Python API на примерах

Перед запуском примеров рекомендуется прочитать инструкцию по получению токена.

Все программы рекомендуется запускать из-под Linux.

Базовый уровень

Современный способ работы с Python API — типизированный.
Данные, хранящиеся в таблицах и обрабатываемые операциями, представляются в коде классами с типизированными полями (аналог dataclasses). Нерекомендуемый (но иногда неизбежный, особенно при работе со старыми таблицами) способ — нетипизированный, когда строки таблиц представляются словарями.
Такой способ гораздо более медленный, чреват ошибками и неудобен при работе со сложными типами. Поэтому в данном разделе документации приведены примеры работы с типизированным API, а нетипизированные примеры можно найти в соответствующем разделе.

Чтение и запись таблиц

YTsaurus позволяет записывать данные в таблицы, а также дописывать данные в конец существующих таблиц. Для чтения таблиц доступны несколько режимов: чтение всей таблицы, чтение отдельных диапазонов по номеру строки или ключу.

Пример находится в yt/python/examples/table_read_write_typed.

Простой map

Предположим, имеется таблица с колонками login, name, uid по адресу //home/dev/tutorial/staff_unsorted.
Необходимо сделать таблицу с email адресами, вычислив их из логина: email = login + "@ytsaurus.tech".

Для решения задачи подойдёт простой mapper.

Пример находится в yt/python/examples/simple_map_typed

Сортировка таблицы и простая операция reduce

По той же таблице, что и в предыдущем примере, можно посчитать статистику — сколько раз встречается то или иное имя и самый длинный логин среди всех людей с одним именем. Для решения данной задачи хорошо подходит операция Reduce. Так как операцию Reduce можно запускать только на сортированных таблицах, сначала необходимо отсортировать исходную таблицу.

Пример находится в yt/python/examples/simple_reduce_typed.

Reduce с несколькими входными таблицами

Предположим, кроме таблицы с пользователями есть другая таблице, в которой записано какой пользователь является служебным. Поле is_robot принимает значения true или false.

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

Пример находится в yt/python/examples/multiple_input_reduce_typed.

Reduce с несколькими входными и несколькими выходными таблицами

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

Пример находится в yt/python/examples/multiple_input_multiple_output_reduce_typed.

Схемы таблиц

У всех таблиц в YTsaurus есть схема.
В коде продемонстрированы примеры работы со схемой таблиц.

Пример находится в yt/python/examples/table_schema_typed.

MapReduce

В YTsaurus реализована слитная операция MapReduce, которая работает быстрее, нежели Map + Sort + Reduce. Попробуем по таблице с пользователями ещё раз посчитать статистику, сколько раз встречается то или иное имя. Перед подсчётом статистики нормализируем имена, приведя их к нижнему регистру, чтобы люди с именами АРКАДИЙ и Аркадий склеились в нашей статистике.

Пример находится в yt/python/examples/map_reduce_typed.

MapReduce с несколькими промежуточными таблицами

Промежуточные данные (между стадиями map и reduce) в операции MapReduce могут "течь" в несколько потоков и иметь разные типы. В данном примере на входе операции две таблицы: первая отображает uid в имя, а вторая содержит информация о событиях, связанных с пользователем с данным uid. Mapper отбирает события типа "клик" и посылает их в один выходной поток, а всех пользователей отправляет в другой. Reducer считает все клики по данному пользователю.

Пример находится в yt/python/examples/map_reduce_multiple_intermediate_streams_typed.

Декораторы для классов-джобов

Существует возможность пометить функции или классы джобов специальными декораторами, меняющими ожидаемый интерфейс взаимодействия с джобами.
Примеры декораторов: with_context, aggregator, reduce_aggregator, raw, raw_io. Полное описание можно найти в документации

Пример находится в yt/python/examples/job_decorators_typed.

Работа с файлами на клиенте и в операциях

Более полная информация в документации.
Подробнее про файлы в Кипарисе можно прочитать в разделе.

Пример находится в yt/python/examples/files_typed.

Генеричный grep

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

Пример находится в yt/python/examples/grep_typed.

Продвинутый уровень

Batch запросы

Существует возможность исполнять "лёгкие" запросы (создать/удалить таблицу, проверить её существование и так далее) группами. Разумно пользоваться данным способом, если необходимо выполнить большое количество однотипных операций, batch запросы могут заметно сэкономить время выполнения.

Пример находится в yt/python/examples/batch_client.

Использование RPC

Использование RPC с помощью CLI.

yt list / --proxy cluster_name --config '{backend=rpc}'
cooked_logs
home
...

Аналогичный пример (полный код в yt/python/examples/simple_rpc) можно соорудить из питона (в аркадийной сборке):

Обратите внимание на дополнительный PEERDIR(yt/python/client_with_rpc) в ya.make.

C помощью RPC можно работать с динамическими таблицами.
Пример находится в yt/python/examples/dynamic_tables_rpc.

Указание типов строк с помощью prepare_operation

Помимо использования type hints, для указания Python-типов строк таблиц можно определить метод prepare_operation, где все типы указываются с использованием специальных методов. При наличии в классе джоба метода prepare_operation библиотека будет использовать типы, указанные внутри метода, и попытка вывести типы строк из type hints производиться не будет.

Пример находится в yt/python/examples/prepare_operation_typed.

Разные примеры

Датаклассы

В данном примере более подробно продемонстрированы возможности и особенности работы с датаклассами.

Пример находится в yt/python/examples/dataclass_typed.

Контекст и управление записью в выходные таблицы

Для выбора, в какую выходную таблицу записать строку, необходимо использовать класс-обёртку OutputRow, а именно аргумент table_index его конструктора. Имея любой итератор на датаклассы (который вернулся из read_table_structured() или передан в метод __call__() джоба), с помощью метода .with_context() можно сделать из него итератор на пары (row, context). Объект context имеет методы .get_table_index(), .get_row_index() и .get_range_index().

При написании класса джоба, в метод __call__() которого передаётся не итератор, а отдельная строка (например, mapper-ы), можно добавить к классу декоратор @yt.wrapper.with_context, в таком случае метод __call__() должен принимать третьим аргументом context (смотрите документацию).

В reducer, mapper-агрегаторах и при чтении таблиц — всегда, когда есть итератор на строки, используйте метод with_context итератора.

Пример находится в yt/python/examples/table_switches_typed.

Spec builders

Используйте spec builder для описания спецификации операций чтобы избегать ошибок.

Пример находится в yt/python/examples/spec_builder_typed.

Использование gevent

Документация содержится в отдельном разделе.
Пример находится в yt/python/examples/gevent.