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.

Permission

The API key must have the control-plane:service:manage permission.

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"
}