Подключиться
Yandex Managed Service for ClickHouse

Управление схемами формата данных

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

Managed Service for ClickHouse позволяет вставлять (INSERT) и выводить (SELECT) данные в различных форматах. Большинство таких форматов — самоописываемые, то есть они уже содержат в себе схему формата данных, описывающую допустимые типы данных, их порядок и представление в этом формате. Это позволяет, например, сразу делать вставку из файла.

Примечание

Схема формата данных (format schema) описывает формат ввода или вывода данных, в то время как схема данных (data scheme) описывает структуру и устройство баз данных и таблиц ClickHouse, которые хранят эти данные. Эти понятия не являются взаимозаменяемыми.

Форматы данных Cap'n Proto и Protobuf (включая ProtobufSingle) не содержат в себе схему формата — данные представляются в бинарном виде без какой-либо информации о структуре. Перед началом работы с данными в этих форматах (например, перед вставкой в таблицу) необходимо подключить схему формата данных к кластеру Managed Service for ClickHouse. Это позволит правильно интерпретировать количество, порядок и тип значений при работе с бинарными данными.

Вы можете подключить к кластеру Managed Service for ClickHouse одну или несколько таких схем формата и использовать их для ввода и вывода требуемых данных в соответствующих форматах.

Важно

Чтобы использовать подключенные схемы формата, вставку данных в Managed Service for ClickHouse следует производить с помощью HTTP-интерфейса, т. к. в этом случае сериализация и десериализация данных производится на стороне сервера с использованием подключенных схем.

Подробнее о форматах данных см. в документации ClickHouse.

Примеры работы с форматами Cap'n Proto и Protobuf при вставке данных в кластер приведены в разделе Добавление данных в ClickHouse.

Перед подключением схемы формата данных

Managed Service for ClickHouse работает только со схемами формата данных, которые загружены в Yandex Object Storage и к которым предоставлен доступ на чтение. Перед подключением схемы к кластеру:

  1. Подготовьте файл со схемой формата (см. документацию Cap'n Proto и Protobuf).

  2. Загрузите файл со схемой формата данных в Yandex Object Storage.

  3. Настройте доступ к файлу схемы одним из способов:

  4. Получите ссылку на файл схемы.

Подключить схему формата данных

  1. В консоли управления перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse.
  2. Нажмите на имя нужного кластера и выберите вкладку Схемы формата данных.
  3. Нажмите кнопку Добавить схему.
  4. В диалоговом окне Добавление схемы заполните форму, указав в поле URL полученную ранее ссылку на файл со схемой формата.
  5. Нажмите кнопку Добавить.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы подключить схему формата данных к кластеру, выполните команду:

  • для формата Cap'n Proto:

    yc managed-clickhouse format-schema create "<имя схемы формата>" \
  --cluster-name="<имя кластера>" \
  --type="capnproto" \
  --uri="<ссылка на файл в Yandex Object Storage>"

  • для формата Protobuf:

    yc managed-clickhouse format-schema create "<имя схемы формата>" \
  --cluster-name="<имя кластера>" \
  --type="protobuf" \
  --uri="<ссылка на файл в Yandex Object Storage>"

Имя кластера можно запросить со списком кластеров в каталоге.

  1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

    О том, как создать такой файл, см. в разделе Создание ClickHouse-кластера.

  2. Добавьте к описанию кластера Managed Service for ClickHouse блок format_schema:

    resource "yandex_mdb_clickhouse_cluster" "<имя кластера>" {
  ...
  format_schema {
    name = "<имя схемы>"
    type = "<тип схемы: FORMAT_SCHEMA_TYPE_CAPNPROTO или FORMAT_SCHEMA_TYPE_PROTOBUF>"
    uri  = "<ссылка на файл схемы формата данных в Yandex Object Storage>"
  }
}

  3. Проверьте корректность настроек.

    1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

    2. Выполните команду:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

  4. Подтвердите изменение ресурсов.

    1. Выполните команду для просмотра планируемых изменений:

      terraform plan

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

    2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

        terraform apply

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

Ограничения по времени

Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse:

  • создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
  • изменение — 90 минут;
  • удаление — 30 минут.

Операции, длящиеся дольше указанного времени, прерываются.

Как изменить эти ограничения?

Добавьте к описанию кластера блок timeouts, например:

resource "yandex_mdb_clickhouse_cluster" "<имя кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

Воспользуйтесь методом API create и передайте в запросе:

  • Идентификатор кластера в параметре clusterId. Идентификатор кластера можно получить со списком кластеров в каталоге.
  • Имя схемы формата в параметре formatSchemaName.
  • Тип схемы: FORMAT_SCHEMA_TYPE_CAPNPROTO или FORMAT_SCHEMA_TYPE_PROTOBUF в параметре type.
  • Ссылку на файл в Yandex Object Storage в параметре uri.

Изменить схему формата данных

Managed Service for ClickHouse не отслеживает изменения в файле со схемой формата данных, который находится в бакете Yandex Object Storage.

Чтобы актуализировать содержимое схемы, которая уже подключена к кластеру:

  1. Загрузите файл с актуальной схемой формата данных в Yandex Object Storage.
  2. Получите ссылку на этот файл.
  3. Измените параметры схемы формата данных, подключенной к Managed Service for ClickHouse, передав новую ссылку на файл со схемой формата.
  1. В консоли управления перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse.
  2. Нажмите на имя нужного кластера и выберите вкладку Схемы формата данных.
  3. Выберите нужную схему, нажмите на значок и выберите пункт Изменить.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы изменить ссылку на файл в объектном хранилище со схемой формата данных, выполнив команду:

yc managed-clickhouse format-schema update "<имя схемы данных>" \
  --cluster-name="<имя кластера>" \
  --uri="<новая ссылка на файл в Yandex Object Storage>"

Имя схемы можно запросить со списком схем формата данных в кластере; имя кластера можно запросить со списком кластеров в каталоге.

  1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

    О том, как создать такой файл, см. в разделе Создание ClickHouse-кластера.

  2. Измените в описании кластера Managed Service for ClickHouse значение параметра uri в блоке format_schema:

    resource "yandex_mdb_clickhouse_cluster" "<имя кластера>" {
  ...
  format_schema {
    name = "<имя схемы>"
    type = "<тип схемы>"
    uri  = "<новая ссылка на файл схемы в Yandex Object Storage>"
  }
}

  3. Проверьте корректность настроек.

    1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

    2. Выполните команду:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

  4. Подтвердите изменение ресурсов.

    1. Выполните команду для просмотра планируемых изменений:

      terraform plan

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

    2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

        terraform apply

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

    Подробнее см. в документации провайдера Terraform.

    Ограничения по времени

    Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse:

    • создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
    • изменение — 90 минут;
    • удаление — 30 минут.

    Операции, длящиеся дольше указанного времени, прерываются.

    Как изменить эти ограничения?

    Добавьте к описанию кластера блок timeouts, например:

    resource "yandex_mdb_clickhouse_cluster" "<имя кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

Воспользуйтесь методом API update и передайте в запросе:

  • Идентификатор кластера в параметре clusterId. Идентификатор кластера можно получить со списком кластеров в каталоге.

  • Имя схемы формата в параметре formatSchemaName. Имя схемы можно запросить со списком схем формата данных в кластере.

  • Новую ссылку на файл в Yandex Object Storage в параметре uri.

  • Список полей конфигурации кластера, подлежащих изменению, в параметре updateMask.

    Важно

    Этот метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).

Отключить схему формата данных

Примечание

После отключения схемы формата данных соответствующий объект остается в бакете Yandex Object Storage. Если этот объект со схемой формата больше не нужен, его можно удалить.

  1. В консоли управления перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse.
  2. Нажмите на имя нужного кластера и выберите вкладку Схемы формата данных.
  3. Выберите нужную схему, нажмите на значок и выберите пункт Удалить.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы отключить схему формата данных, выполните команду:

yc managed-clickhouse format-schema delete "<имя схемы формата>" \
  --cluster-name="<имя кластера>"

Имя схемы можно запросить со списком схем формата данных в кластере; имя кластера можно запросить со списком кластеров в каталоге.

  1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

    О том, как создать такой файл, см. в разделе Создание ClickHouse-кластера.

  2. Удалите из описания кластера Managed Service for ClickHouse блок описания нужной схемы формата данных format_schema.

  3. Проверьте корректность настроек.

    1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.

    2. Выполните команду:

      terraform validate

      Если в файлах конфигурации есть ошибки, Terraform на них укажет.

  4. Подтвердите изменение ресурсов.

    1. Выполните команду для просмотра планируемых изменений:

      terraform plan

      Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.

    2. Если вас устраивают планируемые изменения, внесите их:

      1. Выполните команду:

        terraform apply

      2. Подтвердите изменение ресурсов.

      3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

Ограничения по времени

Провайдер Terraform ограничивает время на выполнение операций с кластером Managed Service for ClickHouse:

  • создание, в т. ч. путем восстановления из резервной копии, — 60 минут;
  • изменение — 90 минут;
  • удаление — 30 минут.

Операции, длящиеся дольше указанного времени, прерываются.

Как изменить эти ограничения?

Добавьте к описанию кластера блок timeouts, например:

resource "yandex_mdb_clickhouse_cluster" "<имя кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

Воспользуйтесь методом API delete и передайте в запросе:

Получить список схем формата данных в кластере

  1. В консоли управления перейдите на страницу каталога и выберите сервис Managed Service for ClickHouse.
  2. Нажмите на имя нужного кластера и выберите вкладку Схемы формата данных.

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы получить список схем формата данных в кластере, выполните команду:

yc managed-clickhouse format-schema list --cluster-name="<имя кластера>"

Имя кластера можно запросить со списком кластеров в каталоге.

Воспользуйтесь методом API list и передайте в запросе идентификатор кластера в параметре clusterId.

Идентификатор кластера можно получить со списком кластеров в каталоге.

Получить детальную информацию о схеме формата данных

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.

По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.

Чтобы получить детальную информацию о схеме формата данных, выполните команду:

yc managed-clickhouse format-schema get "<имя схемы формата>" \
  --cluster-name="<имя кластера>"

Имя схемы можно запросить со списком схем формата данных в кластере; имя кластера можно запросить со списком кластеров в каталоге.

Воспользуйтесь методом API get и передайте в запросе:

В этой статье: