Yandex Cloud
Поиск
Связаться с намиПодключиться
  • Документация
  • Блог
  • Все сервисы
  • Статус работы сервисов
    • Популярные
    • Инфраструктура и сеть
    • Платформа данных
    • Контейнеры
    • Инструменты разработчика
    • Бессерверные вычисления
    • Безопасность
    • Мониторинг и управление ресурсами
    • Машинное обучение
    • Бизнес-инструменты
  • Все решения
    • По отраслям
    • По типу задач
    • Экономика платформы
    • Безопасность
    • Техническая поддержка
    • Каталог партнёров
    • Обучение и сертификация
    • Облако для стартапов
    • Облако для крупного бизнеса
    • Центр технологий для общества
    • Облако для интеграторов
    • Поддержка IT-бизнеса
    • Облако для фрилансеров
    • Обучение и сертификация
    • Блог
    • Документация
    • Контент-программа
    • Мероприятия и вебинары
    • Контакты, чаты и сообщества
    • Идеи
    • Истории успеха
    • Тарифы Yandex Cloud
    • Промоакции и free tier
    • Правила тарификации
  • Документация
  • Блог
Проект Яндекса
© 2025 ООО «Яндекс.Облако»
Yandex Data Transfer
  • Доступные трансферы
  • Начало работы
    • Все инструкции
    • Подготовка к трансферу
      • Управление эндпоинтами
      • Миграция эндпоинтов в другую зону доступности
        • Источник
        • Приемник
    • Управление трансфером
    • Работа с базами данных во время трансфера
    • Мониторинг состояния трансфера
  • Решение проблем
  • Управление доступом
  • Справочник Terraform
  • Метрики Monitoring
  • Аудитные логи Audit Trails
  • Публичные материалы
  • Обучающие курсы

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

  • Сценарии передачи данных из ClickHouse®
  • Подготовка базы данных источника
  • Настройка эндпоинта-источника ClickHouse®
  • Кластер Managed Service for ClickHouse®
  • Пользовательская инсталляция
  • Фильтр таблиц
  • Настройка приемника данных
  • Решение проблем, возникающих при переносе данных
  • Не добавляются новые таблицы
  • Не переносятся данные
  • Неподдерживаемый диапазон дат
  1. Пошаговые инструкции
  2. Настройка эндпоинтов
  3. ClickHouse
  4. Источник

Передача данных из эндпоинта-источника ClickHouse®

Статья создана
Yandex Cloud
Обновлена 10 апреля 2025 г.
  • Сценарии передачи данных из ClickHouse®
  • Подготовка базы данных источника
  • Настройка эндпоинта-источника ClickHouse®
    • Кластер Managed Service for ClickHouse®
    • Пользовательская инсталляция
    • Фильтр таблиц
  • Настройка приемника данных
  • Решение проблем, возникающих при переносе данных
    • Не добавляются новые таблицы
    • Не переносятся данные
    • Неподдерживаемый диапазон дат

С помощью сервиса Yandex Data Transfer вы можете переносить данные из базы ClickHouse® и реализовывать различные сценарии переноса, обработки и трансформации данных. Для реализации трансфера:

  1. Ознакомьтесь с возможными сценариями передачи данных.
  2. Подготовьте базу данных ClickHouse® к трансферу.
  3. Настройте эндпоинт-источник в Yandex Data Transfer.
  4. Настройте один из поддерживаемых приемников данных.
  5. Создайте и запустите трансфер.
  6. Выполняйте необходимые действия по работе с базой и контролируйте трансфер.
  7. При возникновении проблем, воспользуйтесь готовыми решениями по их устранению.

Сценарии передачи данных из ClickHouse®Сценарии передачи данных из ClickHouse®

Миграция — перенос данных из одного хранилища в другое. Часто это перенос базы из устаревших локальных баз в управляемые облачные.

  • Миграция кластера ClickHouse®.
  • Перераспределение данных по шардам.

Подробное описание возможных сценариев передачи данных в Yandex Data Transfer см. в разделе Практические руководства.

Подготовка базы данных источникаПодготовка базы данных источника

Примечание

Yandex Data Transfer не может переносить базы данных ClickHouse®, в названии которых есть дефис.

При переносе таблиц с движками, отличными от движков на базе ReplicatedMergeTree и Distributed, в многохостовом кластере ClickHouse® трансфер завершится с ошибкой: the following tables have not Distributed or Replicated engines and are not yet supported.

Managed Service for ClickHouse®
ClickHouse®
  1. Убедитесь, что переносимые таблицы используют движки семейства MergeTree. Будут перенесены только эти таблицы и материализованные представления (MaterializedView).

    В случае многохостового кластера будут перенесены таблицы и материализованные представления только с движками на базе ReplicatedMergeTree либо Distributed. Проверьте, что данные таблицы и представления присутствуют на всех хостах кластера.

  2. Создайте пользователя с доступом к базе источника. В настройках пользователя укажите для параметра Max execution time значение не менее 1000000.

  1. Убедитесь, что переносимые таблицы используют движки семейства MergeTree. Будут перенесены только эти таблицы и материализованные представления (MaterializedView).

    В случае многохостового кластера будут перенесены таблицы и материализованные представления только с движками на базе ReplicatedMergeTree либо Distributed. Проверьте, что данные таблицы и представления присутствуют на всех хостах кластера.

  2. Если вы не планируете использовать для подключения к внешнему кластеру сервис Cloud Interconnect или VPN, разрешите подключения к такому кластеру из интернета с IP-адресов, используемых сервисом Data Transfer.

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

  3. Настройте доступ к кластеру-источнику из Yandex Cloud.

  4. Создайте пользователя с доступом к базе источника. В настройках пользователя укажите для параметра Max execution time значение не менее 1000000.

Настройка эндпоинта-источника ClickHouse®Настройка эндпоинта-источника ClickHouse®

При создании или изменении эндпоинта вы можете задать:

  • Настройки подключения к кластеру Yandex Managed Service for ClickHouse® или пользовательской инсталляции, в т. ч. на базе виртуальных машин Yandex Compute Cloud. Эти параметры обязательные.
  • Дополнительные параметры.

Кластер Managed Service for ClickHouse®Кластер Managed Service for ClickHouse®

Важно

Для создания или редактирования эндпоинта управляемой базы данных вам потребуется роль managed-clickhouse.viewer или примитивная роль viewer, выданная на каталог кластера этой управляемой базы данных.

Подключение к БД с указанием идентификатора кластера в Yandex Cloud.

Консоль управления
CLI
Terraform
API
  • Managed кластер — из списка выберите имя кластера, к которому необходимо подключиться.

  • Группа шардов — укажите группу шардов, из которой будут передаваться данные. Если значение не указано, будут передаваться данные из всех шардов.

  • Пользователь — укажите имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • Пароль — укажите пароль пользователя для доступа к базе данных.

  • База данных — укажите имя базы данных в выбранном кластере.

  • Группы безопасности — выберите облачную сеть для размещения эндпоинта и группы безопасности для сетевого трафика. Это позволит применить указанные правила групп безопасности к ВМ и кластерам в выбранной сети без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.

    Убедитесь, что выбранные группы безопасности настроены.

  • Тип эндпоинта — clickhouse-source.
  • --cluster-id — идентификатор кластера, к которому необходимо подключиться.

  • --cluster-name — группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов.

  • --database — имя базы данных.

  • --user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • --security-group — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.

    Убедитесь, что указанные группы безопасности настроены.

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

    • --raw-password — пароль в текстовом виде.

    • --password-file — путь к файлу с паролем.

  • Тип эндпоинта — clickhouse_source.
  • connection.connection_options.mdb_cluster_id — идентификатор кластера, к которому необходимо подключиться.

  • clickhouse_cluster_name — группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов.

  • subnet_id — идентификатор подсети, в которой находится кластер. Трансфер будет использовать эту подсеть для доступа к кластеру. Если идентификатор не указан, то кластер должен быть доступен из интернета.

    Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.

  • security_groups — группы безопасности для сетевого трафика.

    Правила групп безопасности применяются к трансферу. Они позволяют открыть сетевой доступ с ВМ трансфера к кластеру. Подробнее см. в разделе Сеть в Yandex Data Transfer.

    Группы безопасности и подсеть subnet_id, если она указана, должны принадлежать той же сети, в которой размещен кластер.

    Примечание

    В Terraform сеть для групп безопасности задавать не нужно.

    Убедитесь, что указанные группы безопасности настроены.

  • connection.connection_options.database — имя базы данных.

  • connection.connection_options.user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • connection.connection_options.password.raw — пароль в текстовом виде.

Пример структуры конфигурационного файла:

resource "yandex_datatransfer_endpoint" "<имя_эндпоинта_в_Terraform>" {
  name = "<имя_эндпоинта>"
  settings {
    clickhouse_source {
      clickhouse_cluster_name="<группа_шардов>"
      security_groups = ["<список_идентификаторов_групп_безопасности>"]
      subnet_id       = "<идентификатор_подсети>"
      connection {
        connection_options {
          mdb_cluster_id = "<идентификатор_кластера>"
          database       = "<имя_переносимой_базы_данных>"
          user           = "<имя_пользователя_для_подключения>"
          password {
            raw = "<пароль_пользователя>"
          }
        }
      }
      <дополнительные_настройки_эндпоинта>
    }
  }
}

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

  • securityGroups — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.

    Убедитесь, что указанные группы безопасности настроены.

  • mdbClusterId — идентификатор кластера, к которому необходимо подключиться.

  • clickhouseClusterName — группа шардов, из которой будут передаваться данные. Если параметр не указан, будут передаваться данные из всех шардов.

  • database — имя базы данных.

  • user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • password.raw — пароль пользователя для доступа к базе данных (в текстовом виде).

Пользовательская инсталляцияПользовательская инсталляция

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

Консоль управления
CLI
Terraform
API
  • Шарды

    • Шард — укажите строку, которая позволит сервису отличать шарды друг от друга. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя.
    • Хосты — укажите FQDN или IP-адреса хостов, входящих в шард.
  • HTTP-порт — укажите номер порта, который сервис Data Transfer будет использовать для подключения.

    При подключении через HTTP-порт:

    • Для необязательных полей используются значения по умолчанию, если они заданы.
    • Поддерживается запись сложных типов (array, tuple и т. д.).
  • Нативный порт — укажите номер нативного порта, который сервис Data Transfer будет использовать для подключения.

  • SSL — включите, если кластер поддерживает только шифрованные соединения.

  • Сертификат CA — если требуется шифрование передаваемых данных, например для соответствия требованиям PCI DSS, загрузите файл сертификата или добавьте его содержимое в текстовом виде.

    Важно

    Если не добавить сертификат, трансфер может завершиться ошибкой.

  • Идентификатор подсети — выберите или создайте подсеть в нужной зоне доступности. Трансфер будет использовать эту подсеть для доступа к кластеру.

    Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.

  • Пользователь — укажите имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • Пароль — укажите пароль пользователя для доступа к базе данных.

  • База данных — укажите имя базы данных в выбранном кластере.

  • Группы безопасности — выберите облачную сеть для размещения эндпоинта и группы безопасности для сетевого трафика.

    Это позволит применить к ВМ и кластерам в выбранной сети указанные правила групп безопасности без изменения настроек этих ВМ и кластеров. Подробнее см. в разделе Сеть в Yandex Data Transfer.

  • Тип эндпоинта — clickhouse-source.
  • --cluster-name — имя кластера, из которого будут передаваться данные.

  • --host — список IP-адресов или FQDN хостов, к которым необходимо подключиться, в формате {имя_шарда}:{IP-адрес_или_FQDN_хоста}. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя шарда.

  • http-port — номер порта, который сервис Data Transfer будет использовать для подключения по HTTP.

  • native-port — номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®.

  • --ca-certificate — сертификат CA, если требуется шифрование передаваемых данных, например для соответствия требованиям PCI DSS.

    Важно

    Если не добавить сертификат, трансфер может завершиться ошибкой.

  • --subnet-id — идентификатор подсети, в которой находится хост. Трансфер будет использовать эту подсеть для доступа к хосту.

  • --database — имя базы данных.

  • --user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • --security-group — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.

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

    • --raw-password — пароль в текстовом виде.

    • --password-file — путь к файлу с паролем.

  • Тип эндпоинта — clickhouse_source.
  • Настройки шардов:

    • connection.connection_options.on_premise.shards.name — имя шарда, с помощью которого сервис сможет отличать шарды друг от друга. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя.
    • connection.connection_options.on_premise.shards.hosts — укажите FQDN или IP-адреса хостов, входящих в шард.
  • connection.connection_options.on_premise.http_port — номер порта, который сервис Data Transfer будет использовать для подключения по HTTP.

  • connection.connection_options.on_premise.native_port — номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®.

  • connection.connection_options.on_premise.tls_mode.enabled.ca_certificate — сертификат CA, если требуется шифрование передаваемых данных, например, для соответствия требованиям PCI DSS.

    Важно

    Если не добавить сертификат, трансфер может завершиться ошибкой.

  • clickhouse_cluster_name — имя кластера, из которого будут передаваться данные.
  • subnet_id — идентификатор подсети, в которой находится кластер. Трансфер будет использовать эту подсеть для доступа к кластеру. Если идентификатор не указан, то кластер должен быть доступен из интернета.

    Если значение в этом поле задано для обоих эндпоинтов, то обе подсети должны быть размещены в одной зоне доступности.

  • security_groups — группы безопасности для сетевого трафика.

    Правила групп безопасности применяются к трансферу. Они позволяют открыть сетевой доступ с ВМ трансфера к ВМ c базой данных. Подробнее см. в разделе Сеть в Yandex Data Transfer.

    Группы безопасности должны принадлежать той же сети, что и подсеть subnet_id, если она указана.

    Примечание

    В Terraform сеть для групп безопасности задавать не нужно.

  • connection.connection_options.database — имя базы данных.

  • connection.connection_options.user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • connection.connection_options.password.raw — пароль в текстовом виде.

Пример структуры конфигурационного файла:

resource "yandex_datatransfer_endpoint" "<имя_эндпоинта_в_Terraform>" {
  name = "<имя_эндпоинта>"
  settings {
    clickhouse_source {
      clickhouse_cluster_name="<имя_кластера>"
      security_groups = ["<список_идентификаторов_групп_безопасности>"]
      subnet_id       = "<идентификатор_подсети>"
      connection {
        connection_options {
          on_premise {
            http_port   = "<порт_для_подключения_по_HTTP>"
            native_port = "<порт_для_подключения_к_нативному_интерфейсу>"
            shards {
              name  = "<имя_шарда>"
              hosts = [ "список IP-адресов или FQDN хостов шарда" ]
            }
            tls_mode {
              enabled {
                ca_certificate = "<сертификат_в_формате_PEM>"
              }
            }
          }
          database = "<имя_переносимой_базы_данных>"
          user     = "<имя_пользователя_для_подключения>"
          password {
            raw = "<пароль_пользователя>"
          }
        }
      }
      <дополнительные_настройки_эндпоинта>
    }
  }
}

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

  • onPremise — параметры подключения к базе данных:
    • shards – настройки шардов:

      • name — имя шарда, с помощью которого сервис сможет отличать шарды друг от друга. Если в пользовательской инсталляции шардирование выключено, укажите произвольное имя.
      • hosts — укажите FQDN или IP-адреса хостов, входящих в шард.
    • httpPort — номер порта, который сервис Data Transfer будет использовать для подключения по HTTP.

    • nativePort — номер порта, который сервис Data Transfer будет использовать для подключения к нативному интерфейсу ClickHouse®.

    • tlsMode — параметры шифрования передаваемых данных, если оно требуется, например для соответствия требованиям PCI DSS.

      • disabled — отключено.
      • enabled — включено
        • caCertificate — сертификат CA.

          Важно

          Если не добавить сертификат, трансфер может завершиться ошибкой.

    • subnetId — идентификатор подсети, в которой находится хост. Трансфер будет использовать эту подсеть для доступа к хосту.

  • clickhouseClusterName — имя кластера, из которого будут передаваться данные.
  • securityGroups — группы безопасности для сетевого трафика, правила которых применятся к ВМ и кластерам без изменения их настроек. Подробнее см. в разделе Сеть в Yandex Data Transfer.

  • database — имя базы данных.

  • user — имя пользователя, под которым сервис Data Transfer будет подключаться к базе данных.

  • password.raw — пароль пользователя для доступа к базе данных (в текстовом виде).

Фильтр таблицФильтр таблиц

Консоль управления
CLI
Terraform
API
  • Список включённых таблиц — будут передаваться данные только из таблиц этого списка.

    Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.

  • Список исключённых таблиц — данные таблиц из этого списка передаваться не будут.

Имена включенных и исключенных таблиц должны соответствовать правилам именования идентификаторов в ClickHouse®. Подробнее читайте в документации ClickHouse®. Экранирование двойных кавычек не требуется.

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

  • --include_table — список включенных таблиц. Будут передаваться данные только из таблиц этого списка.

    Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.

  • --exclude_table — список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.

Если списки не указаны, передаются данные из всех таблиц.

  • include_tables — список включенных таблиц. Будут передаваться данные только из таблиц этого списка.

    Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.

  • exclude_tables — список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.

Если списки не указаны, передаются данные из всех таблиц.

  • includeTables — список включенных таблиц. Будут передаваться данные только из таблиц этого списка.

    Добавление новых таблиц при редактировании эндпоинта, использующегося в трансферах типа Копирование и репликация или Репликация в статусе Реплицируется, не приведет к загрузке истории данных по этим таблицам. Чтобы добавить таблицу с ее историческими данными, используйте поле Список объектов для переноса в настройках трансфера.

  • excludeTables — список исключенных таблиц. Данные таблиц из этого списка передаваться не будут.

Если списки не указаны, передаются данные из всех таблиц.

Настройка приемника данныхНастройка приемника данных

Настройте эндпоинт-приемник:

  • ClickHouse®.

Полный список поддерживаемых источников и приемников в Yandex Data Transfer см. в разделе Доступные трансферы.

После настройки источника и приемника данных создайте и запустите трансфер.

Решение проблем, возникающих при переносе данныхРешение проблем, возникающих при переносе данных

  • Не добавляются новые таблицы
  • Не переносятся данные
  • Неподдерживаемый диапазон дат

См. полный список рекомендаций в разделе Решение проблем.

Не добавляются новые таблицыНе добавляются новые таблицы

​В трансфер типа Копирование и репликация не добавляются новые таблицы.

Решение:

  1. Создайте таблицы в базе-приемнике вручную. Чтобы трансфер работал, при создании таблицы:

    1. Добавьте в нее служебные поля трансфера:

      __data_transfer_commit_time timestamp,
      __data_transfer_delete_time timestamp
      
    2. Используйте движок ReplacingMergeTree:

      ENGINE = ReplacingMergeTree
      
  2. Создайте отдельный трансфер типа Копирование и репликация и добавьте в список объектов для переноса только новые таблицы. При этом исходный трансфер типа Копирование и репликация можно не деактивировать. Активируйте новый трансфер, а после перехода в статус Реплицируется деактивируйте его.

    Чтобы добавить другие таблицы, замените ими список объектов для переноса в созданном отдельном трансфере, вновь активируйте его, а после перехода в статус Реплицируется деактивируйте.

    Примечание

    Так как два трансфера одновременно переносили данные, то в новых таблицах на приемнике присутствуют дубликаты записей. Чтобы скрыть их, выполните запрос SELECT * from TABLE <имя_таблицы> FINAL, а чтобы удалить — запрос OPTIMIZE TABLE <имя_таблицы>.

Не переносятся данныеНе переносятся данные

При попытке перенести данные из источника ClickHouse® выводится ошибка:


Syntax error: failed at position 25 ('-'): <детали_ошибки>. Expected one of: token, Dot, UUID, alias, AS, identifier, FINAL, SAMPLE, INTO OUTFILE, FORMAT, SETTINGS, end of query

Решение:

Yandex Data Transfer не может переносить базы данных, в названии которых есть дефис. Переименуйте базу данных, если есть такая возможность.

Неподдерживаемый диапазон датНеподдерживаемый диапазон дат

Если в переносимых данных есть даты вне поддерживаемых диапазонов, ClickHouse® возвращает ошибку:

TYPE_ERROR [target]: failed to run (abstract1 source): failed to push items from 0 to 1 in batch:
Push failed: failed to push 1 rows to ClickHouse shard 0:
ClickHouse Push failed: Unable to exec changeItem: clickhouse:
dateTime <имя_поля> must be between 1900-01-01 00:00:00 and 2262-04-11 23:47:16

Поддерживаемые диапазоны дат в ClickHouse®:

  • Для полей с типом DateTime64 — с 1900-01-01 по 2299-12-31. Подробнее см. в документации ClickHouse®.
  • Для полей с типом DateTime — с 1970-01-01 по 2106-02-07. Подробнее см. в документации ClickHouse®.

Решение: используйте один из вариантов:

  • Приведите все даты в базе-источнике к поддерживаемому в ClickHouse® диапазону.
  • В параметрах эндпоинта-источника исключите таблицу с некорректными датами из трансфера.
  • В параметрах трансфера укажите трансформер Преобразовать значения в строки. В этом случае при трансфере изменится тип поля.

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

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

Предыдущая
Источник
Следующая
Приемник
Проект Яндекса
© 2025 ООО «Яндекс.Облако»