StateAccessor в YTsaurus Flow (Python)
StateAccessor — интерфейс для чтения, модификации и удаления значений стейта.
Общие сведения о stateful-обработке описаны в разделе Stateful processing.
Принцип работы
Стейт во Flow хранится в сортированных динамических таблицах.
В случае внешнего стейта эта таблица создаётся пользователем, в случае внутреннего стейта таблицы создаются и управляются Flow автоматически.
Для TTransformCompanionComputation ключевые колонки в таблице стейта совпадают с group_by_schema компьютейшена. Для внутреннего стейта TTransformOrderedSourceCompanionComputation ключом служит ключ партиции источника: group_by_schema в таком SourceComputation не поддерживается. Во всех случаях сообщения с одинаковым ключом разделяют один стейт.
Чтение и запись данных
Непосредственную работу с таблицей (чтение, запись, удаление данных) осуществляет воркер. При получении очередного батча сообщений воркер загружает значения стейтов для всех ключей в батче и отправляет их в компаньон вместе с сообщениями и таймерами. Подробнее про схему взаимодействия.
Запись новых значений в таблицу стейта осуществляется транзакционно в рамках эпохи.
Типы аксессоров
Выберите аксессор по расположению и формату стейта:
|
Аксессор |
Формат |
Получение |
Описание |
|
YSON (dict) |
|
Сериализация Python dict в YSON |
|
|
|
|
Сырые байты без сериализации |
|
|
Protobuf |
|
Сериализация через Protobuf |
|
|
Payload (строка таблицы) |
|
Типизированный доступ к внешней таблице |
|
|
Payload (строка таблицы) |
|
Чтение через joiner в формате строк таблицы |
|
|
Protobuf |
|
Явная запись снапшотов через менеджер с поддержкой protobuf |
|
|
Protobuf |
|
Чтение снапшотов через joiner с поддержкой protobuf |
Первые три аксессора работают с внутренним стейтом (таблицами управляет Flow). Внешние аксессоры используют настроенный менеджер или joiner и таблицу, которую вы создаёте самостоятельно. Формат задаёт эта реализация; выбор Python-аксессора его не меняет. См. условия использования и доступность protobuf-стейта.
Общий API внутреннего стейта
Все внутренние аксессоры (YsonStateAccessor, RawStateAccessor, ProtoStateAccessor) предоставляют единый набор методов:
|
Метод |
Описание |
|
|
Получить значение стейта (или |
|
|
Установить значение стейта |
|
|
Удалить стейт для текущего ключа |
|
|
Получить значение или вернуть |
Внутренние аксессоры также поддерживают read_only(). Их значения живые и общие для батча. У внешних аксессоров отдельный контракт: строковый стейт читается по полям через Payload, а protobuf-стейт возвращает независимые снапшоты сообщений, для записи которых нужен явный set(). Аксессоры присоединённого внешнего стейта запрещают запись.
Получение аксессора
Аксессор получается через RuntimeContext (ctx) внутри on_message или on_timer:
class MyFunction(RowFunction):
def on_message(self, message, output, ctx):
# YSON (dict)
yson_state = ctx.state("state-name", message)
# Raw bytes
raw_state = ctx.raw_state("state-name", message)
# Protobuf
proto_state = ctx.proto_state("state-name", message, MyProtoClass)
# External (имя обязательно начинается с "/")
ext_state = ctx.external_state("/state-name", message)
def on_timer(self, timer, output, ctx):
# Аналогично, но вместо message передаётся timer
state = ctx.state("state-name", timer)
Параметры:
name— строка с именем стейта, объявленным в статической спеке. Для внутренних стейтов — строка изinternal_states; для внешних — ключ изexternal_state_managersили, для присоединённого стейта,external_state_joiners, начинающийся с/.message/timer— сообщение или таймер, для ключа которого нужно получить стейт.ProtoClass(дляproto_state,proto_external_stateиjoined_proto_external_state) — класс Protobuf-сообщения для десериализации. Для внешнего стейта имя дескриптора должно совпадать сproto_typeменеджера или joiner-а.
Когда использовать какой тип
|
Ситуация |
Рекомендуемый аксессор |
|
Простой словарь с несколькими полями |
|
|
Произвольные двоичные данные |
|
|
Структурированные данные с фиксированной схемой |
|
|
Данные, к которым нужен доступ из других систем |
|
|
Данные, требующие пользовательской таблицы |
|
|
Чтение строк таблицы без записи |
|
|
Внешний менеджер с поддержкой protobuf-стейта |
|
|
Чтение protobuf-стейта через совместимый joiner |
|
См. также
- Internal State (Python)
- External State (Python)
- Работа со стейтами (Python) — краткий обзор всех типов
- Stateful processing (концепция)
- StateAccessor (Java)