Managed Service for ClickHouse API, REST: Cluster.Update

Field

Description

clusterId

string

Required field. ID of the ClickHouse Cluster resource to update.
To get the ClickHouse cluster ID, use a ClusterService.List request.

Field

Description

updateMask

string (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.

description

string

New description of the ClickHouse cluster.

labels

string

Custom labels for the ClickHouse cluster as key:value pairs. Maximum 64 per resource.
For example, "project": "mvp" or "source": "dictionary".

The new set of labels will completely replace the old ones. To add a label, request the current
set with the ClusterService.Get method, then send an ClusterService.Update request with the new label added to the set.

configSpec

ConfigSpec

New configuration and resources for hosts in the cluster.

name

string

New name for the cluster.

serviceAccountId

string

ID of the service account used for access to Object Storage.

maintenanceWindow

MaintenanceWindow

New maintenance window settings for the cluster.

securityGroupIds[]

string

User security groups

deletionProtection

boolean

Deletion Protection inhibits deletion of the cluster

networkId

string

ID of the network to move the cluster to.

Field

Description

version

string

Version of the ClickHouse server software.

clickhouse

Clickhouse

Configuration and resources for a ClickHouse server.

zookeeper

Zookeeper

Configuration and resources for a ZooKeeper server.

backupWindowStart

TimeOfDay

Time to start the daily backup, in the UTC timezone.

access

Access

Access policy for external services.

If you want a specific service to access the ClickHouse cluster, then set the necessary values in this policy.

cloudStorage

CloudStorage

sqlDatabaseManagement

boolean

Whether database management through SQL commands is enabled.

sqlUserManagement

boolean

Whether user management through SQL commands is enabled.

adminPassword

string

Password for user 'admin' that has SQL user management access.

embeddedKeeper

boolean

Whether cluster should use embedded Keeper instead of Zookeeper

backupRetainPeriodDays

string (int64)

Retain period of automatically created backup in days

Field

Description

config

ClickhouseConfig

Configuration for a ClickHouse server.

resources

Resources

Resources allocated to ClickHouse hosts.

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

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

Field

Description

method

enum (Method)

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

• METHOD_UNSPECIFIED
• LZ4: LZ4 compression algorithm.
• ZSTD: Zstandard compression algorithm.

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)

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.

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.

Field

Description

name

string

Required field. Name of the numeric key.

Field

Description

attributes[]

Attribute

Attributes of a complex key.

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.

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.

Field

Description

min

string (int64)

Minimum dictionary lifetime.

max

string (int64)

Maximum dictionary lifetime.

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.

Field

Description

name

string

Required field.

value

string

Required field.

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.

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.

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.

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

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.

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

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.

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.

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

Field

Description

name

string

Required field.

settings

Kafka

Required field.

Field

Description

username

string

RabbitMQ username

password

string

RabbitMQ password

vhost

string

RabbitMQ virtual host

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

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)

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.

Field

Description

resources

Resources

Resources allocated to ZooKeeper hosts. If not set, minimal available resources will be used.
All available resource presets can be retrieved with a ResourcePresetService.List request.

Field

Description

hours

integer (int32)

Hours of day in 24 hour format. Should be from 0 to 23. An API may choose
to allow the value "24:00:00" for scenarios like business closing time.

minutes

integer (int32)

Minutes of hour of day. Must be from 0 to 59.

seconds

integer (int32)

Seconds of minutes of the time. Must normally be from 0 to 59. An API may
allow the value 60 if it allows leap-seconds.

nanos

integer (int32)

Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999.

Field

Description

dataLens

boolean

Allow to export data from the cluster to DataLens.

webSql

boolean

Allow SQL queries to the cluster databases from the management console.

See SQL queries in the management console for more details.

metrika

boolean

Allow to import data from Yandex Metrica and AppMetrica to the cluster.

See AppMetrica documentation for more details.

serverless

boolean

Allow access to cluster for Serverless.

dataTransfer

boolean

Allow access for DataTransfer

yandexQuery

boolean

Allow access for Query

Field

Description

enabled

boolean

Whether to use Object Storage for storing ClickHouse data.

moveFactor

number (double)

dataCacheEnabled

boolean

dataCacheMaxSize

string (int64)

preferNotToMerge

boolean

Field

Description

anytime

object

Maintenance operation can be scheduled anytime.

Includes only one of the fields anytime, weeklyMaintenanceWindow.

The maintenance policy in effect.

weeklyMaintenanceWindow

WeeklyMaintenanceWindow

Maintenance operation can be scheduled on a weekly basis.

Includes only one of the fields anytime, weeklyMaintenanceWindow.

The maintenance policy in effect.

Field

Description

day

enum (WeekDay)

Day of the week (in DDD format).

• WEEK_DAY_UNSPECIFIED
• MON
• TUE
• WED
• THU
• FRI
• SAT
• SUN

hour

string (int64)

Hour of the day in UTC (in HH format).

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

UpdateClusterMetadata

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

Cluster

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.

Field

Description

clusterId

string

ID of the ClickHouse Cluster resource that is being updated.

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.

Field

Description

id

string

ID of the ClickHouse cluster.
This ID is assigned by MDB at creation time.

folderId

string

ID of the folder that the ClickHouse cluster belongs to.

createdAt

string (date-time)

Creation timestamp in RFC3339 text format.

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).

name

string

Name of the ClickHouse cluster.
The name is unique within the folder. 1-63 characters long.

description

string

Description of the ClickHouse cluster. 0-256 characters long.

labels

string

Custom labels for the ClickHouse cluster as key:value pairs. Maximum 64 per resource.

environment

enum (Environment)

Deployment environment of the ClickHouse cluster.

• ENVIRONMENT_UNSPECIFIED
• PRODUCTION: Stable environment with a conservative update policy:
  only hotfixes are applied during regular maintenance.
• PRESTABLE: Environment with more aggressive update policy: new versions
  are rolled out irrespective of backward compatibility.

monitoring[]

Monitoring

Description of monitoring systems relevant to the ClickHouse cluster.

config

ClusterConfig

Configuration of the ClickHouse cluster.

networkId

string

ID of the network that the cluster belongs to.

health

enum (Health)

Aggregated cluster health.

• HEALTH_UNKNOWN: State of the cluster is unknown (Host.health for every host in the cluster is UNKNOWN).
• ALIVE: Cluster is alive and well (Host.health for every host in the cluster is ALIVE).
• DEAD: Cluster is inoperable (Host.health for every host in the cluster is DEAD).
• DEGRADED: Cluster is working below capacity (Host.health for at least one host in the cluster is not ALIVE).

status

enum (Status)

Current state of the cluster.

• STATUS_UNKNOWN: Cluster state is unknown.
• CREATING: Cluster is being created.
• RUNNING: Cluster is running normally.
• ERROR: Cluster encountered a problem and cannot operate.
• UPDATING: Cluster is being updated.
• STOPPING: Cluster is stopping.
• STOPPED: Cluster stopped.
• STARTING: Cluster is starting.

serviceAccountId

string

ID of the service account used for access to Object Storage.

maintenanceWindow

MaintenanceWindow

Maintenance window for the cluster.

plannedOperation

MaintenanceOperation

Planned maintenance operation to be started for the cluster within the nearest maintenanceWindow.

securityGroupIds[]

string

User security groups

deletionProtection

boolean

Deletion Protection inhibits deletion of the cluster

Field

Description

name

string

Name of the monitoring system.

description

string

Description of the monitoring system.

link

string

Link to the monitoring system charts for the ClickHouse cluster.

Field

Description

version

string

Version of the ClickHouse server software.

clickhouse

Clickhouse

Configuration and resource allocation for ClickHouse hosts.

zookeeper

Zookeeper

Configuration and resource allocation for ZooKeeper hosts.

backupWindowStart

TimeOfDay

Time to start the daily backup, in the UTC timezone.

access

Access

Access policy for external services.

cloudStorage

CloudStorage

sqlDatabaseManagement

boolean

Whether database management through SQL commands is enabled.

sqlUserManagement

boolean

Whether user management through SQL commands is enabled.

embeddedKeeper

boolean

Whether cluster should use embedded Keeper instead of Zookeeper.

backupRetainPeriodDays

string (int64)

Retain period of automatically created backup in days

Field

Description

config

ClickhouseConfigSet

Configuration settings of a ClickHouse server.

resources

Resources

Resources allocated to ClickHouse hosts.

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.

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

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

Field

Description

method

enum (Method)

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

• METHOD_UNSPECIFIED
• LZ4: LZ4 compression algorithm.
• ZSTD: Zstandard compression algorithm.

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)

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.

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.

Field

Description

name

string

Required field. Name of the numeric key.

Field

Description

attributes[]

Attribute

Attributes of a complex key.

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.

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.

Field

Description

min

string (int64)

Minimum dictionary lifetime.

max

string (int64)

Maximum dictionary lifetime.

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.

Field

Description

name

string

Required field.

value

string

Required field.

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.

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.

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.

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

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.

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

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.

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.

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

Field

Description

name

string

Required field.

settings

Kafka

Required field.

Field

Description

username

string

RabbitMQ username

password

string

RabbitMQ password

vhost

string

RabbitMQ virtual host

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

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)

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.

Field

Description

resources

Resources

Resources allocated to ZooKeeper hosts.

Field

Description

hours

integer (int32)

Hours of day in 24 hour format. Should be from 0 to 23. An API may choose
to allow the value "24:00:00" for scenarios like business closing time.

minutes

integer (int32)

Minutes of hour of day. Must be from 0 to 59.

seconds

integer (int32)

Seconds of minutes of the time. Must normally be from 0 to 59. An API may
allow the value 60 if it allows leap-seconds.

nanos

integer (int32)

Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999.

Field

Description

dataLens

boolean

Allow to export data from the cluster to DataLens.

webSql

boolean

Allow SQL queries to the cluster databases from the management console.

See SQL queries in the management console for more details.

metrika

boolean

Allow to import data from Yandex Metrica and AppMetrica to the cluster.

See AppMetrica documentation for more details.

serverless

boolean

Allow access to cluster for Serverless.

dataTransfer

boolean

Allow access for DataTransfer

yandexQuery

boolean

Allow access for Query

Field

Description

enabled

boolean

Whether to use Object Storage for storing ClickHouse data.

moveFactor

number (double)

dataCacheEnabled

boolean

dataCacheMaxSize

string (int64)

preferNotToMerge

boolean

Field

Description

anytime

object

Maintenance operation can be scheduled anytime.

Includes only one of the fields anytime, weeklyMaintenanceWindow.

The maintenance policy in effect.

weeklyMaintenanceWindow

WeeklyMaintenanceWindow

Maintenance operation can be scheduled on a weekly basis.

Includes only one of the fields anytime, weeklyMaintenanceWindow.

The maintenance policy in effect.

Field

Description

day

enum (WeekDay)

Day of the week (in DDD format).

• WEEK_DAY_UNSPECIFIED
• MON
• TUE
• WED
• THU
• FRI
• SAT
• SUN

hour

string (int64)

Hour of the day in UTC (in HH format).

Field

Description

info

string

Information about this maintenance operation.

delayedUntil

string (date-time)

Time until which this maintenance operation is delayed.

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).