Yandex.Cloud
  • Сервисы
  • Почему Yandex.Cloud
  • Сообщество
  • Тарифы
  • Документация
  • Связаться с нами
Подключиться
Yandex Managed Service for ClickHouse
  • Начало работы
  • Пошаговые инструкции
    • Все инструкции
    • Информация об имеющихся кластерах
    • Создание кластера
    • Подключение к базе данных
    • Остановка и запуск кластера
    • SQL-запросы в консоли управления
    • Изменение настроек кластера и базы данных
    • Подключение внешних словарей
    • Подключение собственной геобазы
    • Подключение моделей машинного обучения
    • Управление схемами формата данных
    • Подключение к DataLens
    • Изменение версии ClickHouse
    • Управление хостами ClickHouse
    • Управление хостами ZooKeeper
    • Управление базами данных
    • Управление пользователями БД
    • Управление резервными копиями
    • Управление шардами
    • Управление группами шардов
    • Удаление кластера
  • Сценарии использования
    • Добавление данных в БД
    • Миграция данных ClickHouse
    • Шардирование таблиц
    • Использование гибридного хранилища
    • Получение данных из Managed Service for Apache Kafka®
  • Концепции
    • Взаимосвязь ресурсов сервиса
    • Классы хостов
      • Действующие классы хостов
      • Архив
        • До 1 июня 2020 года
      • Использование устаревших классов хостов
    • Сеть в Managed Service for ClickHouse
    • Квоты и лимиты
    • Типы хранилища
    • Резервные копии
    • Репликация
    • Словари
    • Шардирование
    • Поддерживаемые клиенты
    • Политика работа с версиями ClickHouse
  • Управление доступом
  • Правила тарификации
    • Действующие правила
    • Архив
      • До 1 января 2019 года
      • С 1 января до 1 марта 2019 года
      • С 1 марта 2019 года до 1 февраля 2020 года
  • Справочник API
    • Аутентификация в API
    • gRPC
      • Обзор
      • BackupService
      • ClusterService
      • DatabaseService
      • MlModelService
      • ResourcePresetService
      • UserService
      • VersionsService
      • OperationService
    • REST
      • Обзор
      • Backup
        • Обзор
        • get
        • list
      • Cluster
        • Обзор
        • addHosts
        • addShard
        • addZookeeper
        • backup
        • create
        • createExternalDictionary
        • createShardGroup
        • delete
        • deleteExternalDictionary
        • deleteHosts
        • deleteShard
        • deleteShardGroup
        • get
        • getShard
        • getShardGroup
        • list
        • listBackups
        • listHosts
        • listLogs
        • listOperations
        • listShardGroups
        • listShards
        • move
        • restore
        • start
        • stop
        • streamLogs
        • update
        • updateShard
        • updateShardGroup
      • Database
        • Обзор
        • create
        • delete
        • get
        • list
      • MlModel
        • Обзор
        • create
        • delete
        • get
        • list
        • update
      • ResourcePreset
        • Обзор
        • get
        • list
      • User
        • Обзор
        • create
        • delete
        • get
        • grantPermission
        • list
        • revokePermission
        • update
      • Versions
        • Обзор
        • list
      • Operation
        • Обзор
        • get
  • Вопросы и ответы
    • Общие вопросы
    • Вопросы о ClickHouse
    • Все вопросы на одной странице
  1. Сценарии использования
  2. Добавление данных в БД

Добавление данных в ClickHouse

  • Обычная вставка данных
  • Вставка данных с указанием схемы формата данных
  • Пример работы со схемой формата при вставке данных
  • Перед началом работы
    • Установка зависимостей
    • Подготовка схем формата данных
    • Подготовка скриптов
    • Вставка данных

Обычная вставка данных

Для рутинного добавления данных в базу данных используйте запрос INSERT, описанный в документации ClickHouse. INSERT-запросы рекомендуется отправлять не чаще одного раза в секунду.

Чтобы загружать большое количество информации, используйте сжатие данных при передаче: например, его можно включить для HTTP или clickhouse-client. Подробнее см. в документации 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.

Пример работы со схемой формата при вставке данных

Пример проверялся в следующем окружении:

  • Виртуальная машина в Облаке c Ubuntu 20.04 LTS.
  • Bash: 5.0.16.
  • clickhouse-client: 20.10.2.20.
  • capnproto: 0.7.0.
  • protobuf-compiler: 3.6.1.
  • Python: 3.8.5; pip3: 20.0.2.

Допустим, что создан однохостовый кластер Managed Service for ClickHouse chclusterс базой данных db1 и нужно вставить данные о пользователях в таблицу db1.users. Пусть каждая запись о пользователе содержит следующую информацию:

  • идентификатор пользователя id;
  • имя пользователя name.

Чтобы вставить данные о пользователях в форматах Cap'n Proto и Protobuf в таблицу db1.users:

  1. Установите зависимости.
  2. Подготовьте схемы формата данных.
  3. Подготовьте скрипты.
  4. Вставьте данные.

Перед началом работы

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

    В этом сценарии использования для иллюстрации принимается, что:

    • идентификатор пользователя id представлен в виде целого беззнакового 64-битного числа (Uint64 в Cap'n Proto и ClickHouse, uint64 в Protobuf);
    • имя пользователя name представлено в виде строки (Text в Cap'n Proto, string в Protobuf, String в ClickHouse).

    Подробнее о поддерживаемых типах данных см. в документации Cap'n Proto, Protobuf и ClickHouse.

  2. Подключитесь к кластеру и cоздайте таблицу db1.users нужного вида, если ее еще не существует:

    CREATE TABLE IF NOT EXISTS db1.users (id UInt64, name String)
    ENGINE = MergeTree() ORDER BY id;
    

Установка зависимостей

sudo apt update && sudo apt install -y python3 python3-pip capnproto protobuf-compiler && \
pip3 install protobuf varint pycapnp 

Подготовка схем формата данных

  1. Создайте файл с описанием схемы:

    Cap'n Proto
    Protobuf

    user.capnp

    @0xbec0f3f99cec4fbf;
    
    struct User {
      id @0 :UInt64;
      name @1 :Text;
    }
    

    Подробнее о формате файла см. в документации Cap'n Proto.

    user.proto

    syntax = "proto3";
    
    message User {
      uint64 id = 1;
      string name = 2;
    };
    

    Подробнее о формате файла см. в документации Protobuf.

  2. Загрузите файл в Object Storage и получите ссылку на него.

  3. Подключите схему формата данных к кластеру chcluster:

    • Для схемы формата данных Cap'n Proto (файл user.capnp) задайте имя schema-capnproto.
    • Для схемы формата данных Protobuf (файл user.protobuf) задайте имя schema-protobuf.

Подготовка скриптов

Эти Python-скрипты подготавливают тестовые данные о пользователях в нужных форматах и вставляют их в таблицу кластера.

Примечание

Скрипты на Python приведены в демонстрационных целях. Вы можете подготовить и вставить бинарные данные в требуемом формате, создав аналогичный скрипт на другом языке программирования.

Чтобы подготовить скрипты:

  1. Cкомпилируйте файл схемы Protobuf user.proto для Python:

    protoc user.proto --python_out .
    

    Будет сгенерирован файл user_pb2.py.

  2. Создайте файлы с кодом Python:

    Cap'n Proto
    Protobuf

    capnproto-example.py

    import requests
    import io
    import capnp
    from user_capnp import User
    
    DB_HOST="<FQDN хоста ClickHouse>"
    DB_NAME="db1"
    DB_USER="<имя пользователя БД>"
    DB_PASS="<пароль пользователя БД>"
    CA_CERT="/usr/local/share/ca-certificates/Yandex/YandexInternalRootCA.crt"
    
    SCHEMA_NAME = 'schema-capnproto'
    SCHEMA_TYPE = "CapnProto"
    SCHEMA_CLASS = "User"
    
    def execute_query(query, data=None):
        url = 'https://{host}:8443/'.format(host=DB_HOST)
        params = {
            'database': DB_NAME,
            'query': query.strip()
        }
        auth = {
            'X-ClickHouse-User': DB_USER,
            'X-ClickHouse-Key': DB_PASS
        }
    
        rs = requests.post(url, 
                           params=params, 
                           headers=auth, 
                           data=data, 
                           verify=CA_CERT)
    
        rs.raise_for_status()
    
    def add_user(fileobj, user_id, user_name):
        user = User.new_message()
        user.id = user_id
        user.name = user_name
    
        fileobj.write(user.to_bytes())
    
    message = io.BytesIO()
    
    add_user(message, 11, 'John')
    add_user(message, 12, 'Bob')
    add_user(message, 13, 'Jane')
    
    execute_query(
        '''
        INSERT INTO {database}.users FORMAT {type} SETTINGS format_schema='{name}:{cls}'
        '''.format(database=DB_NAME, 
                   type=SCHEMA_TYPE, 
                   name=SCHEMA_NAME, 
                   cls=SCHEMA_CLASS), data=message.getvalue())
    

    Этот скрипт:

    1. Получает класс User из подключенного файла user.capnp (from user_capnp import User).
    2. Выполняет запросы к кластеру по HTTPS, использует SSL.
    3. Записывает тестовый набор данных в объект класса User (def add_user ...) и добавляет этот объект к битовому потоку ввода-вывода message.
    4. Вставляет данные из битового потока message в таблицу db1.users, опираясь на данные класса User схемы формата данных schema-capnproto в кластере.

    protobuf-example.py

    import requests
    import io
    import varint
    from user_pb2 import User
    
    DB_HOST="<FQDN хоста ClickHouse>"
    DB_NAME="db1"
    DB_USER="<имя пользователя БД>"
    DB_PASS="<пароль пользователя БД>"
    CA_CERT="/usr/local/share/ca-certificates/Yandex/YandexInternalRootCA.crt"
    
    SCHEMA_NAME = 'schema-protobuf'
    SCHEMA_TYPE = "Protobuf"
    SCHEMA_CLASS = "User"
    
    def execute_query(query, data=None):
        url = 'https://{host}:8443/'.format(host=DB_HOST)
        params = {
            'database': DB_NAME,
            'query': query.strip()
        }
        auth = {
            'X-ClickHouse-User': DB_USER,
            'X-ClickHouse-Key': DB_PASS
        }
    
        rs = requests.post(url,
                           params=params,
                           headers=auth, 
                           data=data,
                           verify=CA_CERT)
    
        rs.raise_for_status()
    
    def add_user(fileobj, user_id, user_name):
        user = User()
        user.id = user_id
        user.name = user_name
    
        fileobj.write(varint.encode(user.ByteSize()))
        fileobj.write(user.SerializeToString())
    
    message = io.BytesIO()
    add_user(message, 21, 'Stephen')
    add_user(message, 22, 'Olivia')
    add_user(message, 23, 'Tim')
    
    execute_query(
        '''INSERT INTO {database}.users FORMAT {type} SETTINGS format_schema='{name}:{cls}'
        '''.format(database=DB_NAME, 
                   type=SCHEMA_TYPE, 
                   name=SCHEMA_NAME, 
                   cls=SCHEMA_CLASS), data=message.getvalue())
    

    Этот скрипт:

    1. Получает класс User из подключенного файла user_pb2.py, который был получен после компиляции proto-файла (from user_pb2 import User).
    2. Записывает тестовый набор данных в объект класса User (def add_user ...) и добавляет этот объект к битовому потоку ввода-вывода message.
    3. Вставляет данные из битового потока message в таблицу db1.users, опираясь на данные класса User схемы формата данных schema-protobuf в кластере.

Вставка данных

  1. Запустите подготовленные на предыдущем этапе скрипты:

    Cap'n Proto
    Protobuf
    python3 capnproto-example.py
    
    python3 protobuf-example.py
    
  2. Подключитесь к кластеру и проверьте, что данные были успешно вставлены, выполнив запрос SELECT:

    Cap'n Proto
    Protobuf
    SELECT * FROM db1.users;
    
    ┌─id─┬─name─┐
    │ 11 │ John │
    │ 12 │ Bob  │
    │ 13 │ Jane │
    └────┴──────┘
    
    SELECT * FROM db1.users;
    
    ┌─id─┬─name────┐
    │ 21 │ Stephen │
    │ 22 │ Olivia  │
    │ 23 │ Tim     │
    └────┴─────────┘
    
В этой статье:
  • Обычная вставка данных
  • Вставка данных с указанием схемы формата данных
  • Пример работы со схемой формата при вставке данных
  • Перед началом работы
  • Установка зависимостей
  • Подготовка схем формата данных
  • Подготовка скриптов
  • Вставка данных
Language
Вакансии
Политика конфиденциальности
Условия использования
© 2021 ООО «Яндекс.Облако»