Transfer documentation #2 (#20816)

Co-authored-by: Ivan Blinkov <ivan@blinkov.ru>
Co-authored-by: Andrey Fomichev <andrey.fomichev@gmail.com>

Author: 3 people

ydb/docs/presets.yaml

@@ -23,6 +23,7 @@ default:
   feature_resource_pool_classifier: true
   feature_view: true
   feature_async_replication: true
+  feature_transfer: true
   feature_batch_operations: true
   ydb: YDB
   ydb-name: YDB

ydb/docs/ru/core/concepts/glossary.md

@@ -237,6 +237,14 @@
 
 {% endif %}
 
+{% if feature_transfer == true %}
+
+### Экземпляр трансфера {#transfer-instance}
+
+**Экземпляр трансфера** — это именованная сущность, хранящая настройки [трансфера](transfer.md), включая настройки подключения и правила преобразования данных. Также с его помощью можно получить информацию о состоянии трансфера, например [ошибки](transfer.md#error-handling).
+
+{% endif %}
+
 ### Узел координации {#coordination-node}
 
 **Узел координации** или **coordination node** — это объект схемы, который позволяет клиентским приложениям создавать семафоры для координации своих действий. Узлы координации применяются для реализации распределённых блокировок, обнаружения сервисов, выбора лидера и других сценариев. Более подробно об [узлах координации](./datamodel/coordination-node.md).

ydb/docs/ru/core/concepts/toc_i.yaml

@@ -32,6 +32,9 @@ items:
 - name: Асинхронная репликация
   href: async-replication.md
   when: feature_async_replication
+- name: Трансфер данных
+  href: transfer.md
+  when: feature_transfer
 - name: Оптимизатор запросов
   href: optimizer.md
 - name: Федеративные запросы

ydb/docs/ru/core/concepts/transfer.md

@@ -0,0 +1,74 @@
+# Трансфер данных
+
+Трансфер в {{ ydb-short-name }} — асинхронный механизм переноса данных из [топика](glossary.md#topic) в таблицу. [Создание](../yql/reference/syntax/create-transfer.md) экземпляра трансфера, его [изменение](../yql/reference/syntax/alter-transfer.md) и [удаление](../yql/reference/syntax/drop-transfer.md) осуществляет с использованием YQL. Трансфер запускается внутри базы данных, работает в фоновом режиме. Трансфер используется для решения задачи поставки данных из топика в таблицу.
+
+Часто на практике удобнее записывать данные не напрямую в таблицу, а в топик, чтобы затем в асинхронном режиме переписывать их из топика в таблицу. Такой подход позволяет равномерно распределять нагрузку и справляться со всплесками, поскольку операция записи в очередь сообщений более лёгкая. В зависимости от количества записываемых сообщений в топик, задержка доступности данных для чтения из таблицы после добавления в топик может составлять от нескольких секунд до нескольких минут.
+
+Трансфер осуществляет чтение сообщений из указанного топика, их преобразование в формат, пригодный для записи в таблицу, и последующую запись в целевую таблицу. Если в таблице уже есть строка с указанным [первичным ключом](glossary.md#primary-key), то строка будет обновлена. Преобразование данных осуществляется с помощью [lambda-функции](../yql/reference/syntax/expressions.md#lambda), которая принимает сообщение в качестве параметра и возвращает список [структур](../yql/reference/types/containers.md), каждая из которых соответствует строке, подлежащей добавлению или замене в таблице. Например, если таблица содержит колонку `example_column` типа `Int32`, структура должна включать именованное поле `example_column` того же типа.
+Если [lambda-функция](../yql/reference/syntax/expressions.md#lambda) возвращает пустой список, ни одна строка в таблице не будет изменена. Из lambda-функции не допускается обращение к таблицам и другим объектам {{ ydb-short-name }}.
+Используемую lambda-функцию можно получить из [описания](../reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера.
+
+На работу трансфера тратятся дополнительные ресурсы сервера, в первую очередь CPU. Потребление CPU зависит от сложности преобразования записываемых в топик данных.
+
+Трансфер способен читать данные из топиков, расположенных как в [базе данных](glossary.md#database), где он создаётся, так и в другой базе {{ ydb-short-name }} или [кластере](glossary.md#cluster) {{ ydb-short-name }}. Для чтения топика из другой базы данных при создании трансфера необходимо указать параметры подключения к этой базе. Целевая таблица должна находиться в той же базе данных, где создаётся трансфер.
+
+Чтение из [топика](glossary.md#topic) осуществляется с использованием [читателя](glossary.md#consumer). Трансфер автоматически добавляет в топик читателя с уникальным именем для чтения сообщений. При удалении трансфера созданный читатель удаляется автоматически. Также возможно создать читателя вручную и указать его имя при создании трансфера. Читатель, созданный вручную, не удаляется автоматически при удалении трансфера. Имя автоматически созданного читателя можно получить из [описания](../reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера.
+
+Если требуется передача данных из одного топика в несколько таблиц, для каждой таблицы необходимо создать отдельный трансфер. Аналогично, данные из нескольких топиков могут быть направлены в одну таблицу, для чего каждый топик должен быть ассоциирован с отдельным трансфером. Если имя читателя задаётся вручную, то при наличии нескольких трансферов, читающих из одного топика, необходимо назначить каждому трансферу уникального читателя, иначе данные будут обработаны только одним из них.
+
+{% note info %}
+
+При обновлении строки в таблице производится полная перезапись её значений данными из возвращаемой lambda-функцией структуры. Если структура не содержит именованного поля, соответствующего колонке таблицы, значение этой колонки будет установлено в `NULL`. Именованные поля, не имеющие соответствия в таблице, игнорируются.
+
+При попытке записать в `NOT NULL` колонку таблицы значение `NULL` трансфер остановится с [критичной ошибкой](#error-handling).
+
+{% endnote %}
+
+## Гарантии {#guarantees}
+
+* Гарантируется, что записи в таблицу будут происходить в том же порядке, в которую они были записаны в [партицию](glossary.md#partition) топика. Рекомендуется группировать сообщения, относящиеся к одной строке таблицы, в одну партицию топика.
+* Запись в таблицу осуществляется с использованием [пакетной вставки](../recipes/ydb-sdk/bulk-upsert.md) без гарантий атомарности. Запись данных разбивается на несколько независимых транзакций, каждая их которых затрагивает единственную партицию таблицы, с параллельным исполнением.
+
+## Начало работы трансфера
+
+Если трансфер создаётся без явного указания имени читателя, то в топик будет добавлен новый читатель, и обработка сообщений топика начнётся с первого сообщения в топике.
+Если трансфер создаётся с указанием созданного ранее читателя, то обработка сообщений топика начнётся с первого необработанного этим читателем сообщения.
+
+## Необходимые права для работы трансфера {#permissions}
+
+Для создания и выполнения трансфера пользователь должен обладать правами на запись в целевую таблицу и чтение из исходного топика. Если топик расположен в другой базе данных {{ ydb-short-name }}, читатель создаётся автоматически; дополнительно требуется право на модификацию топика, что позволяет трансферу автоматически создавать читателя и удалять его при удалении трансфера.
+
+## Диагностика
+
+Текущие параметры трансфера, включая текст lambda-функции, можно просмотреть в пользовательском интерфейсе [Embedded UI](../reference/embedded-ui/index.md) и в [описании](../reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера.
+
+Скорость обработки данных и задержки можно контролировать по [метрикам читателя](../reference/observability/metrics/index.md#topics), который используется для чтения из топика.
+
+## Временная остановка трансфера {#pause-and-resume}
+
+Работа трансфера может быть временно приостановлена, а затем возобновлена. После возобновления работы трансфера начнут обрабатываться сообщения, следующие за последним обработанным сообщением в топике.
+
+Для остановки трансфера следует [изменить](../yql/reference/syntax/alter-transfer.md#examples) статус трансфера на `PAUSED`, а для возобновления — на `STANDBY`.
+
+{% note warning %}
+
+Следует учесть, что в топике есть [время хранения сообщений](topic.md#retention-time), по истечении которого сообщения удаляются. Если с момента остановки трансфера пройдёт больше времени, чем время хранения сообщений, то сообщения будут удалены и не будут обработаны после возобновления работы трансфера.
+
+Чтобы гарантировать, что необработанные сообщения не будут удалены, следует сделать читателя [важным](topic.md#important-consumer).
+
+{% endnote %}
+
+## Обработка ошибок в процессе трансфера {#error-handling}
+
+В процессе трансфера возможно возникновение разных типов ошибок:
+
+* **Временные сбои**. Транспортные ошибки, перегрузка системы и другие временные проблемы. Запросы будут повторяться до успешного выполнения.
+* **Критичные ошибки**. Ошибки, связанные с правами доступа, схемой данных и другими критическими аспектами. В случае возникновения таких ошибок трансфер будет остановлен, и в пользовательском интерфейсе [Embedded UI](../reference/embedded-ui/index.md) на странице трансфера будет указан текст ошибки. Также текст ошибки можно получить из [описания](../reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера.
+
+Для возобновления работы трансфера необходимо выполнить команду `ALTER` с устранением причины ошибки. Например, если ошибка содержалась в тексте lambda-функции, то следует изменить lambda-функцию. Если ошибка не связана с конфигурацией трансфера, например, отсутствовали права на чтение из топика, то после устранения причины ошибки трансфер необходимо перезапустить сначала [временно остановив](#pause-and-resume), а потом [возобновив](#pause-and-resume) его работу.
+
+## См. также
+
+* [CREATE TRANSFER](../yql/reference/syntax/create-transfer.md)
+* [ALTER TRANSFER](../yql/reference/syntax/alter-transfer.md)
+* [DROP TRANSFER](../yql/reference/syntax/drop-transfer.md)

ydb/docs/ru/core/security/encryption/data-in-transit.md

@@ -22,4 +22,10 @@
 
 {% endif %}
 
+{% if feature_transfer == true %}
+
+* В [трансфере](../../concepts/transfer.md) между двумя базами данных {{ ydb-short-name }} одна из них выступает в роли клиента по отношению к другой.
+
+{% endif %}
+
 По умолчанию шифрование данных при передаче отключено и должно быть включено отдельно для каждого протокола. Они могут использовать общий набор TLS-сертификатов или отдельные. Инструкции по включению TLS можно найти в разделе [{#T}](../../reference/configuration/tls.md).

ydb/docs/ru/core/yql/reference/_includes/permissions_list.md

@@ -10,7 +10,7 @@
 `ydb.database.create` | `CREATE` | Право создавать новые базы данных в кластере
 `ydb.database.drop` | `DROP` | Право удалять базы данных в кластере
 Элементарные права на объекты базы данных
-`ydb.granular.select_row` | `SELECT ROW` | Право читать строки из таблицы (select), читать сообщения сообщения из топиков
+`ydb.granular.select_row` | `SELECT ROW` | Право читать строки из таблицы (select), читать сообщения из топиков
 `ydb.granular.update_row` | `UPDATE ROW` | Право обновлять строки в таблице (insert, update, upsert, replace), писать сообщения в топики
 `ydb.granular.erase_row` | `ERASE ROW` | Право удалять строки из таблицы (delete)
 `ydb.granular.create_directory` | `CREATE DIRECTORY` | Право создавать и удалять директории, в том числе существующие и вложенные

ydb/docs/ru/core/yql/reference/_includes/transfer_flush.md

@@ -0,0 +1,3 @@
+ Параметры батчевания записи в таблицу позволяют настроить баланс между задержкой появления записей в таблице и ресурсами, требуемыми для работы трансфера. Параметры батчевания влияют на обработку каждой партиции топика независимо. К изменению параметров батчевания нужно подходить с осторожностью, так как их изменение может как улучшить скорость обработки потока сообщений, так и ухудшить её, и даже привести к отказу в обслуживании, если параметры будут подобраны неверно. Например, запись в таблицу маленькими по размеру батчами может привести к перегрузке таблицы и деградации скорости работы с ней, а слишком большой размер батча — к тому, что на сервере закончится вся доступная память.
+  * `BATCH_SIZE_BYTES` — размер батча в байтах. По умолчанию — 8 МБ.
+  * `FLUSH_INTERVAL` — периодичность записи в таблицу. По умолчанию — 60 секунд. Запись в таблицу будет осуществлена, даже если батч не достиг размера, заданного в параметре `BATCH_SIZE_BYTES`.