Настройки ввода/вывода

В данном разделе перечислены опции для настройки ввода-вывода операций, а также опции команд чтения и записи таблиц.

Примечание

В данном разделе рассмотрена только важная часть опций, которая может помочь пользователю. Фактически опций гораздо больше, и они позволяют достаточно тонко настраивать различные параметры при чтении/записи данных. Чаще всего в такой настройке нет необходимости и использование значений не по умолчанию может навредить.

Управлять чтением и записью можно через форматы табличных данных, TableReader/TableWriter и ControlAttributes.

Чтение данных определяется двумя секциями настроек: table_reader и control_attributes.
За настройку записи данных отвечает секция table_writer.

Секция TableReader

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

Семплирование

В секции table_reader можно указать настройки семплирования sampling_seed и sampling_rate:

...
spec = {"job_io": {"table_reader": {"sampling_seed": 42, "sampling_rate": 0.3}}}
yt.run_map(map_function, input, output, spec=spec)
...
yt.read_table(table_path, table_reader={"sampling_seed": 42, "sampling_rate": 0.3})
...

Значение "sampling_rate": 0.3 приведет к тому, что операция — функция map_function — получит на вход 30% всех строк из входной таблицы.
Опция sampling_seed позволяет управлять генератором случайных чисел, который используется для семплирования строк. Гарантируется, что при одинаковом sampling_seed, детерминированной map_function и том же наборе входных чанков будет сгенерирован одинаковый выход. Если sampling_seed не был указан в спецификации, то он будет случайным.

При использовании семплирования все данные читаются с диска независимо от указанной вероятности.
Тем не менее, это может быть дешевле, чем самостоятельное семплирование данных, так как семплирование будет производиться на стороне системы сразу после чтения данных с диска.
Чтобы получить максимальную скорость чтения с семплированием в операции при ухудшении качества семплирования, используйте опцию sampling в спецификации операции.

Размер буфера подаваемых джобу данных

Размером буфера подаваемых джобу данных можно управлять через параметр window_size в байтах. По умолчанию значение равно 20 МБ.

Настройка буфера подаваемых джобу данных:

...
spec = {"job_io": {"table_reader": {"window_size": 20971520}}}
yt.run_map(map_function, input, output, spec=spec)
...
yt.read_table(table_path, table_reader={"window_size": 20971520})
...

Секция TableWriter

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

Ограничение на размеры строк в таблице

При записи табличных данных система YTsaurus проверяет размер. Если размер оказывается больше определенного лимита, то запись прерывается и соответствующий джоб или команда write заканчивается неудачей.

По умолчанию ограничение на размер строки — 16 МБ, однако оно может быть настроено в секции table_writer.

Изменение ограничения на размер строки в таблице:

...
spec = {"job_io": {"table_writer": {"max_row_weight": 32 * 1024 * 1024}}}
yt.run_map(map_function, input, output, spec=spec)
...
yt.write_table(table_path, table_writer={"max_row_weight": 32 * 1024 * 1024})
...

max_row_weight указывается в байтах. Не может быть больше 128 МБ.

table_writer позволяет на этапе создания таблицы в операции или при вызове merge управлять различными параметрами хранения.

Размер чанка

Настройка спецификации desired_chunk_size задаёт желаемый размер чанка в байтах.
Для преобразования таблицы, чтобы размер чанка был близок к 1 КБ, можно вызвать команду merge.

Изменение размера чанка:

yt merge --mode auto --spec '{"force_transform"=true; "job_io"={"table_writer"={"desired_chunk_size"=1024}}}' --src <> --dst <>

Данные, приходящие в джобы, не могут быть меньше размера блока. Размер блока задаётся block_size в байтах, минимальное значение 1 КБ, значение по умолчанию — 16 МБ.

Коэффициент репликации

Настройка спецификации upload_replication_factor задаёт число реплик для чанков таблицы или файла. Значение по умолчанию — 2, максимальное — 10.
Для изменения числа реплик достаточно выполнить команду merge.

Изменение коэффициента репликации:

yt merge --mode auto --spec '{"force_transform"=true; "job_io"={"table_writer"={"upload_replication_factor"=10}}}' --src <> --dst <>

Чтобы преобразование было сделано позже в фоновом режиме, выполните set на replication_factor таблицы. Аналогичное верно и для записи в таблицу с предварительно заданным параметром.

Коэффициент семплирования

Настройка спецификации sample_rate задаёт долю строк, которые будут отобраны и помещены в метаданные чанка.
Данный набор строк влияет на построение корзин для partition стадии сортировки. Увеличение числа в sample rate позволяет системе более точно находить распределение ключей, но увеличивает нагрузку на систему: увеличиться объем метаданных, время записи и чтения.
Чтобы избежать перекоса в размере корзин при объединении значений в одну партицию для колонки, в которой мало значений, увеличьте sample_rate перед фазой sort или reduce.
Значение по умолчанию 1/10 000.

Например, если в таблице 100 000 строк, то в семпле будет 10. Следовательно, партиций в сортировке будет не более 10.

Чтобы получить семпл равный 0.1% таблицы — максимальному размеру семпла — выполните команду merge.

Изменение коэффициента семплирования:

yt merge --mode auto --spec '{"force_transform"=true; "job_io"={"table_writer"={"sample_rate"=0.001}}}' --src <> --dst <>

Секция ControlAttributes

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

Рассмотрим контрольные атрибуты на примере формата YSON: в таком случае в потоке данных могут встречаться специальные записи, которые имеют тип Yson Entity, а не Yson Map, как обычные записи с данными. Они содержат в атрибутах служебную информацию.
Например, если пришла запись <table_index=2>#, это означает, что все последующие записи в потоке будут из второй входной таблицы до тех пор, пока не придет новая контрольная запись, в которой будет указан другой table_index.

Секция control_attributes поддерживает следующие опции:

В скобках указаны значения по умолчанию.

  • enable_table_index (false) — присылать контрольные записи с индексами входных таблицы (поле table_index типа int64 в атрибутах контрольной записи);
  • enable_row_index (false) — присылать контрольные записи с номером записи входной таблицы (поле row_index типа int64 в атрибутах контрольной записи);
  • enable_range_index (false) — присылать контрольные записи с номером диапазона среди заказанных диапазонов входной таблицы смотрите ranges (поле range_index типа int64 в атрибутах контрольной записи);
  • enable_key_switch (false) — присылать записи при переключении ключа входных данных (поле key_switch типа bool в атрибутах контрольной записи). Настройка имеет силу только в фазе reduce в операциях Map-Reduce и Reduce.

Примечание

Работа с контрольными атрибутами в случае Python API и C++ API скрыта от пользователя. То есть их разбором и представлением в более удобном виде занимается API.

Опции, регулирующие наличие и отсутствие табличных индексов во входном потоке, есть в разных слоях системы.
Опция enable_input_table_index находится в спецификации операции в секции, описывающей пользовательский процесс.
Значение этой опции перезаписывает значение опции enable_table_index в секции control_attributes.

Опция enable_table_index позволяет включать и выключать table index на уровне формата.
Во многих форматах индексы выключены по умолчанию, поэтому их необходимо включать. Во многих форматах есть опции, отвечающие за представление table_index в данном формате.
Подробнее про table_index в разных форматах можно прочитать в разделе Переключение таблиц.

Представление row_index, range_index и key_switchподдерживается только в форматах YSON и JSON.

Поток входных данных в reduce-джобе в формате YSON, с указанием всех контрольных атрибутов:

<"table_index"=0;>#;
<"range_index"=0;>#;
<"row_index"=2;>#;
{"a"="2";};
<"key_switch"=%true;>#;
{"a"="3";};
<"key_switch"=%true;>#;
<"row_index"=0;>#;
{"a"="1";};

Включение контрольных атрибутов в операции и при чтении:

yt read --control-attributes="{enable_row_index=true;}" "//path/to/table[#10:#20]"
{"$value": null, "$attributes": {"row_index": 10}}
...
...
spec = {"job_io": {"control_attributes": {"enable_row_index": True}}}
yt.run_map(map_function, input, output, spec=spec) # will place "@row_index" key to input records
...
yt.read_table(path, control_attributes={"enable_row_index": True}, format=yt.YsonFormat())
...