> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Легко подключайте источники данных Amazon Kinesis к ClickHouse Cloud.

# Интеграция Amazon Kinesis с ClickHouse Cloud

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

Kinesis ClickPipes можно развертывать и настраивать вручную через интерфейс ClickPipes, а также программно с помощью [OpenAPI](/ru/integrations/clickpipes/programmatic-access/openapi) и [Terraform](/ru/integrations/clickpipes/programmatic-access/terraform).

<div id="prerequisite">
  ## Предварительные требования
</div>

Вы уже ознакомились с [введением в ClickPipes](/ru/integrations/clickpipes/home) и настроили [учетные данные IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) или [роль IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). Сведения о том, как настроить роль для работы с ClickHouse Cloud, см. в [руководстве по ролевому доступу Kinesis](/ru/integrations/clickpipes/kinesis/auth).

<div id="creating-your-first-clickpipe">
  ## Создание первого ClickPipe
</div>

1. Откройте консоль SQL для своего сервиса ClickHouse Cloud.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_service.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=baa2a1fbd12dce262df262176b152c5f" alt="Сервис ClickPipes" size="lg" border width="1184" height="482" data-path="images/integrations/data-ingestion/clickpipes/cp_service.webp" />

2. В левом меню нажмите кнопку `Data Sources`, затем — "Set up a ClickPipe"

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step0.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=5c127cc5de6fe7160371dce223f06b60" alt="Выбор импорта" size="lg" border width="2606" height="790" data-path="images/integrations/data-ingestion/clickpipes/cp_step0.webp" />

3. Выберите источник данных.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step1.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=277dd43baebb113db688a516f2d05f86" alt="Выбор типа источника данных" size="lg" border width="2600" height="1890" data-path="images/integrations/data-ingestion/clickpipes/cp_step1.webp" />

4. Заполните форму: укажите имя ClickPipe, описание (необязательно), роль IAM или учетные данные, а также другие сведения о подключении.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step2_kinesis.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=0f9bac03cfe158fd3e23b177bfa28e3d" alt="Заполнение сведений о подключении" size="lg" border width="2266" height="1226" data-path="images/integrations/data-ingestion/clickpipes/cp_step2_kinesis.webp" />

5. Выберите Kinesis Stream и начальное смещение. Интерфейс покажет пример документа из выбранного источника (топик Kafka и т. д.). Вы также можете включить Enhanced Fan-out для потоков Kinesis, чтобы повысить производительность и стабильность ClickPipe (подробнее об Enhanced Fan-out можно узнать [здесь](https://aws.amazon.com/blogs/aws/kds-enhanced-fanout))

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step3_kinesis.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=b7fdb5c534b2d94469ba937f9e50bff9" alt="Настройка формата данных и топика" size="lg" border width="2274" height="1540" data-path="images/integrations/data-ingestion/clickpipes/cp_step3_kinesis.webp" />

6. На следующем шаге вы можете выбрать, выполнять ли приём данных в новую таблицу ClickHouse или использовать существующую. Следуйте инструкциям на экране, чтобы изменить имя таблицы, схему и настройки. Вверху страницы отображается предварительный просмотр изменений в реальном времени на примере таблицы.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step4a.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=b9f12f6c0d73035e1aada3ba43ebbad2" alt="Настройка таблицы, схемы и параметров" size="lg" border width="2734" height="1328" data-path="images/integrations/data-ingestion/clickpipes/cp_step4a.webp" />

Вы также можете настроить дополнительные параметры с помощью доступных элементов управления

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step4a3.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=082d0fc28d1d2f8af315e1cfa3d1e0d2" alt="Настройка дополнительных элементов управления" size="lg" border width="1592" height="338" data-path="images/integrations/data-ingestion/clickpipes/cp_step4a3.webp" />

7. Кроме того, можно выбрать приём данных в существующую таблицу ClickHouse. В этом случае интерфейс позволит сопоставить поля источника с полями ClickHouse в выбранной целевой таблице.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step4b.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=5a68f31fdac86791722db4a0faa0f298" alt="Использование существующей таблицы" size="lg" border width="2738" height="1322" data-path="images/integrations/data-ingestion/clickpipes/cp_step4b.webp" />

8. Наконец, вы можете настроить разрешения для внутреннего пользователя ClickPipes.

**Разрешения:** ClickPipes создаст отдельного пользователя для записи данных в целевую таблицу. Для этого внутреннего пользователя можно выбрать пользовательскую роль или одну из предопределенных ролей:

* `Full access`: полный доступ к кластеру. Это может быть полезно, если вы используете materialized view или словарь с целевой таблицей.
  * `Only destination table`: только разрешения `INSERT` для целевой таблицы.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_step5.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=3a3657fe0c594a1217d71290f27d096a" alt="Разрешения" border width="2736" height="1318" data-path="images/integrations/data-ingestion/clickpipes/cp_step5.webp" />

9. Нажмите "Complete Setup", чтобы система зарегистрировала ClickPipe, после чего он появится в сводной таблице.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_success.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=81d5e86ce8d7315d5463f45d54e4f53c" alt="Уведомление об успешной настройке" size="sm" border width="613" height="212" data-path="images/integrations/data-ingestion/clickpipes/cp_success.webp" />

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_remove.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=c4cc25a78f1bdb4212d42cf8659bd02d" alt="Уведомление об удалении" size="lg" border width="2756" height="1320" data-path="images/integrations/data-ingestion/clickpipes/cp_remove.webp" />

Сводная таблица содержит элементы управления для просмотра примеров данных из источника или из целевой таблицы в ClickHouse

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_destination.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=186557ea6d5b5189f972399519a60165" alt="Просмотр пункта назначения" size="lg" border width="2758" height="1316" data-path="images/integrations/data-ingestion/clickpipes/cp_destination.webp" />

А также элементы управления для удаления ClickPipe и просмотра сводки по задаче приёма.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/Qdrmbc1T54ihl0_n/images/integrations/data-ingestion/clickpipes/cp_overview.webp?fit=max&auto=format&n=Qdrmbc1T54ihl0_n&q=85&s=1dfc009ce729fb48f46e3e7cd6c83581" alt="Просмотр обзора" size="lg" border width="3436" height="1076" data-path="images/integrations/data-ingestion/clickpipes/cp_overview.webp" />

10. **Поздравляем!** Вы успешно настроили свой первый ClickPipe. Если это стриминговый ClickPipe, он будет работать непрерывно и выполнять приём данных в реальном времени из удаленного источника. В противном случае он выполнит приём батча и завершит работу.

<div id="supported-data-formats">
  ## Поддерживаемые форматы данных
</div>

Поддерживаются следующие форматы:

* [JSON](/ru/reference/formats/JSON/JSON)

<div id="compression">
  ## Сжатие
</div>

ClickPipes для Kinesis автоматически определяет и распаковывает сжатые записи. В отличие от Kafka, где декомпрессия прозрачно выполняется клиентской библиотекой, Kinesis передаёт сырые байты — ClickPipes берёт это на себя без дополнительной настройки.

Поддерживаются следующие кодеки сжатия:

* **gzip**
* **zstd**
* **lz4**
* **snappy** (фреймированный формат)

Сжатие автоматически определяется по сигнатурам magic bytes в каждой записи. Если известная сигнатура сжатия не найдена, запись считается несжатой. Обнаруженный тип сжатия также определяется при автоопределении схемы, поэтому в предпросмотре данных в интерфейсе корректно отображаются распакованные данные.

<Note>
  Автоопределение безопасно для текстовых форматов, таких как JSON и CSV, поскольку печатные символы ASCII не могут совпасть с сигнатурами magic bytes сжатия.
</Note>

<div id="supported-data-types">
  ## Поддерживаемые типы данных
</div>

<div id="standard-types-support">
  ### Поддержка стандартных типов
</div>

В настоящее время ClickPipes поддерживает следующие типы данных ClickHouse:

* Базовые числовые типы — \[U]Int8/16/32/64, Float32/64 и BFloat16
* Целочисленные типы большой разрядности — \[U]Int128/256
* Типы Decimal
* Boolean
* String
* FixedString
* Date, Date32
* DateTime, DateTime64 (только часовой пояс UTC)
* Enum8/Enum16
* UUID
* IPv4
* IPv6
* все типы ClickHouse LowCardinality
* Map с ключами и значениями, использующими любой из перечисленных выше типов (включая Nullable)
* Tuple и Array с элементами, использующими любой из перечисленных выше типов (включая Nullable; только один уровень вложенности)
* типы SimpleAggregateFunction (для пунктов назначения AggregatingMergeTree или SummingMergeTree)

<div id="variant-type-support">
  ### Поддержка типа варианта
</div>

Вы можете вручную указать тип варианта (например, `Variant(String, Int64, DateTime)`) для любого JSON-поля
в потоке исходных данных. Поскольку ClickPipes определяет, какой подтип варианта следует использовать, особым образом, в определении Variant можно использовать только один целочисленный тип или один тип datetime —
например, `Variant(Int64, UInt32)` не поддерживается.

<div id="json-type-support">
  ### Поддержка типа JSON
</div>

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

<div id="kinesis-virtual-columns">
  ## Виртуальные столбцы Kinesis
</div>

Для потока Kinesis поддерживаются следующие виртуальные столбцы. При создании новой целевой таблицы их можно добавить с помощью кнопки `Add Column`.

| Name               | Description                                                                  | Recommended Data Type |
| ------------------ | ---------------------------------------------------------------------------- | --------------------- |
| \_key              | Ключ партиционирования Kinesis                                               | String                |
| \_timestamp        | Примерная временная метка поступления в Kinesis (с точностью до миллисекунд) | DateTime64(3)         |
| \_stream           | Имя потока Kinesis                                                           | String                |
| \_sequence\_number | Номер последовательности Kinesis                                             | String                |
| \_raw\_message     | Полное сообщение Kinesis                                                     | String                |

Поле \_raw\_message можно использовать в случаях, когда нужна только полная JSON-запись Kinesis (например, при использовании функций ClickHouse [`JsonExtract*`](/ru/reference/functions/regular-functions/json-functions#jsonextract-functions) для заполнения материализованного
представления ниже по конвейеру). Для таких пайпов удаление всех «не виртуальных» столбцов может повысить производительность ClickPipes.

<div id="limitations">
  ## Ограничения
</div>

* [DEFAULT](/ru/reference/statements/create/table#default) не поддерживается.
* По умолчанию размер отдельных сообщений ограничен 16 МБ (без сжатия) для реплик минимального размера (XS) и 32 МБ (без сжатия) для более крупных реплик.  Сообщения, превышающие этот лимит, будут отклонены с ошибкой.  Если вам требуются сообщения большего размера, пожалуйста, обратитесь в службу поддержки.

<div id="performance">
  ## Производительность
</div>

<div id="batching">
  ### Батчинг
</div>

ClickPipes выполняет вставку данных в ClickHouse батчами. Это позволяет избежать создания слишком большого количества частей в базе данных, что может привести к проблемам с производительностью в кластере.

Батчи вставляются при выполнении одного из следующих условий:

* Размер батча достиг максимального значения (100 000 строк или 32 МБ на 1 ГБ памяти реплики)
* Батч оставался открытым в течение максимально допустимого времени (5 секунд)

<div id="latency">
  ### Задержка
</div>

Задержка (то есть время между отправкой сообщения Kinesis в поток и моментом, когда это сообщение становится доступным в ClickHouse) зависит от ряда факторов (например, задержки в Kinesis, сетевой задержки, размера/формата сообщения). Описанный в предыдущем разделе [батчинг](#batching) также влияет на задержку. Мы всегда рекомендуем протестировать ваш конкретный сценарий использования, чтобы понять, на какую задержку можно рассчитывать.

Если у вас есть особые требования к низкой задержке, [свяжитесь с нами](https://clickhouse.com/company/contact?loc=clickpipes).

<div id="active-shards">
  ### Активные сегменты
</div>

Мы настоятельно рекомендуем ограничивать число одновременно активных сегментов в соответствии с требованиями к пропускной способности. Для потока Kinesis типа "On Demand" AWS автоматически назначает соответствующее количество сегментов на основе пропускной способности,
но для потоков "Provisioned" выделение слишком большого количества сегментов может вызывать задержки, как описано ниже, а также увеличивать затраты, поскольку для таких потоков тарификация Kinesis рассчитывается "за сегмент".

Если приложение-производитель непрерывно записывает данные в большое число активных сегментов, это может вызывать задержки, если ваш пайп масштабирован недостаточно для их эффективной обработки. С учётом ограничений Kinesis по пропускной способности
ClickPipes назначает определённое количество "воркеров" на реплику для чтения данных из сегментов. Например, в минимальной конфигурации реплика ClickPipes имеет 4 таких воркера. Если производитель записывает
одновременно более чем в 4 сегмента, данные из "лишних" сегментов не будут обрабатываться, пока не освободится воркер. В частности, если пайп использует "enhanced fanout", каждый воркер будет подписан на
один сегмент в течение 5 минут и в это время не сможет читать данные из других сегментов. Это может вызывать "всплески" задержки с интервалом в 5 минут.

<div id="scaling">
  ### Масштабирование
</div>

ClickPipes для Kinesis спроектирован так, чтобы масштабироваться как по горизонтали, так и по вертикали. По умолчанию создается группа потребителей с одним потребителем. Это можно настроить при создании ClickPipe или позже в разделе **Настройки** -> **Дополнительные настройки** -> **Масштабирование**.

ClickPipes обеспечивает высокую доступность за счет архитектуры с распределением по зонам доступности.
Для этого требуется масштабирование как минимум до двух потребителей.

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

<div id="authentication">
  ## Аутентификация
</div>

Для доступа к потокам Amazon Kinesis можно использовать [учетные данные IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) или [роль IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). Подробнее о настройке роли IAM см. [в этом руководстве](/ru/integrations/clickpipes/kinesis/auth), где описано, как настроить роль для работы с ClickHouse Cloud