--- metadata: - name: generator content: Diplodoc Platform v5.50.4 alternate: - https://ydb.tech/docs/en/concepts/transfer.md - https://ydb.tech/docs/ru/concepts/transfer.md sourcePath: ru/core/concepts/transfer.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Трансфер данных Трансфер в YDB — асинхронный механизм переноса данных из [топика](https://ydb.tech/docs/ru/concepts/glossary.md#topic) в таблицу. [Создание](https://ydb.tech/docs/ru/yql/reference/syntax/create-transfer.md) экземпляра трансфера, его [изменение](https://ydb.tech/docs/ru/yql/reference/syntax/alter-transfer.md) и [удаление](https://ydb.tech/docs/ru/yql/reference/syntax/drop-transfer.md) осуществляется с использованием YQL. Трансфер запускается внутри базы данных, работает в фоновом режиме. Трансфер используется для решения задачи поставки данных из топика в таблицу. Часто на практике удобнее записывать данные не напрямую в таблицу, а в топик, чтобы затем в асинхронном режиме переписывать их из топика в таблицу. Такой подход позволяет равномерно распределять нагрузку и справляться со всплесками, поскольку операция записи в очередь сообщений более лёгкая. В зависимости от количества записываемых сообщений в топик, задержка доступности данных для чтения из таблицы после добавления в топик может составлять от нескольких секунд до нескольких минут. Трансфер осуществляет чтение сообщений из указанного топика, их преобразование в формат, пригодный для записи в таблицу, и последующую запись в целевую таблицу. Если в таблице уже есть строка с указанным [первичным ключом](https://ydb.tech/docs/ru/concepts/glossary.md#primary-key), то строка будет обновлена. Преобразование данных осуществляется с помощью [lambda-функции](https://ydb.tech/docs/ru/yql/reference/syntax/expressions.md#lambda), которая принимает сообщение в качестве параметра и возвращает список [структур](https://ydb.tech/docs/ru/yql/reference/types/containers.md), каждая из которых соответствует строке, подлежащей добавлению или замене в таблице. Например, если таблица содержит колонку `example_column` типа `Int32`, структура должна включать именованное поле `example_column` того же типа. Если [lambda-функция](https://ydb.tech/docs/ru/yql/reference/syntax/expressions.md#lambda) возвращает пустой список, ни одна строка в таблице не будет изменена. Из lambda-функции не допускается обращение к таблицам и другим объектам YDB. Используемую lambda-функцию можно получить из [описания](https://ydb.tech/docs/ru/reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера. На работу трансфера тратятся дополнительные ресурсы сервера, в первую очередь CPU. Потребление CPU зависит от сложности преобразования записываемых в топик данных. Трансфер способен читать данные из топиков, расположенных как в [базе данных](https://ydb.tech/docs/ru/concepts/glossary.md#database), где он создаётся, так и в другой базе YDB или [кластере](https://ydb.tech/docs/ru/concepts/glossary.md#cluster) YDB. Для чтения топика из другой базы данных при создании трансфера необходимо указать параметры подключения к этой базе. Целевая таблица должна находиться в той же базе данных, где создаётся трансфер. Чтение из [топика](https://ydb.tech/docs/ru/concepts/glossary.md#topic) осуществляется с использованием [читателя](https://ydb.tech/docs/ru/concepts/glossary.md#consumer). Трансфер автоматически добавляет в топик читателя с уникальным именем для чтения сообщений. При удалении трансфера созданный читатель удаляется автоматически. Также возможно создать читателя вручную и указать его имя при создании трансфера. Читатель, созданный вручную, не удаляется автоматически при удалении трансфера. Имя автоматически созданного читателя можно получить из [описания](https://ydb.tech/docs/ru/reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера. Если требуется передача данных из одного топика в несколько таблиц, для каждой таблицы необходимо создать отдельный трансфер. Аналогично, данные из нескольких топиков могут быть направлены в одну таблицу, для чего каждый топик должен быть ассоциирован с отдельным трансфером. Если имя читателя задаётся вручную, то при наличии нескольких трансферов, читающих из одного топика, необходимо назначить каждому трансферу уникального читателя, иначе данные будут обработаны только одним из них. {% note info %} При обновлении строки в таблице производится полная перезапись её значений данными из возвращаемой lambda-функцией структуры. Если структура не содержит именованного поля, соответствующего колонке таблицы, значение этой колонки будет установлено в `NULL`. Именованные поля, не имеющие соответствия в таблице, игнорируются. При попытке записать в `NOT NULL` колонку таблицы значение `NULL` трансфер остановится с [критичной ошибкой](#error-handling). {% endnote %} ## Гарантии {#guarantees} * Гарантируется, что записи в таблицу будут происходить в том же порядке, в которую они были записаны в [партицию](https://ydb.tech/docs/ru/concepts/glossary.md#partition) топика. Рекомендуется группировать сообщения, относящиеся к одной строке таблицы, в одну партицию топика. * Запись в таблицу осуществляется с использованием [пакетной вставки](https://ydb.tech/docs/ru/recipes/ydb-sdk/bulk-upsert.md) без гарантий атомарности. Запись данных разбивается на несколько независимых транзакций, каждая их которых затрагивает единственную партицию таблицы, с параллельным исполнением. ## Начало работы трансфера Если трансфер создаётся без явного указания имени читателя, то в топик будет добавлен новый читатель, и обработка сообщений топика начнётся с первого сообщения в топике. Если трансфер создаётся с указанием созданного ранее читателя, то обработка сообщений топика начнётся с первого необработанного этим читателем сообщения. ## Необходимые права для работы трансфера {#permissions} Для создания и выполнения трансфера пользователь должен обладать правами на запись в целевую таблицу и чтение из исходного топика. Если топик расположен в другой базе данных YDB и читатель создаётся автоматически, дополнительно требуется право на модификацию топика, что позволяет трансферу автоматически создавать читателя и удалять его при удалении трансфера. ## Диагностика Текущие параметры трансфера, включая текст lambda-функции, можно просмотреть в пользовательском интерфейсе [Embedded UI](https://ydb.tech/docs/ru/reference/embedded-ui/index.md) и в [описании](https://ydb.tech/docs/ru/reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера. Скорость обработки данных и задержки можно контролировать по [метрикам читателя](https://ydb.tech/docs/ru/reference/observability/metrics/index.md#topics), который используется для чтения из топика. ## Временная остановка трансфера {#pause-and-resume} Работа трансфера может быть временно приостановлена, а затем возобновлена. После возобновления работы трансфера начнут обрабатываться сообщения, следующие за последним обработанным сообщением в топике. Для остановки трансфера следует [изменить](https://ydb.tech/docs/ru/yql/reference/syntax/alter-transfer.md#examples) статус трансфера на `PAUSED`, а для возобновления — на `ACTIVE`. {% note warning %} Следует учесть, что в топике есть [время хранения сообщений](https://ydb.tech/docs/ru/concepts/datamodel/topic.md#retention-time), по истечении которого сообщения удаляются. Если с момента остановки трансфера пройдёт больше времени, чем время хранения сообщений, то сообщения будут удалены и не будут обработаны после возобновления работы трансфера. Чтобы гарантировать, что необработанные сообщения не будут удалены, следует сделать читателя [важным](https://ydb.tech/docs/ru/concepts/datamodel/topic.md#important-consumer). {% endnote %} ## Обработка ошибок в процессе трансфера {#error-handling} В процессе трансфера возможно возникновение разных типов ошибок: * **Временные сбои**. Транспортные ошибки, перегрузка системы и другие временные проблемы. Запросы будут повторяться до успешного выполнения. * **Критичные ошибки**. Ошибки, связанные с правами доступа, схемой данных и другими критическими аспектами. В случае возникновения таких ошибок трансфер будет остановлен, и в пользовательском интерфейсе [Embedded UI](https://ydb.tech/docs/ru/reference/embedded-ui/index.md) на странице трансфера будет указан текст ошибки. Также текст ошибки можно получить из [описания](https://ydb.tech/docs/ru/reference/ydb-cli/commands/scheme-describe.md) экземпляра трансфера. Для возобновления работы трансфера необходимо выполнить команду [`ALTER TRANSFER`](https://ydb.tech/docs/ru/yql/reference/syntax/alter-transfer.md) с устранением причины ошибки. Например, если ошибка содержалась в тексте lambda-функции, то следует изменить lambda-функцию. Если ошибка не связана с конфигурацией трансфера, например, отсутствовали права на чтение из топика, то после устранения причины ошибки трансфер необходимо перезапустить сначала [временно остановив](#pause-and-resume), а потом [возобновив](#pause-and-resume) его работу. ## См. также * [CREATE TRANSFER](https://ydb.tech/docs/ru/yql/reference/syntax/create-transfer.md) * [ALTER TRANSFER](https://ydb.tech/docs/ru/yql/reference/syntax/alter-transfer.md) * [DROP TRANSFER](https://ydb.tech/docs/ru/yql/reference/syntax/drop-transfer.md) * [Рецепты работы с трансфером данных из топика в таблицу](https://ydb.tech/docs/ru/recipes/transfer/index.md)