Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Blog
  • Pricing
  • Documentation
© 2025 Direct Cursus Technology L.L.C.
Yandex Managed Service for ClickHouse®
  • Getting started
  • Access management
  • Pricing policy
  • Terraform reference
    • Authentication with the API
      • Overview
        • Overview
        • Get
        • List
        • Create
        • Update
        • Delete
        • Start
        • Stop
        • Move
        • AddZookeeper
        • Backup
        • Restore
        • RescheduleMaintenance
        • ListLogs
        • StreamLogs
        • ListOperations
        • ListBackups
        • ListHosts
        • AddHosts
        • UpdateHosts
        • DeleteHosts
        • RestartHosts
        • GetShard
        • ListShards
        • AddShard
        • AddShards
        • UpdateShard
        • DeleteShard
        • DeleteShards
        • GetShardGroup
        • ListShardGroups
        • CreateShardGroup
        • UpdateShardGroup
        • DeleteShardGroup
        • ListExternalDictionaries
        • CreateExternalDictionary
        • UpdateExternalDictionary
        • DeleteExternalDictionary
  • Yandex Monitoring metrics
  • Audit Trails events
  • Public materials
  • Release notes

In this article:

  • HTTP request
  • Path parameters
  • Query parameters
  • Response
  • ExternalDictionary
  • Structure
  • Id
  • Key
  • Attribute
  • Layout
  • Range
  • HttpSource
  • Header
  • MysqlSource
  • Replica
  • ClickhouseSource
  • MongodbSource
  • PostgresqlSource
  1. API reference
  2. REST
  3. Cluster
  4. ListExternalDictionaries

Managed Service for ClickHouse API, REST: Cluster.ListExternalDictionaries

Written by
Yandex Cloud
Updated at April 18, 2025
  • HTTP request
  • Path parameters
  • Query parameters
  • Response
  • 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.

HTTP requestHTTP request

GET https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/{clusterId}/externalDictionaries

Path parametersPath parameters

Field

Description

clusterId

string

Required field. ID of the cluster that the external dictionaries belong to.

Query parametersQuery parameters

Field

Description

pageSize

string (int64)

The maximum number of results per page to return. If the number of available
results is larger than pageSize, the service returns a [ListClusterExternalDictionaryResponse.next_page_token]
that can be used to get the next page of results in subsequent list requests.

pageToken

string

Page token. To get the next page of results, set pageToken to the [ListClusterExternalDictionaryResponse.next_page_token]
returned by a previous list request.

ResponseResponse

HTTP Code: 200 - OK

{
  "externalDictionaries": [
    {
      "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",
        "allowReadExpiredKeys": "boolean",
        "maxUpdateQueueSize": "string",
        "updateQueuePushTimeoutMilliseconds": "string",
        "queryWaitTimeoutMilliseconds": "string",
        "maxThreadsForUpdates": "string",
        "initialArraySize": "string",
        "maxArraySize": "string",
        "accessToKeyFromAttributes": "boolean"
      },
      // 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
    }
  ],
  "nextPageToken": "string"
}

Field

Description

externalDictionaries[]

ExternalDictionary

List of ClickHouse Cluster external dictionaries.

nextPageToken

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 nextPageToken as the value
for the [ListClusterExternalDictionaryRequest.page_token] parameter in the next list request. Each subsequent
list request will have its own nextPageToken to continue paging through the results.

ExternalDictionaryExternalDictionary

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.

StructureStructure

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.

IdId

Numeric key.

Field

Description

name

string

Required field. Name of the numeric key.

KeyKey

Complex key.

Field

Description

attributes[]

Attribute

Attributes of a complex key.

AttributeAttribute

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.

LayoutLayout

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.

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.

allowReadExpiredKeys

boolean

Allows to read expired keys.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

maxUpdateQueueSize

string (int64)

Max size of update queue.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

updateQueuePushTimeoutMilliseconds

string (int64)

Max timeout in milliseconds for push update task into queue.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

queryWaitTimeoutMilliseconds

string (int64)

Max wait timeout in milliseconds for update task to complete.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

maxThreadsForUpdates

string (int64)

Max threads for cache dictionary update.
Applicable only for CACHE and COMPLEX_KEY_CACHE layout types.

initialArraySize

string (int64)

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

maxArraySize

string (int64)

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

accessToKeyFromAttributes

boolean

Allows to retrieve key attribute using dictGetString function.
Enabling this option increases memory usage.
Applicable only for IP_TRIE layout type.

RangeRange

Field

Description

min

string (int64)

Minimum dictionary lifetime.

max

string (int64)

Maximum dictionary lifetime.

HttpSourceHttpSource

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.

HeaderHeader

Field

Description

name

string

Required field.

value

string

Required field.

MysqlSourceMysqlSource

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.

ReplicaReplica

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.

ClickhouseSourceClickhouseSource

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.

MongodbSourceMongodbSource

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

PostgresqlSourcePostgresqlSource

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.

Was the article helpful?

Previous
DeleteShardGroup
Next
CreateExternalDictionary
© 2025 Direct Cursus Technology L.L.C.