Метод createExternalDictionary

Создает внешний словарь для указанного кластера ClickHouse.

HTTP-запрос

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

Path-параметры

Параметр Описание
clusterId Обязательное поле. Идентификатор кластера ClickHouse, для которого следует создать внешний словарь. Чтобы получить идентификатор кластера, используйте запрос list. Максимальная длина строки в символах — 50.

Параметры в теле запроса

{
  "externalDictionary": {
    "name": "string",
    "structure": {
      "id": {
        "name": "string"
      },
      "key": {
        "attributes": [
          {
            "name": "string",
            "type": "string",
            "nullValue": "string",
            "expression": "string",
            "hierarchical": true,
            "injective": true
          }
        ]
      },
      "rangeMin": {
        "name": "string",
        "type": "string",
        "nullValue": "string",
        "expression": "string",
        "hierarchical": true,
        "injective": true
      },
      "rangeMax": {
        "name": "string",
        "type": "string",
        "nullValue": "string",
        "expression": "string",
        "hierarchical": true,
        "injective": true
      },
      "attributes": [
        {
          "name": "string",
          "type": "string",
          "nullValue": "string",
          "expression": "string",
          "hierarchical": true,
          "injective": true
        }
      ]
    },
    "layout": {
      "type": "string",
      "sizeInCells": "string"
    },

    // `externalDictionary` включает только одно из полей `httpSource`, `mysqlSource`, `clickhouseSource`, `mongodbSource`, `postgresqlSource`
    "fixedLifetime": "string",
    "lifetimeRange": {
      "min": "string",
      "max": "string"
    },
    // конец списка возможных полей`externalDictionary`

    "httpSource": {
      "url": "string",
      "format": "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"
    },
    "clickhouseSource": {
      "db": "string",
      "table": "string",
      "host": "string",
      "port": "string",
      "user": "string",
      "password": "string",
      "where": "string"
    },
    "mongodbSource": {
      "db": "string",
      "collection": "string",
      "host": "string",
      "port": "string",
      "user": "string",
      "password": "string"
    },
    "postgresqlSource": {
      "db": "string",
      "table": "string",
      "hosts": [
        "string"
      ],
      "port": "string",
      "user": "string",
      "password": "string",
      "invalidateQuery": "string",
      "sslMode": "string"
    }
  }
}
Поле Описание
externalDictionary object

Конфигурация внешнего словаря.

externalDictionary.
name
string

Обязательное поле. Имя внешнего словаря.

externalDictionary.
structure
object
Обязательное поле. Набор атрибутов внешнего словаря. Подробное описание см. в документации ClickHouse.
externalDictionary.
structure.
id
object

Один столбец с числовыми ключами для словаря.

Числовой ключ.

externalDictionary.
structure.
id.
name
string

Обязательное поле. Имя числового ключа.

externalDictionary.
structure.
key
object

Составной ключ для словаря, содержащего один или несколько столбцов с ключами. Подробнее см. в документации ClickHouse.

Составной ключ.

externalDictionary.
structure.
key.
attributes[]
object

Обязательное поле. Поля составного ключа.

Должен содержать хотя бы один элемент.

externalDictionary.
structure.
key.
attributes[].
name
string

Обязательное поле. Имя столбца.

externalDictionary.
structure.
key.
attributes[].
type
string

Обязательное поле. Тип столбца.

externalDictionary.
structure.
key.
attributes[].
nullValue
string

Значение по умолчанию для элемента без данных (например, пустая строка).

externalDictionary.
structure.
key.
attributes[].
expression
string

Выражение, описывающее атрибут, если применимо.

externalDictionary.
structure.
key.
attributes[].
hierarchical
boolean (boolean)

Признак поддержки иерархии. Значение по умолчанию false.

externalDictionary.
structure.
key.
attributes[].
injective
boolean (boolean)

Признакт инъективного отображения "id -> атрибут". Значение по умолчанию false.

externalDictionary.
structure.
rangeMin
object

Поле, содержащее начало диапазона для словарей, которые хранятся в памяти способомRANGE_HASHED. Подробнее см. вдокументации ClickHouse

externalDictionary.
structure.
rangeMin.
name
string

Обязательное поле. Имя столбца.

externalDictionary.
structure.
rangeMin.
type
string

Обязательное поле. Тип столбца.

externalDictionary.
structure.
rangeMin.
nullValue
string

Значение по умолчанию для элемента без данных (например, пустая строка).

externalDictionary.
structure.
rangeMin.
expression
string

Выражение, описывающее атрибут, если применимо.

externalDictionary.
structure.
rangeMin.
hierarchical
boolean (boolean)

Признак поддержки иерархии. Значение по умолчанию false.

externalDictionary.
structure.
rangeMin.
injective
boolean (boolean)

Признакт инъективного отображения "id -> атрибут". Значение по умолчанию false.

externalDictionary.
structure.
rangeMax
object

Поле, содержащее конец диапазона для словарей, которые хранятся в памяти способомRANGE_HASHED. Подробнее см. вдокументации ClickHouse

externalDictionary.
structure.
rangeMax.
name
string

Обязательное поле. Имя столбца.

externalDictionary.
structure.
rangeMax.
type
string

Обязательное поле. Тип столбца.

externalDictionary.
structure.
rangeMax.
nullValue
string

Значение по умолчанию для элемента без данных (например, пустая строка).

externalDictionary.
structure.
rangeMax.
expression
string

Выражение, описывающее атрибут, если применимо.

externalDictionary.
structure.
rangeMax.
hierarchical
boolean (boolean)

Признак поддержки иерархии. Значение по умолчанию false.

externalDictionary.
structure.
rangeMax.
injective
boolean (boolean)

Признакт инъективного отображения "id -> атрибут". Значение по умолчанию false.

externalDictionary.
structure.
attributes[]
object

Обязательное поле. Описание полей, доступных для запросов к базе данных. Подробнее см. в документации ClickHouse.

Должен содержать хотя бы один элемент.

externalDictionary.
structure.
attributes[].
name
string

Обязательное поле. Имя столбца.

externalDictionary.
structure.
attributes[].
type
string

Обязательное поле. Тип столбца.

externalDictionary.
structure.
attributes[].
nullValue
string

Значение по умолчанию для элемента без данных (например, пустая строка).

externalDictionary.
structure.
attributes[].
expression
string

Выражение, описывающее атрибут, если применимо.

externalDictionary.
structure.
attributes[].
hierarchical
boolean (boolean)

Признак поддержки иерархии. Значение по умолчанию false.

externalDictionary.
structure.
attributes[].
injective
boolean (boolean)

Признакт инъективного отображения "id -> атрибут". Значение по умолчанию false.

externalDictionary.
layout
object
Обязательное поле. Макет для хранения словаря в памяти. Подробное описание см. в документации ClickHouse.

Макет, определяющий способ хранения словаря в памяти.

externalDictionary.
layout.
type
string

Обязательное поле. Тип макета для внешнего словаря.

  • FLAT: Весь словарь хранится в памяти в виде плоских массивов. Доступно для любых источников словарей.
  • HASHED: Весь словарь хранится в памяти в виде хэш-таблицы. Доступно для любых источников словарей.
  • COMPLEX_KEY_HASHED: Аналогичен HASHED, для использования с составными ключами. Доступно для любых источников словарей.
  • RANGE_HASHED: Весь словарь хранится в памяти в виде хэш-таблицы, с упорядоченным массивом диапазонов и соответствующих им значений. Доступно для любых источников словарей.
  • CACHE: Словарь хранится в кэше с заданным количеством ячеек. Доступно для источников словарей MySQL, ClickHouse и HTTP.
  • COMPLEX_KEY_CACHE: Аналогичен CACHE, для использования с составными ключами. Доступно для источников словарей MySQL, ClickHouse и HTTP.
externalDictionary.
layout.
sizeInCells
string (int64)

Количество ячеек в кэше. Округляется до степени двойки. Применимо только для типов макета CACHE и COMPLEX_KEY_CACHE.

externalDictionary.
fixedLifetime
string (int64)
externalDictionary включает только одно из полей fixedLifetime, lifetimeRange

Жесткий интервал между обновлениями словаря.

externalDictionary.
lifetimeRange
object
Диапазон интервалов между обновлениями словаря, из которых может выбирать ClickHouse.
externalDictionary включает только одно из полей fixedLifetime, lifetimeRange

externalDictionary.
lifetimeRange.
min
string (int64)

Минимальное время жизни словаря.

externalDictionary.
lifetimeRange.
max
string (int64)

Максимальное время жизни словаря.

externalDictionary.
httpSource
object
HTTP-источник для словаря.
externalDictionary включает только одно из полей httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource

externalDictionary.
httpSource.
url
string

Обязательное поле. URL внешнего словаря, доступного по HTTP.

externalDictionary.
httpSource.
format
string

Обязательное поле. Формат данных. Допустимые значения: все форматы, поддерживаемые диалектом ClickHouse SQL.

externalDictionary.
mysqlSource
object
MySQL-источник для словаря.
externalDictionary включает только одно из полей httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource

externalDictionary.
mysqlSource.
db
string

Обязательное поле. Имя базы данных MySQL, к которой нужно подключаться.

externalDictionary.
mysqlSource.
table
string

Обязательное поле. Имя таблицы базы данных, которую следует использовать в качестве словаря ClickHouse.

externalDictionary.
mysqlSource.
port
string (int64)

Порт по умолчанию, который нужно использовать при подключении к реплике источника словаря.

Допустимые значения — от 0 до 65535 включительно.

externalDictionary.
mysqlSource.
user
string

Имя пользователя по умолчанию для реплик источника словаря.

externalDictionary.
mysqlSource.
password
string

Пароль пользователя по умолчанию для реплик источника словаря.

externalDictionary.
mysqlSource.
replicas[]
object

Обязательное поле. Список реплик базы данных MySQL, используемой в качестве источника словаря.

Должен содержать хотя бы один элемент.

externalDictionary.
mysqlSource.
replicas[].
host
string

Обязательное поле. Хост реплики MySQL.

Максимальная длина строки в символах — 253.

externalDictionary.
mysqlSource.
replicas[].
priority
string (int64)

Обязательное поле. Приоритет реплики, который ClickHouse должен учитывать при подключении. Реплике с наивысшим приоритетом должно соответствовать наименьшее значение в этом поле.

Значение должно быть больше 0.

externalDictionary.
mysqlSource.
replicas[].
port
string (int64)

Порт, который нужно использовать при подключении к реплике. Если для какой-либо реплики не указан порт, ClickHouse использует порт, указанный для источника.

Допустимые значения — от 0 до 65535 включительно.

externalDictionary.
mysqlSource.
replicas[].
user
string

Имя пользователя базы данных MySQL.

externalDictionary.
mysqlSource.
replicas[].
password
string

Пароль пользователя базы данных MySQL.

externalDictionary.
mysqlSource.
where
string

Критерии выбора данных в указанной таблице MySQL.

externalDictionary.
mysqlSource.
invalidateQuery
string

Запрос на проверку состояния словаря, который позволит извлекать только обновленные данные. Дополнительные сведения см. в документации ClickHouse.

externalDictionary.
clickhouseSource
object
ClickHouse-источник для словаря.
externalDictionary включает только одно из полей httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource

externalDictionary.
clickhouseSource.
db
string

Обязательное поле. Имя базы данных ClickHouse.

externalDictionary.
clickhouseSource.
table
string

Обязательное поле. Имя таблицы в указанной базе данных, используемой в качестве источника словаря.

externalDictionary.
clickhouseSource.
host
string

Обязательное поле. Хост ClickHouse для указанной базы данных.

Максимальная длина строки в символах — 253.

externalDictionary.
clickhouseSource.
port
string (int64)

Порт для подключения к хосту.

Допустимые значения — от 0 до 65535 включительно.

externalDictionary.
clickhouseSource.
user
string

Обязательное поле. Имя пользователя базы данных ClickHouse.

externalDictionary.
clickhouseSource.
password
string

Пароль пользователя базы данных ClickHouse.

externalDictionary.
clickhouseSource.
where
string

Критерии выбора данных в указанной таблице ClickHouse.

externalDictionary.
mongodbSource
object
MongoDB-источник для словаря.
externalDictionary включает только одно из полей httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource

externalDictionary.
mongodbSource.
db
string

Обязательное поле. Имя базы данных MongoDB.

externalDictionary.
mongodbSource.
collection
string

Обязательное поле. Имя коллекции в указанной базе данных, которую следует использовать в качестве источника словаря.

externalDictionary.
mongodbSource.
host
string

Обязательное поле. Хост MongoDB для указанной базы данных.

Максимальная длина строки в символах — 253.

externalDictionary.
mongodbSource.
port
string (int64)

Порт для подключения к хосту.

Допустимые значения — от 0 до 65535 включительно.

externalDictionary.
mongodbSource.
user
string

Обязательное поле. Имя пользователя базы данных MongoDB.

externalDictionary.
mongodbSource.
password
string

Пароль пользователя базы данных MongoDB.

externalDictionary.
postgresqlSource
object
PostgreSQL-источник для словаря.
externalDictionary включает только одно из полей httpSource, mysqlSource, clickhouseSource, mongodbSource, postgresqlSource

externalDictionary.
postgresqlSource.
db
string

Обязательное поле. Имя базы данных PostrgreSQL.

externalDictionary.
postgresqlSource.
table
string

Обязательное поле. Имя таблицы в указанной базе данных, используемой в качестве источника словаря.

externalDictionary.
postgresqlSource.
hosts[]
string

Обязательное поле. Имя хоста PostrgreSQL.

Должен содержать хотя бы один элемент.

externalDictionary.
postgresqlSource.
port
string (int64)

Порт для подключения к хосту.

Допустимые значения — от 0 до 65535 включительно.

externalDictionary.
postgresqlSource.
user
string

Обязательное поле. Имя пользователя базы данных PostrgreSQL.

externalDictionary.
postgresqlSource.
password
string

Пароль пользователя базы данных PostrgreSQL.

externalDictionary.
postgresqlSource.
invalidateQuery
string

Запрос на проверку состояния словаря, который позволит извлекать только обновленные данные. Дополнительные сведения см. в документации ClickHouse.

externalDictionary.
postgresqlSource.
sslMode
string

Режим SSL TCP/IP соединения с хостом PostgreSQL. Есть шесть режимов: disable, allow, prefer (используется по умолчанию), require, verify-ca, verify-full. Дополнительные сведения см. в документации PostgreSQL.

Ответ

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": true,
  "metadata": "object",

  //  включает только одно из полей `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": "object",
  // конец списка возможных полей

}

Ресурс Operation. Дополнительные сведения см. в разделе Объект Operation.

Поле Описание
id string

Идентификатор операции.

description string

Описание операции. Длина описания должна быть от 0 до 256 символов.

createdAt string (date-time)

Время создания ресурса в формате в RFC3339.

Строка в формате RFC3339.

createdBy string

Идентификатор пользователя или сервисного аккаунта, инициировавшего операцию.

modifiedAt string (date-time)

Время, когда ресурс Operation последний раз обновлялся. Значение в формате RFC3339.

Строка в формате RFC3339.

done boolean (boolean)

Если значение равно false — операция еще выполняется. Если true — операция завершена, и задано значение одного из полей error или response.

metadata object

Метаданные операции. Обычно в поле содержится идентификатор ресурса, над которым выполняется операция. Если метод возвращает ресурс Operation, в описании метода приведена структура соответствующего ему поля metadata.

error object
Описание ошибки в случае сбоя или отмены операции.
включает только одно из полей error, response

Описание ошибки в случае сбоя или отмены операции.

error.
code
integer (int32)

Код ошибки. Значение из списка google.rpc.Code.

error.
message
string

Текст ошибки.

error.
details[]
object

Список сообщений с подробными сведениями об ошибке.

response object
включает только одно из полей error, response

Результат операции в случае успешного завершения. Если исходный метод не возвращает никаких данных при успешном завершении, например метод Delete, поле содержит объект google.protobuf.Empty. Если исходный метод — это стандартный метод Create / Update, поле содержит целевой ресурс операции. Если метод возвращает ресурс Operation, в описании метода приведена структура соответствующего ему поля response.