Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

Managed Service for ClickHouse API, REST: Cluster.UpdateShard

Written by
Improved by
Updated at December 17, 2024

Modifies the specified shard.

HTTP request

PATCH https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/{clusterId}/shards/{shardName}

Path parameters

Field

Description

clusterId

string

Required field. ID of the ClickHouse cluster the shard belongs to.
To get the cluster ID, use a ClusterService.List request.

shardName

string

Required field. Name of the shard to be updated.
To get the name of a shard, use a ClusterService.ListShards request.

Body parameters

{
  "updateMask": "object",
  "configSpec": {
    "clickhouse": {
      "config": {
        "logLevel": "string",
        "mergeTree": {
          "replicatedDeduplicationWindow": "string",
          "replicatedDeduplicationWindowSeconds": "string",
          "partsToDelayInsert": "string",
          "partsToThrowInsert": "string",
          "inactivePartsToDelayInsert": "string",
          "inactivePartsToThrowInsert": "string",
          "maxReplicatedMergesInQueue": "string",
          "numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge": "string",
          "maxBytesToMergeAtMinSpaceInPool": "string",
          "maxBytesToMergeAtMaxSpaceInPool": "string",
          "minBytesForWidePart": "string",
          "minRowsForWidePart": "string",
          "ttlOnlyDropParts": "boolean",
          "allowRemoteFsZeroCopyReplication": "boolean",
          "mergeWithTtlTimeout": "string",
          "mergeWithRecompressionTtlTimeout": "string",
          "maxPartsInTotal": "string",
          "maxNumberOfMergesWithTtlInPool": "string",
          "cleanupDelayPeriod": "string",
          "numberOfFreeEntriesInPoolToExecuteMutation": "string",
          "maxAvgPartSizeForTooManyParts": "string",
          "minAgeToForceMergeSeconds": "string",
          "minAgeToForceMergeOnPartitionOnly": "boolean",
          "mergeSelectingSleepMs": "string",
          "mergeMaxBlockSize": "string",
          "checkSampleColumnIsCorrect": "boolean",
          "maxMergeSelectingSleepMs": "string",
          "maxCleanupDelayPeriod": "string"
        },
        "compression": [
          {
            "method": "string",
            "minPartSize": "string",
            "minPartSizeRatio": "string",
            "level": "string"
          }
        ],
        "dictionaries": [
          {
            "name": "string",
            "structure": {
              "id": {
                "name": "string"
              },
              "key": {
                "attributes": [
                  {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  }
                ]
              },
              "rangeMin": {
                "name": "string",
                "type": "string",
                "nullValue": "string",
                "expression": "string",
                "hierarchical": "boolean",
                "injective": "boolean"
              },
              "rangeMax": {
                "name": "string",
                "type": "string",
                "nullValue": "string",
                "expression": "string",
                "hierarchical": "boolean",
                "injective": "boolean"
              },
              "attributes": [
                {
                  "name": "string",
                  "type": "string",
                  "nullValue": "string",
                  "expression": "string",
                  "hierarchical": "boolean",
                  "injective": "boolean"
                }
              ]
            },
            "layout": {
              "type": "string",
              "sizeInCells": "string",
              "maxArraySize": "string"
            },
            // Includes only one of the fields `fixedLifetime`, `lifetimeRange`
            "fixedLifetime": "string",
            "lifetimeRange": {
              "min": "string",
              "max": "string"
            },
            // end of the list of possible fields
            // Includes only one of the fields `httpSource`, `mysqlSource`, `clickhouseSource`, `mongodbSource`, `postgresqlSource`
            "httpSource": {
              "url": "string",
              "format": "string",
              "headers": [
                {
                  "name": "string",
                  "value": "string"
                }
              ]
            },
            "mysqlSource": {
              "db": "string",
              "table": "string",
              "port": "string",
              "user": "string",
              "password": "string",
              "replicas": [
                {
                  "host": "string",
                  "priority": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string"
                }
              ],
              "where": "string",
              "invalidateQuery": "string",
              "closeConnection": "boolean",
              "shareConnection": "boolean"
            },
            "clickhouseSource": {
              "db": "string",
              "table": "string",
              "host": "string",
              "port": "string",
              "user": "string",
              "password": "string",
              "where": "string",
              "secure": "boolean"
            },
            "mongodbSource": {
              "db": "string",
              "collection": "string",
              "host": "string",
              "port": "string",
              "user": "string",
              "password": "string",
              "options": "string"
            },
            "postgresqlSource": {
              "db": "string",
              "table": "string",
              "hosts": [
                "string"
              ],
              "port": "string",
              "user": "string",
              "password": "string",
              "invalidateQuery": "string",
              "sslMode": "string"
            }
            // end of the list of possible fields
          }
        ],
        "graphiteRollup": [
          {
            "name": "string",
            "patterns": [
              {
                "regexp": "string",
                "function": "string",
                "retention": [
                  {
                    "age": "string",
                    "precision": "string"
                  }
                ]
              }
            ],
            "pathColumnName": "string",
            "timeColumnName": "string",
            "valueColumnName": "string",
            "versionColumnName": "string"
          }
        ],
        "kafka": {
          "securityProtocol": "string",
          "saslMechanism": "string",
          "saslUsername": "string",
          "saslPassword": "string",
          "enableSslCertificateVerification": "boolean",
          "maxPollIntervalMs": "string",
          "sessionTimeoutMs": "string",
          "debug": "string",
          "autoOffsetReset": "string"
        },
        "kafkaTopics": [
          {
            "name": "string",
            "settings": {
              "securityProtocol": "string",
              "saslMechanism": "string",
              "saslUsername": "string",
              "saslPassword": "string",
              "enableSslCertificateVerification": "boolean",
              "maxPollIntervalMs": "string",
              "sessionTimeoutMs": "string",
              "debug": "string",
              "autoOffsetReset": "string"
            }
          }
        ],
        "rabbitmq": {
          "username": "string",
          "password": "string",
          "vhost": "string"
        },
        "maxConnections": "string",
        "maxConcurrentQueries": "string",
        "keepAliveTimeout": "string",
        "uncompressedCacheSize": "string",
        "markCacheSize": "string",
        "maxTableSizeToDrop": "string",
        "maxPartitionSizeToDrop": "string",
        "builtinDictionariesReloadInterval": "string",
        "timezone": "string",
        "geobaseEnabled": "boolean",
        "geobaseUri": "string",
        "queryLogRetentionSize": "string",
        "queryLogRetentionTime": "string",
        "queryThreadLogEnabled": "boolean",
        "queryThreadLogRetentionSize": "string",
        "queryThreadLogRetentionTime": "string",
        "partLogRetentionSize": "string",
        "partLogRetentionTime": "string",
        "metricLogEnabled": "boolean",
        "metricLogRetentionSize": "string",
        "metricLogRetentionTime": "string",
        "traceLogEnabled": "boolean",
        "traceLogRetentionSize": "string",
        "traceLogRetentionTime": "string",
        "textLogEnabled": "boolean",
        "textLogRetentionSize": "string",
        "textLogRetentionTime": "string",
        "textLogLevel": "string",
        "opentelemetrySpanLogEnabled": "boolean",
        "opentelemetrySpanLogRetentionSize": "string",
        "opentelemetrySpanLogRetentionTime": "string",
        "queryViewsLogEnabled": "boolean",
        "queryViewsLogRetentionSize": "string",
        "queryViewsLogRetentionTime": "string",
        "asynchronousMetricLogEnabled": "boolean",
        "asynchronousMetricLogRetentionSize": "string",
        "asynchronousMetricLogRetentionTime": "string",
        "sessionLogEnabled": "boolean",
        "sessionLogRetentionSize": "string",
        "sessionLogRetentionTime": "string",
        "zookeeperLogEnabled": "boolean",
        "zookeeperLogRetentionSize": "string",
        "zookeeperLogRetentionTime": "string",
        "asynchronousInsertLogEnabled": "boolean",
        "asynchronousInsertLogRetentionSize": "string",
        "asynchronousInsertLogRetentionTime": "string",
        "backgroundPoolSize": "string",
        "backgroundMergesMutationsConcurrencyRatio": "string",
        "backgroundSchedulePoolSize": "string",
        "backgroundFetchesPoolSize": "string",
        "backgroundMovePoolSize": "string",
        "backgroundDistributedSchedulePoolSize": "string",
        "backgroundBufferFlushSchedulePoolSize": "string",
        "backgroundMessageBrokerSchedulePoolSize": "string",
        "backgroundCommonPoolSize": "string",
        "defaultDatabase": "string",
        "totalMemoryProfilerStep": "string",
        "totalMemoryTrackerSampleProbability": "number",
        "queryMaskingRules": [
          {
            "name": "string",
            "regexp": "string",
            "replace": "string"
          }
        ],
        "dictionariesLazyLoad": "boolean",
        "queryCache": {
          "maxSizeInBytes": "string",
          "maxEntries": "string",
          "maxEntrySizeInBytes": "string",
          "maxEntrySizeInRows": "string"
        }
      },
      "resources": {
        "resourcePresetId": "string",
        "diskSize": "string",
        "diskTypeId": "string"
      },
      "weight": "string"
    }
  }
}

Field

Description

updateMask

object (field-mask)

A comma-separated names off ALL fields to be updated.
Only the specified fields will be changed. The others will be left untouched.
If the field is specified in updateMask and no value for that field was sent in the request,
the field's value will be reset to the default. The default value for most fields is null or 0.

If updateMask is not sent in the request, all fields' values will be updated.
Fields specified in the request will be updated to provided values.
The rest of the fields will be reset to the default.

configSpec

ShardConfigSpec

New configuration for the specified shard.

ShardConfigSpec

Field

Description

clickhouse

Clickhouse

ClickHouse configuration for a shard.

Clickhouse

Field

Description

config

ClickhouseConfig

ClickHouse settings for the shard.

resources

Resources

Computational resources for the shard.

weight

string (int64)

Relative weight of the shard considered when writing data to the cluster.
For details, see ClickHouse documentation.

ClickhouseConfig

ClickHouse configuration options. Detailed description for each set of options
is available in ClickHouse documentation.

Any options not listed here are not supported.

Field

Description

logLevel

enum (LogLevel)

Logging level for the ClickHouse cluster. Possible values: TRACE, DEBUG, INFORMATION, WARNING, ERROR.

  • LOG_LEVEL_UNSPECIFIED
  • TRACE
  • DEBUG
  • INFORMATION
  • WARNING
  • ERROR

mergeTree

MergeTree

Settings for the MergeTree engine.
See description in ClickHouse documentation.

compression[]

Compression

Compression settings for the ClickHouse cluster.
See in-depth description in ClickHouse documentation.

dictionaries[]

ExternalDictionary

Configuration of external dictionaries to be used by the ClickHouse cluster.
See in-depth description in ClickHouse documentation.

graphiteRollup[]

GraphiteRollup

Settings for thinning Graphite data.
See in-depth description in ClickHouse documentation.

kafka

Kafka

kafkaTopics[]

KafkaTopic

rabbitmq

Rabbitmq

maxConnections

string (int64)

Maximum number of inbound connections.

maxConcurrentQueries

string (int64)

Maximum number of simultaneously processed requests.

keepAliveTimeout

string (int64)

Number of milliseconds that ClickHouse waits for incoming requests before closing the connection.

uncompressedCacheSize

string (int64)

Cache size (in bytes) for uncompressed data used by MergeTree tables.

markCacheSize

string (int64)

Approximate size (in bytes) of the cache of "marks" used by MergeTree tables.

maxTableSizeToDrop

string (int64)

Maximum size of the table that can be deleted using a DROP query.

maxPartitionSizeToDrop

string (int64)

Maximum size of the partition that can be deleted using a DROP query.

builtinDictionariesReloadInterval

string (int64)

The setting is deprecated and has no effect.

timezone

string

The server's time zone to be used in DateTime fields conversions. Specified as an IANA identifier.

geobaseEnabled

boolean

Enable or disable geobase.

geobaseUri

string

Address of the archive with the user geobase in Object Storage.

queryLogRetentionSize

string (int64)

The maximum size that query_log can grow to before old data will be removed. If set to 0, automatic removal of
query_log data based on size is disabled.

queryLogRetentionTime

string (int64)

The maximum time that query_log records will be retained before removal. If set to 0, automatic removal of
query_log data based on time is disabled.

queryThreadLogEnabled

boolean

Whether query_thread_log system table is enabled.

queryThreadLogRetentionSize

string (int64)

The maximum size that query_thread_log can grow to before old data will be removed. If set to 0, automatic removal of
query_thread_log data based on size is disabled.

queryThreadLogRetentionTime

string (int64)

The maximum time that query_thread_log records will be retained before removal. If set to 0, automatic removal of
query_thread_log data based on time is disabled.

partLogRetentionSize

string (int64)

The maximum size that part_log can grow to before old data will be removed. If set to 0, automatic removal of
part_log data based on size is disabled.

partLogRetentionTime

string (int64)

The maximum time that part_log records will be retained before removal. If set to 0, automatic removal of
part_log data based on time is disabled.

metricLogEnabled

boolean

Whether metric_log system table is enabled.

metricLogRetentionSize

string (int64)

The maximum size that metric_log can grow to before old data will be removed. If set to 0, automatic removal of
metric_log data based on size is disabled.

metricLogRetentionTime

string (int64)

The maximum time that metric_log records will be retained before removal. If set to 0, automatic removal of
metric_log data based on time is disabled.

traceLogEnabled

boolean

Whether trace_log system table is enabled.

traceLogRetentionSize

string (int64)

The maximum size that trace_log can grow to before old data will be removed. If set to 0, automatic removal of
trace_log data based on size is disabled.

traceLogRetentionTime

string (int64)

The maximum time that trace_log records will be retained before removal. If set to 0, automatic removal of
trace_log data based on time is disabled.

textLogEnabled

boolean

Whether text_log system table is enabled.

textLogRetentionSize

string (int64)

The maximum size that text_log can grow to before old data will be removed. If set to 0, automatic removal of
text_log data based on size is disabled.

textLogRetentionTime

string (int64)

The maximum time that text_log records will be retained before removal. If set to 0, automatic removal of
text_log data based on time is disabled.

textLogLevel

enum (LogLevel)

Logging level for text_log system table. Possible values: TRACE, DEBUG, INFORMATION, WARNING, ERROR.

  • LOG_LEVEL_UNSPECIFIED
  • TRACE
  • DEBUG
  • INFORMATION
  • WARNING
  • ERROR

opentelemetrySpanLogEnabled

boolean

Enable or disable opentelemetry_span_log system table. Default value: false.

opentelemetrySpanLogRetentionSize

string (int64)

The maximum size that opentelemetry_span_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of opentelemetry_span_log data based on size is disabled.

opentelemetrySpanLogRetentionTime

string (int64)

The maximum time that opentelemetry_span_log records will be retained before removal. If set to 0,
automatic removal of opentelemetry_span_log data based on time is disabled.

queryViewsLogEnabled

boolean

Enable or disable query_views_log system table. Default value: false.

queryViewsLogRetentionSize

string (int64)

The maximum size that query_views_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of query_views_log data based on size is disabled.

queryViewsLogRetentionTime

string (int64)

The maximum time that query_views_log records will be retained before removal. If set to 0,
automatic removal of query_views_log data based on time is disabled.

asynchronousMetricLogEnabled

boolean

Enable or disable asynchronous_metric_log system table. Default value: false.

asynchronousMetricLogRetentionSize

string (int64)

The maximum size that asynchronous_metric_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of asynchronous_metric_log data based on size is disabled.

asynchronousMetricLogRetentionTime

string (int64)

The maximum time that asynchronous_metric_log records will be retained before removal. If set to 0,
automatic removal of asynchronous_metric_log data based on time is disabled.

sessionLogEnabled

boolean

Enable or disable session_log system table. Default value: false.

sessionLogRetentionSize

string (int64)

The maximum size that session_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of session_log data based on size is disabled.

sessionLogRetentionTime

string (int64)

The maximum time that session_log records will be retained before removal. If set to 0,
automatic removal of session_log data based on time is disabled.

zookeeperLogEnabled

boolean

Enable or disable zookeeper_log system table. Default value: false.

zookeeperLogRetentionSize

string (int64)

The maximum size that zookeeper_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of zookeeper_log data based on size is disabled.

zookeeperLogRetentionTime

string (int64)

The maximum time that zookeeper_log records will be retained before removal. If set to 0,
automatic removal of zookeeper_log data based on time is disabled.

asynchronousInsertLogEnabled

boolean

Enable or disable asynchronous_insert_log system table. Default value: false.
Minimal required ClickHouse version: 22.10.

asynchronousInsertLogRetentionSize

string (int64)

The maximum size that asynchronous_insert_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of asynchronous_insert_log data based on size is disabled.

asynchronousInsertLogRetentionTime

string (int64)

The maximum time that asynchronous_insert_log records will be retained before removal. If set to 0,
automatic removal of asynchronous_insert_log data based on time is disabled.

backgroundPoolSize

string (int64)

backgroundMergesMutationsConcurrencyRatio

string (int64)

Sets a ratio between the number of threads and the number of background merges and mutations that can be executed concurrently. For example, if the ratio equals to 2 and background_pool_size is set to 16 then ClickHouse can execute 32 background merges concurrently. This is possible, because background operations could be suspended and postponed. This is needed to give small merges more execution priority. You can only increase this ratio at runtime. To lower it you have to restart the server. The same as for background_pool_size setting background_merges_mutations_concurrency_ratio could be applied from the default profile for backward compatibility.
Default: 2
See in-depth description in ClickHouse documentation

backgroundSchedulePoolSize

string (int64)

backgroundFetchesPoolSize

string (int64)

Sets the number of threads performing background fetches for tables with ReplicatedMergeTree engines. Default value: 8.

More info see in ClickHouse documentation.

backgroundMovePoolSize

string (int64)

backgroundDistributedSchedulePoolSize

string (int64)

backgroundBufferFlushSchedulePoolSize

string (int64)

backgroundMessageBrokerSchedulePoolSize

string (int64)

backgroundCommonPoolSize

string (int64)

The maximum number of threads that will be used for performing a variety of operations (mostly garbage collection) for *MergeTree-engine tables in a background.
Default: 8
See in-depth description in ClickHouse documentation

defaultDatabase

string

The default database.

To get a list of cluster databases, see Yandex Managed ClickHouse documentation.

totalMemoryProfilerStep

string (int64)

Sets the memory size (in bytes) for a stack trace at every peak allocation step. Default value: 4194304.

More info see in ClickHouse documentation.

totalMemoryTrackerSampleProbability

number (double)

queryMaskingRules[]

QueryMaskingRule

Regexp-based rules, which will be applied to queries as well as all log messages before storing them in server logs, system.query_log, system.text_log, system.processes tables, and in logs sent to the client. That allows preventing sensitive data leakage from SQL queries (like names, emails, personal identifiers or credit card numbers) to logs.
Change of these settings is applied with ClickHouse restart
See in-depth description in ClickHouse documentation

dictionariesLazyLoad

boolean

Lazy loading of dictionaries.
Default: true
See in-depth description in ClickHouse documentation

queryCache

QueryCache

Query cache configuration.
Min version: 23.5
See in-depth description in ClickHouse documentation

MergeTree

Options specific to the MergeTree table engine.

Field

Description

replicatedDeduplicationWindow

string (int64)

Number of blocks of hashes to keep in ZooKeeper.

replicatedDeduplicationWindowSeconds

string (int64)

Period of time to keep blocks of hashes for.

partsToDelayInsert

string (int64)

If table contains at least that many active parts in single partition, artificially slow down insert into table.

partsToThrowInsert

string (int64)

If more than this number active parts in single partition, throw 'Too many parts ...' exception.

inactivePartsToDelayInsert

string (int64)

inactivePartsToThrowInsert

string (int64)

maxReplicatedMergesInQueue

string (int64)

How many tasks of merging and mutating parts are allowed simultaneously in ReplicatedMergeTree queue.

numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge

string (int64)

If there is less than specified number of free entries in background pool (or replicated queue), start to lower
maximum size of merge to process.

maxBytesToMergeAtMinSpaceInPool

string (int64)

Maximum in total size of parts to merge, when there are minimum free threads in background pool (or entries
in replication queue).

maxBytesToMergeAtMaxSpaceInPool

string (int64)

minBytesForWidePart

string (int64)

Minimum number of bytes in a data part that can be stored in Wide format.

More info see in ClickHouse documentation.

minRowsForWidePart

string (int64)

Minimum number of rows in a data part that can be stored in Wide format.

More info see in ClickHouse documentation.

ttlOnlyDropParts

boolean

Enables or disables complete dropping of data parts where all rows are expired in MergeTree tables.

More info see in ClickHouse documentation.

allowRemoteFsZeroCopyReplication

boolean

mergeWithTtlTimeout

string (int64)

mergeWithRecompressionTtlTimeout

string (int64)

maxPartsInTotal

string (int64)

maxNumberOfMergesWithTtlInPool

string (int64)

cleanupDelayPeriod

string (int64)

numberOfFreeEntriesInPoolToExecuteMutation

string (int64)

maxAvgPartSizeForTooManyParts

string (int64)

The 'too many parts' check according to 'parts_to_delay_insert' and 'parts_to_throw_insert' will be active only if the average part size (in the relevant partition) is not larger than the specified threshold. If it is larger than the specified threshold, the INSERTs will be neither delayed or rejected. This allows to have hundreds of terabytes in a single table on a single server if the parts are successfully merged to larger parts. This does not affect the thresholds on inactive parts or total parts.
Default: 1 GiB
Min version: 22.10
See in-depth description in ClickHouse GitHub

minAgeToForceMergeSeconds

string (int64)

Merge parts if every part in the range is older than the value of min_age_to_force_merge_seconds.
Default: 0 - disabled
Min_version: 22.10
See in-depth description in ClickHouse documentation

minAgeToForceMergeOnPartitionOnly

boolean

Whether min_age_to_force_merge_seconds should be applied only on the entire partition and not on subset.
Default: false
Min_version: 22.11
See in-depth description in ClickHouse documentation

mergeSelectingSleepMs

string (int64)

Sleep time for merge selecting when no part is selected. A lower setting triggers selecting tasks in background_schedule_pool frequently, which results in a large number of requests to ClickHouse Keeper in large-scale clusters.
Default: 5000
Min_version: 21.10
See in-depth description in ClickHouse documentation

mergeMaxBlockSize

string (int64)

The number of rows that are read from the merged parts into memory.
Default: 8192
See in-depth description in ClickHouse documentation

checkSampleColumnIsCorrect

boolean

Enables the check at table creation, that the data type of a column for sampling or sampling expression is correct. The data type must be one of unsigned integer types: UInt8, UInt16, UInt32, UInt64.
Default: true
See in-depth description in ClickHouse documentation

maxMergeSelectingSleepMs

string (int64)

Maximum sleep time for merge selecting, a lower setting will trigger selecting tasks in background_schedule_pool frequently which result in large amount of requests to zookeeper in large-scale clusters.
Default: 60000
Min_version: 23.6
See in-depth description in ClickHouse GitHub

maxCleanupDelayPeriod

string (int64)

Maximum period to clean old queue logs, blocks hashes and parts.
Default: 300
Min_version: 23.6
See in-depth description in ClickHouse GitHub

Compression

Field

Description

method

enum (Method)

Compression method to use for the specified combination of minPartSize and minPartSizeRatio.

minPartSize

string (int64)

Minimum size of a part of a table.

minPartSizeRatio

string

Minimum ratio of a part relative to the size of all the data in the table.

level

string (int64)

ExternalDictionary

Field

Description

name

string

Required field. Name of the external dictionary.

structure

Structure

Required field. Set of attributes for the external dictionary.
For in-depth description, see ClickHouse documentation.

layout

Layout

Required field. Layout for storing the dictionary in memory.
For in-depth description, see ClickHouse documentation.

fixedLifetime

string (int64)

Fixed interval between dictionary updates.

Includes only one of the fields fixedLifetime, lifetimeRange.

Setting for the period of time between dictionary updates.
For details, see ClickHouse documentation.

lifetimeRange

Range

Range of intervals between dictionary updates for ClickHouse to choose from.

Includes only one of the fields fixedLifetime, lifetimeRange.

Setting for the period of time between dictionary updates.
For details, see ClickHouse documentation.

httpSource

HttpSource

HTTP source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

mysqlSource

MysqlSource

MySQL source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

clickhouseSource

ClickhouseSource

ClickHouse source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

mongodbSource

MongodbSource

MongoDB source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

postgresqlSource

PostgresqlSource

PostgreSQL source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

Structure

Field

Description

id

Id

Single numeric key column for the dictionary.

key

Key

Composite key for the dictionary, containing of one or more key columns.
For details, see ClickHouse documentation.

rangeMin

Attribute

Field holding the beginning of the range for dictionaries with RANGE_HASHED layout.
For details, see ClickHouse documentation.

rangeMax

Attribute

Field holding the end of the range for dictionaries with RANGE_HASHED layout.
For details, see ClickHouse documentation.

attributes[]

Attribute

Description of the fields available for database queries.
For details, see ClickHouse documentation.

Id

Numeric key.

Field

Description

name

string

Required field. Name of the numeric key.

Key

Complex key.

Field

Description

attributes[]

Attribute

Attributes of a complex key.

Attribute

Field

Description

name

string

Required field. Name of the column.

type

string

Required field. Type of the column.

nullValue

string

Default value for an element without data (for example, an empty string).

expression

string

Expression, describing the attribute, if applicable.

hierarchical

boolean

Indication of hierarchy support.
Default value: false.

injective

boolean

Indication of injective mapping "id -> attribute".
Default value: false.

Layout

Layout determining how to store the dictionary in memory.

Field

Description

type

enum (Type)

Required field. Layout type for an external dictionary.

  • TYPE_UNSPECIFIED
  • FLAT: The entire dictionary is stored in memory in the form of flat arrays.
    Available for all dictionary sources.
  • HASHED: The entire dictionary is stored in memory in the form of a hash table.
    Available for all dictionary sources.
  • COMPLEX_KEY_HASHED: Similar to HASHED, to be used with composite keys.
    Available for all dictionary sources.
  • RANGE_HASHED: The entire dictionary is stored in memory in the form of a hash table,
    with an ordered array of ranges and their corresponding values.
    Available for all dictionary sources.
  • CACHE: The dictionary is stored in a cache with a set number of cells.
    Available for MySQL, ClickHouse and HTTP dictionary sources.
  • COMPLEX_KEY_CACHE: Similar to CACHE, to be used with composite keys.
    Available for MySQL, ClickHouse and HTTP dictionary sources.

sizeInCells

string (int64)

Number of cells in the cache. Rounded up to a power of two.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

maxArraySize

string (int64)

Maximum dictionary key size.
Applicable only for FLAT layout type.

Range

Field

Description

min

string (int64)

Minimum dictionary lifetime.

max

string (int64)

Maximum dictionary lifetime.

HttpSource

Field

Description

url

string

Required field. URL of the source dictionary available over HTTP.

format

string

Required field. The data format. Valid values are all formats supported by ClickHouse SQL dialect.

headers[]

Header

HTTP headers.

Header

Field

Description

name

string

Required field.

value

string

Required field.

MysqlSource

Field

Description

db

string

Required field. Name of the MySQL database to connect to.

table

string

Required field. Name of the database table to use as a ClickHouse dictionary.

port

string (int64)

Default port to use when connecting to a replica of the dictionary source.

user

string

Name of the default user for replicas of the dictionary source.

password

string

Password of the default user for replicas of the dictionary source.

replicas[]

Replica

List of MySQL replicas of the database used as dictionary source.

where

string

Selection criteria for the data in the specified MySQL table.

invalidateQuery

string

Query for checking the dictionary status, to pull only updated data.
For more details, see ClickHouse documentation on dictionaries.

closeConnection

boolean

Should the connection be closed after each request.

shareConnection

boolean

Should a connection be shared for some requests.

Replica

Field

Description

host

string

Required field. MySQL host of the replica.

priority

string (int64)

Required field. The priority of the replica that ClickHouse takes into account when connecting.
Replica with the highest priority should have this field set to the lowest number.

port

string (int64)

Port to use when connecting to the replica.
If a port is not specified for a replica, ClickHouse uses the port specified for the source.

user

string

Name of the MySQL database user.

password

string

Password of the MySQL database user.

ClickhouseSource

Field

Description

db

string

Required field. Name of the ClickHouse database.

table

string

Required field. Name of the table in the specified database to be used as the dictionary source.

host

string

ClickHouse host of the specified database.

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the ClickHouse database user.

password

string

Password of the ClickHouse database user.

where

string

Selection criteria for the data in the specified ClickHouse table.

secure

boolean

Use ssl for connection.

MongodbSource

Field

Description

db

string

Required field. Name of the MongoDB database.

collection

string

Required field. Name of the collection in the specified database to be used as the dictionary source.

host

string

MongoDB host of the specified database.

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the MongoDB database user.

password

string

Password of the MongoDB database user.

options

string

PostgresqlSource

Field

Description

db

string

Required field. Name of the PostrgreSQL database.

table

string

Required field. Name of the table in the specified database to be used as the dictionary source.

hosts[]

string

Name of the PostrgreSQL host

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the PostrgreSQL database user.

password

string

Password of the PostrgreSQL database user.

invalidateQuery

string

Query for checking the dictionary status, to pull only updated data.
For more details, see ClickHouse documentation on dictionaries.

sslMode

enum (SslMode)

Mode of SSL TCP/IP connection to the PostgreSQL host.
For more details, see PostgreSQL documentation.

  • SSL_MODE_UNSPECIFIED
  • DISABLE: Only try a non-SSL connection.
  • ALLOW: First try a non-SSL connection; if that fails, try an SSL connection.
  • PREFER: First try an SSL connection; if that fails, try a non-SSL connection.
  • VERIFY_CA: Only try an SSL connection, and verify that the server certificate is issued by a trusted certificate authority (CA).
  • VERIFY_FULL: Only try an SSL connection, verify that the server certificate is issued by a trusted CA and that the requested server host name matches that in the certificate.

GraphiteRollup

Rollup settings for the GraphiteMergeTree table engine.

Field

Description

name

string

Required field. Name for the specified combination of settings for Graphite rollup.

patterns[]

Pattern

Pattern to use for the rollup.

pathColumnName

string

The name of the column storing the metric name (Graphite sensor).
Default: Path
See in-depth description in ClickHouse documentation

timeColumnName

string

The name of the column storing the time of measuring the metric.
Default: Time
See in-depth description in ClickHouse documentation

valueColumnName

string

The name of the column storing the value of the metric at the time set in time_column_name.
Default: Value
See in-depth description in ClickHouse documentation

versionColumnName

string

The name of the column storing the version of the metric.
Default: Timestamp
See in-depth description in ClickHouse documentation

Pattern

Field

Description

regexp

string

Pattern for metric names.

function

string

Required field. Name of the aggregating function to apply to data of the age specified in retention.

retention[]

Retention

Age of data to use for thinning.

Retention

Field

Description

age

string (int64)

Minimum age of the data in seconds.

precision

string (int64)

Precision of determining the age of the data, in seconds.

Kafka

Field

Description

securityProtocol

enum (SecurityProtocol)

  • SECURITY_PROTOCOL_UNSPECIFIED
  • SECURITY_PROTOCOL_PLAINTEXT
  • SECURITY_PROTOCOL_SSL
  • SECURITY_PROTOCOL_SASL_PLAINTEXT
  • SECURITY_PROTOCOL_SASL_SSL

saslMechanism

enum (SaslMechanism)

  • SASL_MECHANISM_UNSPECIFIED
  • SASL_MECHANISM_GSSAPI
  • SASL_MECHANISM_PLAIN
  • SASL_MECHANISM_SCRAM_SHA_256
  • SASL_MECHANISM_SCRAM_SHA_512

saslUsername

string

saslPassword

string

enableSslCertificateVerification

boolean

maxPollIntervalMs

string (int64)

sessionTimeoutMs

string (int64)

debug

enum (Debug)

  • DEBUG_UNSPECIFIED
  • DEBUG_GENERIC
  • DEBUG_BROKER
  • DEBUG_TOPIC
  • DEBUG_METADATA
  • DEBUG_FEATURE
  • DEBUG_QUEUE
  • DEBUG_MSG
  • DEBUG_PROTOCOL
  • DEBUG_CGRP
  • DEBUG_SECURITY
  • DEBUG_FETCH
  • DEBUG_INTERCEPTOR
  • DEBUG_PLUGIN
  • DEBUG_CONSUMER
  • DEBUG_ADMIN
  • DEBUG_EOS
  • DEBUG_MOCK
  • DEBUG_ASSIGNOR
  • DEBUG_CONF
  • DEBUG_TELEMETRY
  • DEBUG_ALL

autoOffsetReset

enum (AutoOffsetReset)

  • AUTO_OFFSET_RESET_UNSPECIFIED
  • AUTO_OFFSET_RESET_SMALLEST
  • AUTO_OFFSET_RESET_EARLIEST
  • AUTO_OFFSET_RESET_BEGINNING
  • AUTO_OFFSET_RESET_LARGEST
  • AUTO_OFFSET_RESET_LATEST
  • AUTO_OFFSET_RESET_END
  • AUTO_OFFSET_RESET_ERROR

KafkaTopic

Field

Description

name

string

Required field.

settings

Kafka

Required field.

Rabbitmq

Field

Description

username

string

RabbitMQ username

password

string

RabbitMQ password

vhost

string

RabbitMQ virtual host

QueryMaskingRule

Field

Description

name

string

Name for the rule.

regexp

string

Required field. RE2 compatible regular expression.
Required.

replace

string

Substitution string for sensitive data.
Default: six asterisks

QueryCache

Field

Description

maxSizeInBytes

string (int64)

The maximum cache size in bytes.
Default: 1073741824 (1 GiB)

maxEntries

string (int64)

The maximum number of SELECT query results stored in the cache.
Default: 1024

maxEntrySizeInBytes

string (int64)

The maximum size in bytes SELECT query results may have to be saved in the cache.
Dafault: 1048576 (1 MiB)

maxEntrySizeInRows

string (int64)

The maximum number of rows SELECT query results may have to be saved in the cache.
Default: 30000000 (30 mil)

Resources

Field

Description

resourcePresetId

string

ID of the preset for computational resources available to a host (CPU, memory etc.).
All available presets are listed in the documentation

diskSize

string (int64)

Volume of the storage available to a host, in bytes.

diskTypeId

string

Type of the storage environment for the host.
Possible values:

  • network-hdd - network HDD drive,
  • network-ssd - network SSD drive,
  • local-ssd - local SSD storage.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": "boolean",
  "metadata": {
    "clusterId": "string",
    "shardName": "string"
  },
  // Includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": {
    "name": "string",
    "clusterId": "string",
    "config": {
      "clickhouse": {
        "config": {
          "effectiveConfig": {
            "logLevel": "string",
            "mergeTree": {
              "replicatedDeduplicationWindow": "string",
              "replicatedDeduplicationWindowSeconds": "string",
              "partsToDelayInsert": "string",
              "partsToThrowInsert": "string",
              "inactivePartsToDelayInsert": "string",
              "inactivePartsToThrowInsert": "string",
              "maxReplicatedMergesInQueue": "string",
              "numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge": "string",
              "maxBytesToMergeAtMinSpaceInPool": "string",
              "maxBytesToMergeAtMaxSpaceInPool": "string",
              "minBytesForWidePart": "string",
              "minRowsForWidePart": "string",
              "ttlOnlyDropParts": "boolean",
              "allowRemoteFsZeroCopyReplication": "boolean",
              "mergeWithTtlTimeout": "string",
              "mergeWithRecompressionTtlTimeout": "string",
              "maxPartsInTotal": "string",
              "maxNumberOfMergesWithTtlInPool": "string",
              "cleanupDelayPeriod": "string",
              "numberOfFreeEntriesInPoolToExecuteMutation": "string",
              "maxAvgPartSizeForTooManyParts": "string",
              "minAgeToForceMergeSeconds": "string",
              "minAgeToForceMergeOnPartitionOnly": "boolean",
              "mergeSelectingSleepMs": "string",
              "mergeMaxBlockSize": "string",
              "checkSampleColumnIsCorrect": "boolean",
              "maxMergeSelectingSleepMs": "string",
              "maxCleanupDelayPeriod": "string"
            },
            "compression": [
              {
                "method": "string",
                "minPartSize": "string",
                "minPartSizeRatio": "string",
                "level": "string"
              }
            ],
            "dictionaries": [
              {
                "name": "string",
                "structure": {
                  "id": {
                    "name": "string"
                  },
                  "key": {
                    "attributes": [
                      {
                        "name": "string",
                        "type": "string",
                        "nullValue": "string",
                        "expression": "string",
                        "hierarchical": "boolean",
                        "injective": "boolean"
                      }
                    ]
                  },
                  "rangeMin": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "rangeMax": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "attributes": [
                    {
                      "name": "string",
                      "type": "string",
                      "nullValue": "string",
                      "expression": "string",
                      "hierarchical": "boolean",
                      "injective": "boolean"
                    }
                  ]
                },
                "layout": {
                  "type": "string",
                  "sizeInCells": "string",
                  "maxArraySize": "string"
                },
                // Includes only one of the fields `fixedLifetime`, `lifetimeRange`
                "fixedLifetime": "string",
                "lifetimeRange": {
                  "min": "string",
                  "max": "string"
                },
                // end of the list of possible fields
                // Includes only one of the fields `httpSource`, `mysqlSource`, `clickhouseSource`, `mongodbSource`, `postgresqlSource`
                "httpSource": {
                  "url": "string",
                  "format": "string",
                  "headers": [
                    {
                      "name": "string",
                      "value": "string"
                    }
                  ]
                },
                "mysqlSource": {
                  "db": "string",
                  "table": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "replicas": [
                    {
                      "host": "string",
                      "priority": "string",
                      "port": "string",
                      "user": "string",
                      "password": "string"
                    }
                  ],
                  "where": "string",
                  "invalidateQuery": "string",
                  "closeConnection": "boolean",
                  "shareConnection": "boolean"
                },
                "clickhouseSource": {
                  "db": "string",
                  "table": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "where": "string",
                  "secure": "boolean"
                },
                "mongodbSource": {
                  "db": "string",
                  "collection": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "options": "string"
                },
                "postgresqlSource": {
                  "db": "string",
                  "table": "string",
                  "hosts": [
                    "string"
                  ],
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "invalidateQuery": "string",
                  "sslMode": "string"
                }
                // end of the list of possible fields
              }
            ],
            "graphiteRollup": [
              {
                "name": "string",
                "patterns": [
                  {
                    "regexp": "string",
                    "function": "string",
                    "retention": [
                      {
                        "age": "string",
                        "precision": "string"
                      }
                    ]
                  }
                ],
                "pathColumnName": "string",
                "timeColumnName": "string",
                "valueColumnName": "string",
                "versionColumnName": "string"
              }
            ],
            "kafka": {
              "securityProtocol": "string",
              "saslMechanism": "string",
              "saslUsername": "string",
              "saslPassword": "string",
              "enableSslCertificateVerification": "boolean",
              "maxPollIntervalMs": "string",
              "sessionTimeoutMs": "string",
              "debug": "string",
              "autoOffsetReset": "string"
            },
            "kafkaTopics": [
              {
                "name": "string",
                "settings": {
                  "securityProtocol": "string",
                  "saslMechanism": "string",
                  "saslUsername": "string",
                  "saslPassword": "string",
                  "enableSslCertificateVerification": "boolean",
                  "maxPollIntervalMs": "string",
                  "sessionTimeoutMs": "string",
                  "debug": "string",
                  "autoOffsetReset": "string"
                }
              }
            ],
            "rabbitmq": {
              "username": "string",
              "password": "string",
              "vhost": "string"
            },
            "maxConnections": "string",
            "maxConcurrentQueries": "string",
            "keepAliveTimeout": "string",
            "uncompressedCacheSize": "string",
            "markCacheSize": "string",
            "maxTableSizeToDrop": "string",
            "maxPartitionSizeToDrop": "string",
            "builtinDictionariesReloadInterval": "string",
            "timezone": "string",
            "geobaseEnabled": "boolean",
            "geobaseUri": "string",
            "queryLogRetentionSize": "string",
            "queryLogRetentionTime": "string",
            "queryThreadLogEnabled": "boolean",
            "queryThreadLogRetentionSize": "string",
            "queryThreadLogRetentionTime": "string",
            "partLogRetentionSize": "string",
            "partLogRetentionTime": "string",
            "metricLogEnabled": "boolean",
            "metricLogRetentionSize": "string",
            "metricLogRetentionTime": "string",
            "traceLogEnabled": "boolean",
            "traceLogRetentionSize": "string",
            "traceLogRetentionTime": "string",
            "textLogEnabled": "boolean",
            "textLogRetentionSize": "string",
            "textLogRetentionTime": "string",
            "textLogLevel": "string",
            "opentelemetrySpanLogEnabled": "boolean",
            "opentelemetrySpanLogRetentionSize": "string",
            "opentelemetrySpanLogRetentionTime": "string",
            "queryViewsLogEnabled": "boolean",
            "queryViewsLogRetentionSize": "string",
            "queryViewsLogRetentionTime": "string",
            "asynchronousMetricLogEnabled": "boolean",
            "asynchronousMetricLogRetentionSize": "string",
            "asynchronousMetricLogRetentionTime": "string",
            "sessionLogEnabled": "boolean",
            "sessionLogRetentionSize": "string",
            "sessionLogRetentionTime": "string",
            "zookeeperLogEnabled": "boolean",
            "zookeeperLogRetentionSize": "string",
            "zookeeperLogRetentionTime": "string",
            "asynchronousInsertLogEnabled": "boolean",
            "asynchronousInsertLogRetentionSize": "string",
            "asynchronousInsertLogRetentionTime": "string",
            "backgroundPoolSize": "string",
            "backgroundMergesMutationsConcurrencyRatio": "string",
            "backgroundSchedulePoolSize": "string",
            "backgroundFetchesPoolSize": "string",
            "backgroundMovePoolSize": "string",
            "backgroundDistributedSchedulePoolSize": "string",
            "backgroundBufferFlushSchedulePoolSize": "string",
            "backgroundMessageBrokerSchedulePoolSize": "string",
            "backgroundCommonPoolSize": "string",
            "defaultDatabase": "string",
            "totalMemoryProfilerStep": "string",
            "totalMemoryTrackerSampleProbability": "number",
            "queryMaskingRules": [
              {
                "name": "string",
                "regexp": "string",
                "replace": "string"
              }
            ],
            "dictionariesLazyLoad": "boolean",
            "queryCache": {
              "maxSizeInBytes": "string",
              "maxEntries": "string",
              "maxEntrySizeInBytes": "string",
              "maxEntrySizeInRows": "string"
            }
          },
          "userConfig": {
            "logLevel": "string",
            "mergeTree": {
              "replicatedDeduplicationWindow": "string",
              "replicatedDeduplicationWindowSeconds": "string",
              "partsToDelayInsert": "string",
              "partsToThrowInsert": "string",
              "inactivePartsToDelayInsert": "string",
              "inactivePartsToThrowInsert": "string",
              "maxReplicatedMergesInQueue": "string",
              "numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge": "string",
              "maxBytesToMergeAtMinSpaceInPool": "string",
              "maxBytesToMergeAtMaxSpaceInPool": "string",
              "minBytesForWidePart": "string",
              "minRowsForWidePart": "string",
              "ttlOnlyDropParts": "boolean",
              "allowRemoteFsZeroCopyReplication": "boolean",
              "mergeWithTtlTimeout": "string",
              "mergeWithRecompressionTtlTimeout": "string",
              "maxPartsInTotal": "string",
              "maxNumberOfMergesWithTtlInPool": "string",
              "cleanupDelayPeriod": "string",
              "numberOfFreeEntriesInPoolToExecuteMutation": "string",
              "maxAvgPartSizeForTooManyParts": "string",
              "minAgeToForceMergeSeconds": "string",
              "minAgeToForceMergeOnPartitionOnly": "boolean",
              "mergeSelectingSleepMs": "string",
              "mergeMaxBlockSize": "string",
              "checkSampleColumnIsCorrect": "boolean",
              "maxMergeSelectingSleepMs": "string",
              "maxCleanupDelayPeriod": "string"
            },
            "compression": [
              {
                "method": "string",
                "minPartSize": "string",
                "minPartSizeRatio": "string",
                "level": "string"
              }
            ],
            "dictionaries": [
              {
                "name": "string",
                "structure": {
                  "id": {
                    "name": "string"
                  },
                  "key": {
                    "attributes": [
                      {
                        "name": "string",
                        "type": "string",
                        "nullValue": "string",
                        "expression": "string",
                        "hierarchical": "boolean",
                        "injective": "boolean"
                      }
                    ]
                  },
                  "rangeMin": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "rangeMax": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "attributes": [
                    {
                      "name": "string",
                      "type": "string",
                      "nullValue": "string",
                      "expression": "string",
                      "hierarchical": "boolean",
                      "injective": "boolean"
                    }
                  ]
                },
                "layout": {
                  "type": "string",
                  "sizeInCells": "string",
                  "maxArraySize": "string"
                },
                // Includes only one of the fields `fixedLifetime`, `lifetimeRange`
                "fixedLifetime": "string",
                "lifetimeRange": {
                  "min": "string",
                  "max": "string"
                },
                // end of the list of possible fields
                // Includes only one of the fields `httpSource`, `mysqlSource`, `clickhouseSource`, `mongodbSource`, `postgresqlSource`
                "httpSource": {
                  "url": "string",
                  "format": "string",
                  "headers": [
                    {
                      "name": "string",
                      "value": "string"
                    }
                  ]
                },
                "mysqlSource": {
                  "db": "string",
                  "table": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "replicas": [
                    {
                      "host": "string",
                      "priority": "string",
                      "port": "string",
                      "user": "string",
                      "password": "string"
                    }
                  ],
                  "where": "string",
                  "invalidateQuery": "string",
                  "closeConnection": "boolean",
                  "shareConnection": "boolean"
                },
                "clickhouseSource": {
                  "db": "string",
                  "table": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "where": "string",
                  "secure": "boolean"
                },
                "mongodbSource": {
                  "db": "string",
                  "collection": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "options": "string"
                },
                "postgresqlSource": {
                  "db": "string",
                  "table": "string",
                  "hosts": [
                    "string"
                  ],
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "invalidateQuery": "string",
                  "sslMode": "string"
                }
                // end of the list of possible fields
              }
            ],
            "graphiteRollup": [
              {
                "name": "string",
                "patterns": [
                  {
                    "regexp": "string",
                    "function": "string",
                    "retention": [
                      {
                        "age": "string",
                        "precision": "string"
                      }
                    ]
                  }
                ],
                "pathColumnName": "string",
                "timeColumnName": "string",
                "valueColumnName": "string",
                "versionColumnName": "string"
              }
            ],
            "kafka": {
              "securityProtocol": "string",
              "saslMechanism": "string",
              "saslUsername": "string",
              "saslPassword": "string",
              "enableSslCertificateVerification": "boolean",
              "maxPollIntervalMs": "string",
              "sessionTimeoutMs": "string",
              "debug": "string",
              "autoOffsetReset": "string"
            },
            "kafkaTopics": [
              {
                "name": "string",
                "settings": {
                  "securityProtocol": "string",
                  "saslMechanism": "string",
                  "saslUsername": "string",
                  "saslPassword": "string",
                  "enableSslCertificateVerification": "boolean",
                  "maxPollIntervalMs": "string",
                  "sessionTimeoutMs": "string",
                  "debug": "string",
                  "autoOffsetReset": "string"
                }
              }
            ],
            "rabbitmq": {
              "username": "string",
              "password": "string",
              "vhost": "string"
            },
            "maxConnections": "string",
            "maxConcurrentQueries": "string",
            "keepAliveTimeout": "string",
            "uncompressedCacheSize": "string",
            "markCacheSize": "string",
            "maxTableSizeToDrop": "string",
            "maxPartitionSizeToDrop": "string",
            "builtinDictionariesReloadInterval": "string",
            "timezone": "string",
            "geobaseEnabled": "boolean",
            "geobaseUri": "string",
            "queryLogRetentionSize": "string",
            "queryLogRetentionTime": "string",
            "queryThreadLogEnabled": "boolean",
            "queryThreadLogRetentionSize": "string",
            "queryThreadLogRetentionTime": "string",
            "partLogRetentionSize": "string",
            "partLogRetentionTime": "string",
            "metricLogEnabled": "boolean",
            "metricLogRetentionSize": "string",
            "metricLogRetentionTime": "string",
            "traceLogEnabled": "boolean",
            "traceLogRetentionSize": "string",
            "traceLogRetentionTime": "string",
            "textLogEnabled": "boolean",
            "textLogRetentionSize": "string",
            "textLogRetentionTime": "string",
            "textLogLevel": "string",
            "opentelemetrySpanLogEnabled": "boolean",
            "opentelemetrySpanLogRetentionSize": "string",
            "opentelemetrySpanLogRetentionTime": "string",
            "queryViewsLogEnabled": "boolean",
            "queryViewsLogRetentionSize": "string",
            "queryViewsLogRetentionTime": "string",
            "asynchronousMetricLogEnabled": "boolean",
            "asynchronousMetricLogRetentionSize": "string",
            "asynchronousMetricLogRetentionTime": "string",
            "sessionLogEnabled": "boolean",
            "sessionLogRetentionSize": "string",
            "sessionLogRetentionTime": "string",
            "zookeeperLogEnabled": "boolean",
            "zookeeperLogRetentionSize": "string",
            "zookeeperLogRetentionTime": "string",
            "asynchronousInsertLogEnabled": "boolean",
            "asynchronousInsertLogRetentionSize": "string",
            "asynchronousInsertLogRetentionTime": "string",
            "backgroundPoolSize": "string",
            "backgroundMergesMutationsConcurrencyRatio": "string",
            "backgroundSchedulePoolSize": "string",
            "backgroundFetchesPoolSize": "string",
            "backgroundMovePoolSize": "string",
            "backgroundDistributedSchedulePoolSize": "string",
            "backgroundBufferFlushSchedulePoolSize": "string",
            "backgroundMessageBrokerSchedulePoolSize": "string",
            "backgroundCommonPoolSize": "string",
            "defaultDatabase": "string",
            "totalMemoryProfilerStep": "string",
            "totalMemoryTrackerSampleProbability": "number",
            "queryMaskingRules": [
              {
                "name": "string",
                "regexp": "string",
                "replace": "string"
              }
            ],
            "dictionariesLazyLoad": "boolean",
            "queryCache": {
              "maxSizeInBytes": "string",
              "maxEntries": "string",
              "maxEntrySizeInBytes": "string",
              "maxEntrySizeInRows": "string"
            }
          },
          "defaultConfig": {
            "logLevel": "string",
            "mergeTree": {
              "replicatedDeduplicationWindow": "string",
              "replicatedDeduplicationWindowSeconds": "string",
              "partsToDelayInsert": "string",
              "partsToThrowInsert": "string",
              "inactivePartsToDelayInsert": "string",
              "inactivePartsToThrowInsert": "string",
              "maxReplicatedMergesInQueue": "string",
              "numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge": "string",
              "maxBytesToMergeAtMinSpaceInPool": "string",
              "maxBytesToMergeAtMaxSpaceInPool": "string",
              "minBytesForWidePart": "string",
              "minRowsForWidePart": "string",
              "ttlOnlyDropParts": "boolean",
              "allowRemoteFsZeroCopyReplication": "boolean",
              "mergeWithTtlTimeout": "string",
              "mergeWithRecompressionTtlTimeout": "string",
              "maxPartsInTotal": "string",
              "maxNumberOfMergesWithTtlInPool": "string",
              "cleanupDelayPeriod": "string",
              "numberOfFreeEntriesInPoolToExecuteMutation": "string",
              "maxAvgPartSizeForTooManyParts": "string",
              "minAgeToForceMergeSeconds": "string",
              "minAgeToForceMergeOnPartitionOnly": "boolean",
              "mergeSelectingSleepMs": "string",
              "mergeMaxBlockSize": "string",
              "checkSampleColumnIsCorrect": "boolean",
              "maxMergeSelectingSleepMs": "string",
              "maxCleanupDelayPeriod": "string"
            },
            "compression": [
              {
                "method": "string",
                "minPartSize": "string",
                "minPartSizeRatio": "string",
                "level": "string"
              }
            ],
            "dictionaries": [
              {
                "name": "string",
                "structure": {
                  "id": {
                    "name": "string"
                  },
                  "key": {
                    "attributes": [
                      {
                        "name": "string",
                        "type": "string",
                        "nullValue": "string",
                        "expression": "string",
                        "hierarchical": "boolean",
                        "injective": "boolean"
                      }
                    ]
                  },
                  "rangeMin": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "rangeMax": {
                    "name": "string",
                    "type": "string",
                    "nullValue": "string",
                    "expression": "string",
                    "hierarchical": "boolean",
                    "injective": "boolean"
                  },
                  "attributes": [
                    {
                      "name": "string",
                      "type": "string",
                      "nullValue": "string",
                      "expression": "string",
                      "hierarchical": "boolean",
                      "injective": "boolean"
                    }
                  ]
                },
                "layout": {
                  "type": "string",
                  "sizeInCells": "string",
                  "maxArraySize": "string"
                },
                // Includes only one of the fields `fixedLifetime`, `lifetimeRange`
                "fixedLifetime": "string",
                "lifetimeRange": {
                  "min": "string",
                  "max": "string"
                },
                // end of the list of possible fields
                // Includes only one of the fields `httpSource`, `mysqlSource`, `clickhouseSource`, `mongodbSource`, `postgresqlSource`
                "httpSource": {
                  "url": "string",
                  "format": "string",
                  "headers": [
                    {
                      "name": "string",
                      "value": "string"
                    }
                  ]
                },
                "mysqlSource": {
                  "db": "string",
                  "table": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "replicas": [
                    {
                      "host": "string",
                      "priority": "string",
                      "port": "string",
                      "user": "string",
                      "password": "string"
                    }
                  ],
                  "where": "string",
                  "invalidateQuery": "string",
                  "closeConnection": "boolean",
                  "shareConnection": "boolean"
                },
                "clickhouseSource": {
                  "db": "string",
                  "table": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "where": "string",
                  "secure": "boolean"
                },
                "mongodbSource": {
                  "db": "string",
                  "collection": "string",
                  "host": "string",
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "options": "string"
                },
                "postgresqlSource": {
                  "db": "string",
                  "table": "string",
                  "hosts": [
                    "string"
                  ],
                  "port": "string",
                  "user": "string",
                  "password": "string",
                  "invalidateQuery": "string",
                  "sslMode": "string"
                }
                // end of the list of possible fields
              }
            ],
            "graphiteRollup": [
              {
                "name": "string",
                "patterns": [
                  {
                    "regexp": "string",
                    "function": "string",
                    "retention": [
                      {
                        "age": "string",
                        "precision": "string"
                      }
                    ]
                  }
                ],
                "pathColumnName": "string",
                "timeColumnName": "string",
                "valueColumnName": "string",
                "versionColumnName": "string"
              }
            ],
            "kafka": {
              "securityProtocol": "string",
              "saslMechanism": "string",
              "saslUsername": "string",
              "saslPassword": "string",
              "enableSslCertificateVerification": "boolean",
              "maxPollIntervalMs": "string",
              "sessionTimeoutMs": "string",
              "debug": "string",
              "autoOffsetReset": "string"
            },
            "kafkaTopics": [
              {
                "name": "string",
                "settings": {
                  "securityProtocol": "string",
                  "saslMechanism": "string",
                  "saslUsername": "string",
                  "saslPassword": "string",
                  "enableSslCertificateVerification": "boolean",
                  "maxPollIntervalMs": "string",
                  "sessionTimeoutMs": "string",
                  "debug": "string",
                  "autoOffsetReset": "string"
                }
              }
            ],
            "rabbitmq": {
              "username": "string",
              "password": "string",
              "vhost": "string"
            },
            "maxConnections": "string",
            "maxConcurrentQueries": "string",
            "keepAliveTimeout": "string",
            "uncompressedCacheSize": "string",
            "markCacheSize": "string",
            "maxTableSizeToDrop": "string",
            "maxPartitionSizeToDrop": "string",
            "builtinDictionariesReloadInterval": "string",
            "timezone": "string",
            "geobaseEnabled": "boolean",
            "geobaseUri": "string",
            "queryLogRetentionSize": "string",
            "queryLogRetentionTime": "string",
            "queryThreadLogEnabled": "boolean",
            "queryThreadLogRetentionSize": "string",
            "queryThreadLogRetentionTime": "string",
            "partLogRetentionSize": "string",
            "partLogRetentionTime": "string",
            "metricLogEnabled": "boolean",
            "metricLogRetentionSize": "string",
            "metricLogRetentionTime": "string",
            "traceLogEnabled": "boolean",
            "traceLogRetentionSize": "string",
            "traceLogRetentionTime": "string",
            "textLogEnabled": "boolean",
            "textLogRetentionSize": "string",
            "textLogRetentionTime": "string",
            "textLogLevel": "string",
            "opentelemetrySpanLogEnabled": "boolean",
            "opentelemetrySpanLogRetentionSize": "string",
            "opentelemetrySpanLogRetentionTime": "string",
            "queryViewsLogEnabled": "boolean",
            "queryViewsLogRetentionSize": "string",
            "queryViewsLogRetentionTime": "string",
            "asynchronousMetricLogEnabled": "boolean",
            "asynchronousMetricLogRetentionSize": "string",
            "asynchronousMetricLogRetentionTime": "string",
            "sessionLogEnabled": "boolean",
            "sessionLogRetentionSize": "string",
            "sessionLogRetentionTime": "string",
            "zookeeperLogEnabled": "boolean",
            "zookeeperLogRetentionSize": "string",
            "zookeeperLogRetentionTime": "string",
            "asynchronousInsertLogEnabled": "boolean",
            "asynchronousInsertLogRetentionSize": "string",
            "asynchronousInsertLogRetentionTime": "string",
            "backgroundPoolSize": "string",
            "backgroundMergesMutationsConcurrencyRatio": "string",
            "backgroundSchedulePoolSize": "string",
            "backgroundFetchesPoolSize": "string",
            "backgroundMovePoolSize": "string",
            "backgroundDistributedSchedulePoolSize": "string",
            "backgroundBufferFlushSchedulePoolSize": "string",
            "backgroundMessageBrokerSchedulePoolSize": "string",
            "backgroundCommonPoolSize": "string",
            "defaultDatabase": "string",
            "totalMemoryProfilerStep": "string",
            "totalMemoryTrackerSampleProbability": "number",
            "queryMaskingRules": [
              {
                "name": "string",
                "regexp": "string",
                "replace": "string"
              }
            ],
            "dictionariesLazyLoad": "boolean",
            "queryCache": {
              "maxSizeInBytes": "string",
              "maxEntries": "string",
              "maxEntrySizeInBytes": "string",
              "maxEntrySizeInRows": "string"
            }
          }
        },
        "resources": {
          "resourcePresetId": "string",
          "diskSize": "string",
          "diskTypeId": "string"
        },
        "weight": "string"
      }
    }
  }
  // end of the list of possible fields
}

An Operation resource. For more information, see Operation.

Field

Description

id

string

ID of the operation.

description

string

Description of the operation. 0-256 characters long.

createdAt

string (date-time)

Creation timestamp.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

createdBy

string

ID of the user or service account who initiated the operation.

modifiedAt

string (date-time)

The time when the Operation resource was last modified.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

done

boolean

If the value is false, it means the operation is still in progress.
If true, the operation is completed, and either error or response is available.

metadata

UpdateClusterShardMetadata

Service-specific metadata associated with the operation.
It typically contains the ID of the target resource that the operation is performed on.
Any method that returns a long-running operation should document the metadata type, if any.

error

Status

The error result of the operation in case of failure or cancellation.

Includes only one of the fields error, response.

The operation result.
If done == false and there was no failure detected, neither error nor response is set.
If done == false and there was a failure detected, error is set.
If done == true, exactly one of error or response is set.

response

Shard

The normal response of the operation in case of success.
If the original method returns no data on success, such as Delete,
the response is google.protobuf.Empty.
If the original method is the standard Create/Update,
the response should be the target resource of the operation.
Any method that returns a long-running operation should document the response type, if any.

Includes only one of the fields error, response.

The operation result.
If done == false and there was no failure detected, neither error nor response is set.
If done == false and there was a failure detected, error is set.
If done == true, exactly one of error or response is set.

UpdateClusterShardMetadata

Field

Description

clusterId

string

ID of the cluster that contains the shard being updated.

shardName

string

Name of the shard being updated.

Status

The error result of the operation in case of failure or cancellation.

Field

Description

code

integer (int32)

Error code. An enum value of google.rpc.Code.

message

string

An error message.

details[]

object

A list of messages that carry the error details.

Shard

Field

Description

name

string

Name of the shard.

clusterId

string

ID of the cluster that the shard belongs to.

config

ShardConfig

Configuration of the shard.

ShardConfig

Field

Description

clickhouse

Clickhouse

ClickHouse configuration for a shard.

Clickhouse

Field

Description

config

ClickhouseConfigSet

ClickHouse settings for a shard.

resources

Resources

Computational resources for a shard.

weight

string (int64)

Relative weight of a shard considered when writing data to the cluster.
For details, see ClickHouse documentation.

ClickhouseConfigSet

Field

Description

effectiveConfig

ClickhouseConfig

Required field. Effective settings for a ClickHouse cluster (a combination of settings defined
in userConfig and defaultConfig).

userConfig

ClickhouseConfig

User-defined settings for a ClickHouse cluster.

defaultConfig

ClickhouseConfig

Default configuration for a ClickHouse cluster.

ClickhouseConfig

ClickHouse configuration options. Detailed description for each set of options
is available in ClickHouse documentation.

Any options not listed here are not supported.

Field

Description

logLevel

enum (LogLevel)

Logging level for the ClickHouse cluster. Possible values: TRACE, DEBUG, INFORMATION, WARNING, ERROR.

  • LOG_LEVEL_UNSPECIFIED
  • TRACE
  • DEBUG
  • INFORMATION
  • WARNING
  • ERROR

mergeTree

MergeTree

Settings for the MergeTree engine.
See description in ClickHouse documentation.

compression[]

Compression

Compression settings for the ClickHouse cluster.
See in-depth description in ClickHouse documentation.

dictionaries[]

ExternalDictionary

Configuration of external dictionaries to be used by the ClickHouse cluster.
See in-depth description in ClickHouse documentation.

graphiteRollup[]

GraphiteRollup

Settings for thinning Graphite data.
See in-depth description in ClickHouse documentation.

kafka

Kafka

kafkaTopics[]

KafkaTopic

rabbitmq

Rabbitmq

maxConnections

string (int64)

Maximum number of inbound connections.

maxConcurrentQueries

string (int64)

Maximum number of simultaneously processed requests.

keepAliveTimeout

string (int64)

Number of milliseconds that ClickHouse waits for incoming requests before closing the connection.

uncompressedCacheSize

string (int64)

Cache size (in bytes) for uncompressed data used by MergeTree tables.

markCacheSize

string (int64)

Approximate size (in bytes) of the cache of "marks" used by MergeTree tables.

maxTableSizeToDrop

string (int64)

Maximum size of the table that can be deleted using a DROP query.

maxPartitionSizeToDrop

string (int64)

Maximum size of the partition that can be deleted using a DROP query.

builtinDictionariesReloadInterval

string (int64)

The setting is deprecated and has no effect.

timezone

string

The server's time zone to be used in DateTime fields conversions. Specified as an IANA identifier.

geobaseEnabled

boolean

Enable or disable geobase.

geobaseUri

string

Address of the archive with the user geobase in Object Storage.

queryLogRetentionSize

string (int64)

The maximum size that query_log can grow to before old data will be removed. If set to 0, automatic removal of
query_log data based on size is disabled.

queryLogRetentionTime

string (int64)

The maximum time that query_log records will be retained before removal. If set to 0, automatic removal of
query_log data based on time is disabled.

queryThreadLogEnabled

boolean

Whether query_thread_log system table is enabled.

queryThreadLogRetentionSize

string (int64)

The maximum size that query_thread_log can grow to before old data will be removed. If set to 0, automatic removal of
query_thread_log data based on size is disabled.

queryThreadLogRetentionTime

string (int64)

The maximum time that query_thread_log records will be retained before removal. If set to 0, automatic removal of
query_thread_log data based on time is disabled.

partLogRetentionSize

string (int64)

The maximum size that part_log can grow to before old data will be removed. If set to 0, automatic removal of
part_log data based on size is disabled.

partLogRetentionTime

string (int64)

The maximum time that part_log records will be retained before removal. If set to 0, automatic removal of
part_log data based on time is disabled.

metricLogEnabled

boolean

Whether metric_log system table is enabled.

metricLogRetentionSize

string (int64)

The maximum size that metric_log can grow to before old data will be removed. If set to 0, automatic removal of
metric_log data based on size is disabled.

metricLogRetentionTime

string (int64)

The maximum time that metric_log records will be retained before removal. If set to 0, automatic removal of
metric_log data based on time is disabled.

traceLogEnabled

boolean

Whether trace_log system table is enabled.

traceLogRetentionSize

string (int64)

The maximum size that trace_log can grow to before old data will be removed. If set to 0, automatic removal of
trace_log data based on size is disabled.

traceLogRetentionTime

string (int64)

The maximum time that trace_log records will be retained before removal. If set to 0, automatic removal of
trace_log data based on time is disabled.

textLogEnabled

boolean

Whether text_log system table is enabled.

textLogRetentionSize

string (int64)

The maximum size that text_log can grow to before old data will be removed. If set to 0, automatic removal of
text_log data based on size is disabled.

textLogRetentionTime

string (int64)

The maximum time that text_log records will be retained before removal. If set to 0, automatic removal of
text_log data based on time is disabled.

textLogLevel

enum (LogLevel)

Logging level for text_log system table. Possible values: TRACE, DEBUG, INFORMATION, WARNING, ERROR.

  • LOG_LEVEL_UNSPECIFIED
  • TRACE
  • DEBUG
  • INFORMATION
  • WARNING
  • ERROR

opentelemetrySpanLogEnabled

boolean

Enable or disable opentelemetry_span_log system table. Default value: false.

opentelemetrySpanLogRetentionSize

string (int64)

The maximum size that opentelemetry_span_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of opentelemetry_span_log data based on size is disabled.

opentelemetrySpanLogRetentionTime

string (int64)

The maximum time that opentelemetry_span_log records will be retained before removal. If set to 0,
automatic removal of opentelemetry_span_log data based on time is disabled.

queryViewsLogEnabled

boolean

Enable or disable query_views_log system table. Default value: false.

queryViewsLogRetentionSize

string (int64)

The maximum size that query_views_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of query_views_log data based on size is disabled.

queryViewsLogRetentionTime

string (int64)

The maximum time that query_views_log records will be retained before removal. If set to 0,
automatic removal of query_views_log data based on time is disabled.

asynchronousMetricLogEnabled

boolean

Enable or disable asynchronous_metric_log system table. Default value: false.

asynchronousMetricLogRetentionSize

string (int64)

The maximum size that asynchronous_metric_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of asynchronous_metric_log data based on size is disabled.

asynchronousMetricLogRetentionTime

string (int64)

The maximum time that asynchronous_metric_log records will be retained before removal. If set to 0,
automatic removal of asynchronous_metric_log data based on time is disabled.

sessionLogEnabled

boolean

Enable or disable session_log system table. Default value: false.

sessionLogRetentionSize

string (int64)

The maximum size that session_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of session_log data based on size is disabled.

sessionLogRetentionTime

string (int64)

The maximum time that session_log records will be retained before removal. If set to 0,
automatic removal of session_log data based on time is disabled.

zookeeperLogEnabled

boolean

Enable or disable zookeeper_log system table. Default value: false.

zookeeperLogRetentionSize

string (int64)

The maximum size that zookeeper_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of zookeeper_log data based on size is disabled.

zookeeperLogRetentionTime

string (int64)

The maximum time that zookeeper_log records will be retained before removal. If set to 0,
automatic removal of zookeeper_log data based on time is disabled.

asynchronousInsertLogEnabled

boolean

Enable or disable asynchronous_insert_log system table. Default value: false.
Minimal required ClickHouse version: 22.10.

asynchronousInsertLogRetentionSize

string (int64)

The maximum size that asynchronous_insert_log can grow to before old data will be removed. If set to 0 (default),
automatic removal of asynchronous_insert_log data based on size is disabled.

asynchronousInsertLogRetentionTime

string (int64)

The maximum time that asynchronous_insert_log records will be retained before removal. If set to 0,
automatic removal of asynchronous_insert_log data based on time is disabled.

backgroundPoolSize

string (int64)

backgroundMergesMutationsConcurrencyRatio

string (int64)

Sets a ratio between the number of threads and the number of background merges and mutations that can be executed concurrently. For example, if the ratio equals to 2 and background_pool_size is set to 16 then ClickHouse can execute 32 background merges concurrently. This is possible, because background operations could be suspended and postponed. This is needed to give small merges more execution priority. You can only increase this ratio at runtime. To lower it you have to restart the server. The same as for background_pool_size setting background_merges_mutations_concurrency_ratio could be applied from the default profile for backward compatibility.
Default: 2
See in-depth description in ClickHouse documentation

backgroundSchedulePoolSize

string (int64)

backgroundFetchesPoolSize

string (int64)

Sets the number of threads performing background fetches for tables with ReplicatedMergeTree engines. Default value: 8.

More info see in ClickHouse documentation.

backgroundMovePoolSize

string (int64)

backgroundDistributedSchedulePoolSize

string (int64)

backgroundBufferFlushSchedulePoolSize

string (int64)

backgroundMessageBrokerSchedulePoolSize

string (int64)

backgroundCommonPoolSize

string (int64)

The maximum number of threads that will be used for performing a variety of operations (mostly garbage collection) for *MergeTree-engine tables in a background.
Default: 8
See in-depth description in ClickHouse documentation

defaultDatabase

string

The default database.

To get a list of cluster databases, see Yandex Managed ClickHouse documentation.

totalMemoryProfilerStep

string (int64)

Sets the memory size (in bytes) for a stack trace at every peak allocation step. Default value: 4194304.

More info see in ClickHouse documentation.

totalMemoryTrackerSampleProbability

number (double)

queryMaskingRules[]

QueryMaskingRule

Regexp-based rules, which will be applied to queries as well as all log messages before storing them in server logs, system.query_log, system.text_log, system.processes tables, and in logs sent to the client. That allows preventing sensitive data leakage from SQL queries (like names, emails, personal identifiers or credit card numbers) to logs.
Change of these settings is applied with ClickHouse restart
See in-depth description in ClickHouse documentation

dictionariesLazyLoad

boolean

Lazy loading of dictionaries.
Default: true
See in-depth description in ClickHouse documentation

queryCache

QueryCache

Query cache configuration.
Min version: 23.5
See in-depth description in ClickHouse documentation

MergeTree

Options specific to the MergeTree table engine.

Field

Description

replicatedDeduplicationWindow

string (int64)

Number of blocks of hashes to keep in ZooKeeper.

replicatedDeduplicationWindowSeconds

string (int64)

Period of time to keep blocks of hashes for.

partsToDelayInsert

string (int64)

If table contains at least that many active parts in single partition, artificially slow down insert into table.

partsToThrowInsert

string (int64)

If more than this number active parts in single partition, throw 'Too many parts ...' exception.

inactivePartsToDelayInsert

string (int64)

inactivePartsToThrowInsert

string (int64)

maxReplicatedMergesInQueue

string (int64)

How many tasks of merging and mutating parts are allowed simultaneously in ReplicatedMergeTree queue.

numberOfFreeEntriesInPoolToLowerMaxSizeOfMerge

string (int64)

If there is less than specified number of free entries in background pool (or replicated queue), start to lower
maximum size of merge to process.

maxBytesToMergeAtMinSpaceInPool

string (int64)

Maximum in total size of parts to merge, when there are minimum free threads in background pool (or entries
in replication queue).

maxBytesToMergeAtMaxSpaceInPool

string (int64)

minBytesForWidePart

string (int64)

Minimum number of bytes in a data part that can be stored in Wide format.

More info see in ClickHouse documentation.

minRowsForWidePart

string (int64)

Minimum number of rows in a data part that can be stored in Wide format.

More info see in ClickHouse documentation.

ttlOnlyDropParts

boolean

Enables or disables complete dropping of data parts where all rows are expired in MergeTree tables.

More info see in ClickHouse documentation.

allowRemoteFsZeroCopyReplication

boolean

mergeWithTtlTimeout

string (int64)

mergeWithRecompressionTtlTimeout

string (int64)

maxPartsInTotal

string (int64)

maxNumberOfMergesWithTtlInPool

string (int64)

cleanupDelayPeriod

string (int64)

numberOfFreeEntriesInPoolToExecuteMutation

string (int64)

maxAvgPartSizeForTooManyParts

string (int64)

The 'too many parts' check according to 'parts_to_delay_insert' and 'parts_to_throw_insert' will be active only if the average part size (in the relevant partition) is not larger than the specified threshold. If it is larger than the specified threshold, the INSERTs will be neither delayed or rejected. This allows to have hundreds of terabytes in a single table on a single server if the parts are successfully merged to larger parts. This does not affect the thresholds on inactive parts or total parts.
Default: 1 GiB
Min version: 22.10
See in-depth description in ClickHouse GitHub

minAgeToForceMergeSeconds

string (int64)

Merge parts if every part in the range is older than the value of min_age_to_force_merge_seconds.
Default: 0 - disabled
Min_version: 22.10
See in-depth description in ClickHouse documentation

minAgeToForceMergeOnPartitionOnly

boolean

Whether min_age_to_force_merge_seconds should be applied only on the entire partition and not on subset.
Default: false
Min_version: 22.11
See in-depth description in ClickHouse documentation

mergeSelectingSleepMs

string (int64)

Sleep time for merge selecting when no part is selected. A lower setting triggers selecting tasks in background_schedule_pool frequently, which results in a large number of requests to ClickHouse Keeper in large-scale clusters.
Default: 5000
Min_version: 21.10
See in-depth description in ClickHouse documentation

mergeMaxBlockSize

string (int64)

The number of rows that are read from the merged parts into memory.
Default: 8192
See in-depth description in ClickHouse documentation

checkSampleColumnIsCorrect

boolean

Enables the check at table creation, that the data type of a column for sampling or sampling expression is correct. The data type must be one of unsigned integer types: UInt8, UInt16, UInt32, UInt64.
Default: true
See in-depth description in ClickHouse documentation

maxMergeSelectingSleepMs

string (int64)

Maximum sleep time for merge selecting, a lower setting will trigger selecting tasks in background_schedule_pool frequently which result in large amount of requests to zookeeper in large-scale clusters.
Default: 60000
Min_version: 23.6
See in-depth description in ClickHouse GitHub

maxCleanupDelayPeriod

string (int64)

Maximum period to clean old queue logs, blocks hashes and parts.
Default: 300
Min_version: 23.6
See in-depth description in ClickHouse GitHub

Compression

Field

Description

method

enum (Method)

Compression method to use for the specified combination of minPartSize and minPartSizeRatio.

minPartSize

string (int64)

Minimum size of a part of a table.

minPartSizeRatio

string

Minimum ratio of a part relative to the size of all the data in the table.

level

string (int64)

ExternalDictionary

Field

Description

name

string

Required field. Name of the external dictionary.

structure

Structure

Required field. Set of attributes for the external dictionary.
For in-depth description, see ClickHouse documentation.

layout

Layout

Required field. Layout for storing the dictionary in memory.
For in-depth description, see ClickHouse documentation.

fixedLifetime

string (int64)

Fixed interval between dictionary updates.

Includes only one of the fields fixedLifetime, lifetimeRange.

Setting for the period of time between dictionary updates.
For details, see ClickHouse documentation.

lifetimeRange

Range

Range of intervals between dictionary updates for ClickHouse to choose from.

Includes only one of the fields fixedLifetime, lifetimeRange.

Setting for the period of time between dictionary updates.
For details, see ClickHouse documentation.

httpSource

HttpSource

HTTP source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

mysqlSource

MysqlSource

MySQL source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

clickhouseSource

ClickhouseSource

ClickHouse source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

mongodbSource

MongodbSource

MongoDB source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

postgresqlSource

PostgresqlSource

PostgreSQL source for the dictionary.

Includes only one of the fields httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource.

Description of the source for the external dictionary.

Structure

Field

Description

id

Id

Single numeric key column for the dictionary.

key

Key

Composite key for the dictionary, containing of one or more key columns.
For details, see ClickHouse documentation.

rangeMin

Attribute

Field holding the beginning of the range for dictionaries with RANGE_HASHED layout.
For details, see ClickHouse documentation.

rangeMax

Attribute

Field holding the end of the range for dictionaries with RANGE_HASHED layout.
For details, see ClickHouse documentation.

attributes[]

Attribute

Description of the fields available for database queries.
For details, see ClickHouse documentation.

Id

Numeric key.

Field

Description

name

string

Required field. Name of the numeric key.

Key

Complex key.

Field

Description

attributes[]

Attribute

Attributes of a complex key.

Attribute

Field

Description

name

string

Required field. Name of the column.

type

string

Required field. Type of the column.

nullValue

string

Default value for an element without data (for example, an empty string).

expression

string

Expression, describing the attribute, if applicable.

hierarchical

boolean

Indication of hierarchy support.
Default value: false.

injective

boolean

Indication of injective mapping "id -> attribute".
Default value: false.

Layout

Layout determining how to store the dictionary in memory.

Field

Description

type

enum (Type)

Required field. Layout type for an external dictionary.

  • TYPE_UNSPECIFIED
  • FLAT: The entire dictionary is stored in memory in the form of flat arrays.
    Available for all dictionary sources.
  • HASHED: The entire dictionary is stored in memory in the form of a hash table.
    Available for all dictionary sources.
  • COMPLEX_KEY_HASHED: Similar to HASHED, to be used with composite keys.
    Available for all dictionary sources.
  • RANGE_HASHED: The entire dictionary is stored in memory in the form of a hash table,
    with an ordered array of ranges and their corresponding values.
    Available for all dictionary sources.
  • CACHE: The dictionary is stored in a cache with a set number of cells.
    Available for MySQL, ClickHouse and HTTP dictionary sources.
  • COMPLEX_KEY_CACHE: Similar to CACHE, to be used with composite keys.
    Available for MySQL, ClickHouse and HTTP dictionary sources.

sizeInCells

string (int64)

Number of cells in the cache. Rounded up to a power of two.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

maxArraySize

string (int64)

Maximum dictionary key size.
Applicable only for FLAT layout type.

Range

Field

Description

min

string (int64)

Minimum dictionary lifetime.

max

string (int64)

Maximum dictionary lifetime.

HttpSource

Field

Description

url

string

Required field. URL of the source dictionary available over HTTP.

format

string

Required field. The data format. Valid values are all formats supported by ClickHouse SQL dialect.

headers[]

Header

HTTP headers.

Header

Field

Description

name

string

Required field.

value

string

Required field.

MysqlSource

Field

Description

db

string

Required field. Name of the MySQL database to connect to.

table

string

Required field. Name of the database table to use as a ClickHouse dictionary.

port

string (int64)

Default port to use when connecting to a replica of the dictionary source.

user

string

Name of the default user for replicas of the dictionary source.

password

string

Password of the default user for replicas of the dictionary source.

replicas[]

Replica

List of MySQL replicas of the database used as dictionary source.

where

string

Selection criteria for the data in the specified MySQL table.

invalidateQuery

string

Query for checking the dictionary status, to pull only updated data.
For more details, see ClickHouse documentation on dictionaries.

closeConnection

boolean

Should the connection be closed after each request.

shareConnection

boolean

Should a connection be shared for some requests.

Replica

Field

Description

host

string

Required field. MySQL host of the replica.

priority

string (int64)

Required field. The priority of the replica that ClickHouse takes into account when connecting.
Replica with the highest priority should have this field set to the lowest number.

port

string (int64)

Port to use when connecting to the replica.
If a port is not specified for a replica, ClickHouse uses the port specified for the source.

user

string

Name of the MySQL database user.

password

string

Password of the MySQL database user.

ClickhouseSource

Field

Description

db

string

Required field. Name of the ClickHouse database.

table

string

Required field. Name of the table in the specified database to be used as the dictionary source.

host

string

ClickHouse host of the specified database.

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the ClickHouse database user.

password

string

Password of the ClickHouse database user.

where

string

Selection criteria for the data in the specified ClickHouse table.

secure

boolean

Use ssl for connection.

MongodbSource

Field

Description

db

string

Required field. Name of the MongoDB database.

collection

string

Required field. Name of the collection in the specified database to be used as the dictionary source.

host

string

MongoDB host of the specified database.

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the MongoDB database user.

password

string

Password of the MongoDB database user.

options

string

PostgresqlSource

Field

Description

db

string

Required field. Name of the PostrgreSQL database.

table

string

Required field. Name of the table in the specified database to be used as the dictionary source.

hosts[]

string

Name of the PostrgreSQL host

port

string (int64)

Port to use when connecting to the host.

user

string

Required field. Name of the PostrgreSQL database user.

password

string

Password of the PostrgreSQL database user.

invalidateQuery

string

Query for checking the dictionary status, to pull only updated data.
For more details, see ClickHouse documentation on dictionaries.

sslMode

enum (SslMode)

Mode of SSL TCP/IP connection to the PostgreSQL host.
For more details, see PostgreSQL documentation.

  • SSL_MODE_UNSPECIFIED
  • DISABLE: Only try a non-SSL connection.
  • ALLOW: First try a non-SSL connection; if that fails, try an SSL connection.
  • PREFER: First try an SSL connection; if that fails, try a non-SSL connection.
  • VERIFY_CA: Only try an SSL connection, and verify that the server certificate is issued by a trusted certificate authority (CA).
  • VERIFY_FULL: Only try an SSL connection, verify that the server certificate is issued by a trusted CA and that the requested server host name matches that in the certificate.

GraphiteRollup

Rollup settings for the GraphiteMergeTree table engine.

Field

Description

name

string

Required field. Name for the specified combination of settings for Graphite rollup.

patterns[]

Pattern

Pattern to use for the rollup.

pathColumnName

string

The name of the column storing the metric name (Graphite sensor).
Default: Path
See in-depth description in ClickHouse documentation

timeColumnName

string

The name of the column storing the time of measuring the metric.
Default: Time
See in-depth description in ClickHouse documentation

valueColumnName

string

The name of the column storing the value of the metric at the time set in time_column_name.
Default: Value
See in-depth description in ClickHouse documentation

versionColumnName

string

The name of the column storing the version of the metric.
Default: Timestamp
See in-depth description in ClickHouse documentation

Pattern

Field

Description

regexp

string

Pattern for metric names.

function

string

Required field. Name of the aggregating function to apply to data of the age specified in retention.

retention[]

Retention

Age of data to use for thinning.

Retention

Field

Description

age

string (int64)

Minimum age of the data in seconds.

precision

string (int64)

Precision of determining the age of the data, in seconds.

Kafka

Field

Description

securityProtocol

enum (SecurityProtocol)

  • SECURITY_PROTOCOL_UNSPECIFIED
  • SECURITY_PROTOCOL_PLAINTEXT
  • SECURITY_PROTOCOL_SSL
  • SECURITY_PROTOCOL_SASL_PLAINTEXT
  • SECURITY_PROTOCOL_SASL_SSL

saslMechanism

enum (SaslMechanism)

  • SASL_MECHANISM_UNSPECIFIED
  • SASL_MECHANISM_GSSAPI
  • SASL_MECHANISM_PLAIN
  • SASL_MECHANISM_SCRAM_SHA_256
  • SASL_MECHANISM_SCRAM_SHA_512

saslUsername

string

saslPassword

string

enableSslCertificateVerification

boolean

maxPollIntervalMs

string (int64)

sessionTimeoutMs

string (int64)

debug

enum (Debug)

  • DEBUG_UNSPECIFIED
  • DEBUG_GENERIC
  • DEBUG_BROKER
  • DEBUG_TOPIC
  • DEBUG_METADATA
  • DEBUG_FEATURE
  • DEBUG_QUEUE
  • DEBUG_MSG
  • DEBUG_PROTOCOL
  • DEBUG_CGRP
  • DEBUG_SECURITY
  • DEBUG_FETCH
  • DEBUG_INTERCEPTOR
  • DEBUG_PLUGIN
  • DEBUG_CONSUMER
  • DEBUG_ADMIN
  • DEBUG_EOS
  • DEBUG_MOCK
  • DEBUG_ASSIGNOR
  • DEBUG_CONF
  • DEBUG_TELEMETRY
  • DEBUG_ALL

autoOffsetReset

enum (AutoOffsetReset)

  • AUTO_OFFSET_RESET_UNSPECIFIED
  • AUTO_OFFSET_RESET_SMALLEST
  • AUTO_OFFSET_RESET_EARLIEST
  • AUTO_OFFSET_RESET_BEGINNING
  • AUTO_OFFSET_RESET_LARGEST
  • AUTO_OFFSET_RESET_LATEST
  • AUTO_OFFSET_RESET_END
  • AUTO_OFFSET_RESET_ERROR

KafkaTopic

Field

Description

name

string

Required field.

settings

Kafka

Required field.

Rabbitmq

Field

Description

username

string

RabbitMQ username

password

string

RabbitMQ password

vhost

string

RabbitMQ virtual host

QueryMaskingRule

Field

Description

name

string

Name for the rule.

regexp

string

Required field. RE2 compatible regular expression.
Required.

replace

string

Substitution string for sensitive data.
Default: six asterisks

QueryCache

Field

Description

maxSizeInBytes

string (int64)

The maximum cache size in bytes.
Default: 1073741824 (1 GiB)

maxEntries

string (int64)

The maximum number of SELECT query results stored in the cache.
Default: 1024

maxEntrySizeInBytes

string (int64)

The maximum size in bytes SELECT query results may have to be saved in the cache.
Dafault: 1048576 (1 MiB)

maxEntrySizeInRows

string (int64)

The maximum number of rows SELECT query results may have to be saved in the cache.
Default: 30000000 (30 mil)

Resources

Field

Description

resourcePresetId

string

ID of the preset for computational resources available to a host (CPU, memory etc.).
All available presets are listed in the documentation

diskSize

string (int64)

Volume of the storage available to a host, in bytes.

diskTypeId

string

Type of the storage environment for the host.
Possible values:

  • network-hdd - network HDD drive,
  • network-ssd - network SSD drive,
  • local-ssd - local SSD storage.
Previous
AddShards
Next
DeleteShard