Update ClickHouse settings | ClickHouse Docs

PATCH/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings

Disclaimer: This beta endpoint is evolving; the API contract may change.

Updates one or more ClickHouse settings for the service. To reset a setting to its platform default, use the DELETE single setting endpoint. Use the schema endpoint to discover which settings are configurable.

Authorizations

Authorizationstringheaderrequired
Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path parameters

organizationIdstringrequired
ID of the organization that owns the service.

format: uuid
serviceIdstringrequired
ID of the service.

format: uuid

Request bodyJSON

settingsmap ofServiceClickhouseSettingValuerequired
Nonempty object mapping configurable setting names to their values. Use DELETE to reset a setting.

Example: {"compatibility":"26.2","max_query_size":262144}

Response

JSON

200

Successful response

JSON

statusoptionalnumber
HTTP status code.

Example: 200
requestIdoptionalstring
Unique id assigned to every request. UUIDv4

format: uuid
resultoptionalobject
2 properties
- settingsoptionalmap ofServiceClickhouseSettingValue
  Nonempty object mapping configurable setting names to their values. Use DELETE to reset a setting.
  
  Example: {"compatibility":"26.2","max_query_size":262144}
- warningsoptionalarray ofobject
  Warnings for settings that may have disruptive effects.
  
  2 properties
  nameoptionalstring
  Name of the setting the warning applies to.
  
  Example: "compatibility"
  messageoptionalstring
  Warning message.
  
  Example: "Changing the compatibility version without comprehensive testing can cause query failures or instability."

Update ClickHouse settings

curl --request PATCH \
  --url https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickhouseSettings \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "settings": {
    "compatibility": "26.2",
    "max_query_size": 262144
  }
}
'

const url = 'https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickhouseSettings';
const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <token>'},
  body: JSON.stringify({settings: {compatibility: '26.2', max_query_size: 262144}})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickhouseSettings"

payload = { "settings": {
        "compatibility": "26.2",
        "max_query_size": 262144
    } }
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <token>"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "status": 200,
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "result": {
    "settings": {
      "compatibility": "26.2",
      "max_query_size": 262144
    },
    "warnings": [
      {
        "name": "compatibility",
        "message": "Changing the compatibility version without comprehensive testing can cause query failures or instability."
      }
    ]
  }
}

{
  "status": 400,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

{
  "status": 500,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}