Managed Service for ClickHouse API, gRPC: ClusterService.ListExternalDictionaries

Статья создана

Обновлена 18 апреля 2025 г.

gRPC request
ListClusterExternalDictionariesRequest
ListClusterExternalDictionariesResponse
ExternalDictionary
Structure
Id
Key
Attribute
Layout
Range
HttpSource
Header
MysqlSource
Replica
ClickhouseSource
MongodbSource
PostgresqlSource

Retrieves a list of external dictionaries that belong to specified cluster.

gRPC request

rpc ListExternalDictionaries (ListClusterExternalDictionariesRequest) returns (ListClusterExternalDictionariesResponse)

ListClusterExternalDictionariesRequest

{
  "cluster_id": "string",
  "page_size": "int64",
  "page_token": "string"
}

Field	Description
cluster_id	string Required field. ID of the cluster that the external dictionaries belong to.
page_size	int64 The maximum number of results per page to return. If the number of available results is larger than `page_size`, the service returns a [ListClusterExternalDictionaryResponse.next_page_token] that can be used to get the next page of results in subsequent list requests.
page_token	string Page token. To get the next page of results, set `page_token` to the [ListClusterExternalDictionaryResponse.next_page_token] returned by a previous list request.

ListClusterExternalDictionariesResponse

{
  "external_dictionaries": [
    {
      "name": "string",
      "structure": {
        "id": {
          "name": "string"
        },
        "key": {
          "attributes": [
            {
              "name": "string",
              "type": "string",
              "null_value": "string",
              "expression": "string",
              "hierarchical": "bool",
              "injective": "bool"
            }
          ]
        },
        "range_min": {
          "name": "string",
          "type": "string",
          "null_value": "string",
          "expression": "string",
          "hierarchical": "bool",
          "injective": "bool"
        },
        "range_max": {
          "name": "string",
          "type": "string",
          "null_value": "string",
          "expression": "string",
          "hierarchical": "bool",
          "injective": "bool"
        },
        "attributes": [
          {
            "name": "string",
            "type": "string",
            "null_value": "string",
            "expression": "string",
            "hierarchical": "bool",
            "injective": "bool"
          }
        ]
      },
      "layout": {
        "type": "Type",
        "size_in_cells": "int64",
        "allow_read_expired_keys": "google.protobuf.BoolValue",
        "max_update_queue_size": "int64",
        "update_queue_push_timeout_milliseconds": "int64",
        "query_wait_timeout_milliseconds": "int64",
        "max_threads_for_updates": "int64",
        "initial_array_size": "int64",
        "max_array_size": "int64",
        "access_to_key_from_attributes": "google.protobuf.BoolValue"
      },
      // Includes only one of the fields `fixed_lifetime`, `lifetime_range`
      "fixed_lifetime": "int64",
      "lifetime_range": {
        "min": "int64",
        "max": "int64"
      },
      // end of the list of possible fields
      // Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`
      "http_source": {
        "url": "string",
        "format": "string",
        "headers": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      },
      "mysql_source": {
        "db": "string",
        "table": "string",
        "port": "int64",
        "user": "string",
        "password": "string",
        "replicas": [
          {
            "host": "string",
            "priority": "int64",
            "port": "int64",
            "user": "string",
            "password": "string"
          }
        ],
        "where": "string",
        "invalidate_query": "string",
        "close_connection": "google.protobuf.BoolValue",
        "share_connection": "google.protobuf.BoolValue"
      },
      "clickhouse_source": {
        "db": "string",
        "table": "string",
        "host": "string",
        "port": "int64",
        "user": "string",
        "password": "string",
        "where": "string",
        "secure": "google.protobuf.BoolValue"
      },
      "mongodb_source": {
        "db": "string",
        "collection": "string",
        "host": "string",
        "port": "int64",
        "user": "string",
        "password": "string",
        "options": "string"
      },
      "postgresql_source": {
        "db": "string",
        "table": "string",
        "hosts": [
          "string"
        ],
        "port": "int64",
        "user": "string",
        "password": "string",
        "invalidate_query": "string",
        "ssl_mode": "SslMode"
      }
      // end of the list of possible fields
    }
  ],
  "next_page_token": "string"
}

Field

Description

external_dictionaries[]

ExternalDictionary

List of ClickHouse Cluster external dictionaries.

next_page_token

string

This token allows you to get the next page of results for list requests. If the number of results
is larger than [ListClusterExternalDictionaryRequest.page_size], use the next_page_token as the value
for the [ListClusterExternalDictionaryRequest.page_token] parameter in the next list request. Each subsequent
list request will have its own next_page_token to continue paging through the results.

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.
fixed_lifetime	int64 Fixed interval between dictionary updates. Includes only one of the fields `fixed_lifetime`, `lifetime_range`. Setting for the period of time between dictionary updates. For details, see ClickHouse documentation.
lifetime_range	Range Range of intervals between dictionary updates for ClickHouse to choose from. Includes only one of the fields `fixed_lifetime`, `lifetime_range`. Setting for the period of time between dictionary updates. For details, see ClickHouse documentation.
http_source	HttpSource HTTP source for the dictionary. Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`. Description of the source for the external dictionary.
mysql_source	MysqlSource MySQL source for the dictionary. Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`. Description of the source for the external dictionary.
clickhouse_source	ClickhouseSource ClickHouse source for the dictionary. Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`. Description of the source for the external dictionary.
mongodb_source	MongodbSource MongoDB source for the dictionary. Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`. Description of the source for the external dictionary.
postgresql_source	PostgresqlSource PostgreSQL source for the dictionary. Includes only one of the fields `http_source`, `mysql_source`, `clickhouse_source`, `mongodb_source`, `postgresql_source`. 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.
range_min	Attribute Field holding the beginning of the range for dictionaries with `RANGE_HASHED` layout. For details, see ClickHouse documentation.
range_max	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.
null_value	string Default value for an element without data (for example, an empty string).
expression	string Expression, describing the attribute, if applicable.
hierarchical	bool Indication of hierarchy support. Default value: `false`.
injective	bool 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. `SPARSE_HASHED`: Similar to HASHED, but uses less memory in favor of more CPU usage. `COMPLEX_KEY_SPARSE_HASHED`: Similar to SPARSE_HASHED, to be used with composite keys. `COMPLEX_KEY_RANGE_HASHED`: Similar to RANGE_HASHED, to be used with composite keys. `DIRECT`: The dictionary is not stored in memory and directly goes to the source during the processing of a request. `COMPLEX_KEY_DIRECT`: Similar to DIRECT, to be used with composite keys. `IP_TRIE`: The specialized layout type for mapping network prefixes (IP addresses) to metadata such as ASN.
size_in_cells	int64 Number of cells in the cache. Rounded up to a power of two. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
allow_read_expired_keys	google.protobuf.BoolValue Allows to read expired keys. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
max_update_queue_size	int64 Max size of update queue. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
update_queue_push_timeout_milliseconds	int64 Max timeout in milliseconds for push update task into queue. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
query_wait_timeout_milliseconds	int64 Max wait timeout in milliseconds for update task to complete. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
max_threads_for_updates	int64 Max threads for cache dictionary update. Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.
initial_array_size	int64 Initial dictionary key size. Applicable only for FLAT layout type.
max_array_size	int64 Maximum dictionary key size. Applicable only for FLAT layout type.
access_to_key_from_attributes	google.protobuf.BoolValue Allows to retrieve key attribute using dictGetString function. Enabling this option increases memory usage. Applicable only for IP_TRIE layout type.

Range

Field

Description

min

int64

Minimum dictionary lifetime.

max

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.

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	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.
invalidate_query	string Query for checking the dictionary status, to pull only updated data. For more details, see ClickHouse documentation on dictionaries.
close_connection	google.protobuf.BoolValue Should the connection be closed after each request.
share_connection	google.protobuf.BoolValue Should a connection be shared for some requests.

Replica

Field	Description
host	string Required field. MySQL host of the replica.
priority	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	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	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	google.protobuf.BoolValue 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	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	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.
invalidate_query	string Query for checking the dictionary status, to pull only updated data. For more details, see ClickHouse documentation on dictionaries.
ssl_mode	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.

Managed Service for ClickHouse API, gRPC: ClusterService.ListExternalDictionaries

gRPC requestgRPC request

ListClusterExternalDictionariesRequestListClusterExternalDictionariesRequest

ListClusterExternalDictionariesResponseListClusterExternalDictionariesResponse

ExternalDictionaryExternalDictionary

StructureStructure

IdId

KeyKey

AttributeAttribute

LayoutLayout

RangeRange

HttpSourceHttpSource

HeaderHeader

MysqlSourceMysqlSource

ReplicaReplica

ClickhouseSourceClickhouseSource

MongodbSourceMongodbSource

PostgresqlSourcePostgresqlSource

Была ли статья полезна?

gRPC request

ListClusterExternalDictionariesRequest

ListClusterExternalDictionariesResponse

ExternalDictionary

Structure

Id

Key

Attribute

Layout

Range

HttpSource

Header

MysqlSource

Replica

ClickhouseSource

MongodbSource

PostgresqlSource