YT-прагмы

YT‑прагмы — это пространство имён для прагм, которые настраивают специфичные для YTsaurus параметры YQL‑запросов.

Синтаксис

Названия YT‑прагм содержат префикс yt:

PRAGMA yt.<pragma_name> = '<value>';

Область действия и особенности

По области действия YT‑прагмы можно разделить на статические и динамические.

Статические прагмы:

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

Динамические прагмы:

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

Поддержка per-cluster

Некоторые прагмы поддерживают специальный режим работы — per-cluster. Этот режим позволяет в одном запросе задать разные значения прагм для разных кластеров. Например, можно указать: «На кластере А выполнить запрос с настройками X, а на кластере В — с настройками Y». Это полезно в распределённых запросах, где разные кластеры требуют разных условий выполнения.

Режим per-cluster доступен для всех динамических прагм и для некоторых статических — в документации ниже такие прагмы помечены явно маркером «per-cluster».

Как использовать

По умолчанию YT-прагмы пишутся с префиксом yt — это означает, что настройка применится к текущему кластеру, на котором выполняется запрос. Чтобы та же прагма применилась к другому кластеру с другим значением, замените yt на имя этого кластера. Например, зададим в запросе разные временные директории для двух кластеров:

PRAGMA yt.TmpFolder = "//tmp/my_folder";            -- текущий кластер
PRAGMA cluster_2.TmpFolder = "//tmp/other_folder";  -- кластер cluster_2

... -- тело запроса

В результате при выполнении запроса временные файлы будут сохраняться в //tmp/my_folder на текущем кластере и в //tmp/other_folder на кластере cluster_2.

yt.Annotations

Позволяет задать произвольную структурированную информацию, связанную с операцией. Это пригодится для поиска и идентификации операций в архиве (поиск в нём доступен через API). Подробнее читайте в разделе Настройки операций.

Сигнатура

PRAGMA yt.Annotations = '{
    "name" = "login";
    "time" = "20.02.2002";
}';

Результат

При поиске операции в архиве будет видна информация, заданная в словаре.

yt.Auth

Использовать аутентификационные данные, отличные от дефолтных.

yt.AutoMerge / yt.TemporaryAutoMerge / yt.PublishedAutoMerge

Управление одноименной настройкой YTsaurus, помогающей уменьшить потребление квоты на число chunk'ов. yt.TemporaryAutoMerge действует для всех YT-операций, за исключением merge внутри YtPublish узла.

yt.PublishedAutoMerge действует только для merge внутри YtPublish узла (если он там запускается). yt.AutoMerge задаёт значение этой настройки одновременно для всех YTsaurus операций запроса.

yt.BatchListFolderConcurrency

Задаёт количество одновременных операций листинга директорий.

yt.BinaryExpirationInterval

Позволяет управлять TTL кешируемых бинарных артефактов. Работает только в паре с yt.BinaryTmpFolder. Каждое использование бинарного артефакта в запросе продлевает его TTL.

yt.BinaryTmpFolder

Задаёт отдельный путь на кластере, где будут кешироваться бинарные артефакты запроса (UDF и job binary). Артефакты сохраняются в корне директории с именем, равным md5 артефакта. Сохранение и использование артефактов в данной директории выполняется вне транзакции, даже если в запросе задана прагма yt.ExternalTx

yt.BufferRowCount

Ограничение на количество записей, которые могут быть забуферизированы JobProxy.

yt.ColumnGroupMode

Задаёт режим вычисления поколоночных групп для промежуточных таблиц запроса. В режиме disable поколоночные группы не используются. В режиме single создается одна группа на все колонки таблицы. В режиме perusage создаются гранулярные группы колонок по их потребителям. Все колонки одной группы одновременно используются в одном или нескольких потребителях. Например, если в промежуточной таблице имеются колонки [a, b, c, d, e, f] и её используют две операции с выборками колонок [a, b, c, d] и [c, d, e, f] соответственно, то в таблице будут созданы три группы колонок [a, b], [c, d] и [e, f]. Если промежуточная таблица используется для публикации в выходную таблицу (т.е. потребителем является узел YtPublish), то поколоночные группы не применяются, за исключением явно заданного модификатора column_groups. В последнем случае, промежуточная таблица использует поколоночные группы модификатора.

yt.CombineCoreLimit

Задаёт размер буфера памяти для выполнения CombineCore узла.

yt.CommonJoinCoreLimit

Задаёт размер буфера памяти для выполнения CommonJoinCore узла (исполняется в джобе при выборе common-стратегии JOIN).

yt.CoreDumpPath

Позволяет сохранить coredump от упавших джобов MapReduce операций в отдельную таблицу.

yt.DataSizePerJob / yt.DataSizePerMapJob

Управление нарезкой MapReduce-операций на джобы, чем больше число, тем меньше джобов. Для вычислительно затратных джобов значение рекомендуется уменьшать, а для бегло просматривающих много данных (в частности, user_sessions) — увеличивать.

Допустимы суффиксы K, M и G для указания в килобайтах, мегабайтах и гигабайтах, соответственно.

yt.DataSizePerPartition

Управление размером партиций в MapReduce операциях.

Допустимы суффиксы K, M и G для указания в килобайтах, мегабайтах и гигабайтах, соответственно.

yt.DataSizePerSortJob

Управление нарезкой sort-джобов в MapReduce-операциях.

Допустимы суффиксы K, M и G для указания в килобайтах, мегабайтах и гигабайтах, соответственно.

yt.DefaultCalcMemoryLimit

Ограничение потребляемой памяти для вычислений, не связанных с доступом к таблицам.

Допустимы суффиксы K, M и G для указания в килобайтах, мегабайтах и гигабайтах, соответственно.

yt.DefaultLocalityTimeout

Задаёт настройку locality_timeout в спеке операции (настройка пока не задокументирована).

yt.DefaultMapSelectivityFactor

Задаёт приблизительное соотношение выхода к входу map-стадии в совмещенной MapReduce операции, см. документацию

yt.DefaultMaxJobFails

Количество упавших MapReduce-джобов, при достижении которого повторные попытки выполнения запроса прекращаются и запрос признается не успешным.

yt.DefaultMemoryDigestLowerBound

Задаёт настройку user_job_memory_digest_lower_bound в спеке операции. Про настройку можно почитать в документации.

yt.DefaultMemoryLimit

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

Допустимы суффиксы K, M и G для указания в килобайтах, мегабайтах и гигабайтах, соответственно.

yt.DefaultMemoryReserveFactor

Задаёт коэффициент резервирования памяти для джобов, см. документацию.

yt.DefaultOperationWeight

Вес всех запускаемых MapReduce-операций в рамках выбранного вычислительного pool.

yt.Description

Задаёт информацию, которая отображается в веб-интерфейсе на странице операции. См. документацию.

yt.DisableJobSplitting

Запретить планировщику YTsaurus адаптивно дополнительно разбивать долго бегущие пользовательские джобы.

yt.DisableOptimizers

Отключает заданные оптимизаторы.

yt.DockerImage

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

yt.DontForceTransformForInputTables

Отключает принудительную трансформацию данных для пользовательских таблиц с настройками хранения (erasure_codec, compression_codec, primary_medium, media, поколоночные группы), отличающимися от настроек по умолчанию.

Принудительная трансформация применяется для входных таблиц, если они используются для записи в выходные таблицы только через операцию YtMerge.

yt.ErasureCodecCpu

Множитель для оценки потребления процессора для обработки таблиц, пожатых erasure кодеком. Влияет на разбиение MapReduce-операций на джобы.

yt.EvaluationTableSizeLimit

Задаёт максимальный суммарный объём таблиц, используемых на evaluation-стадии.

yt.ExpirationDeadline / yt.ExpirationInterval

Позволяет управлять TTL создаваемых операцией таблиц.

yt.ExternalTx

Используется для указания внешней транзакции, в контексте которой будет выполняться запрос (например, если транзакция была создана через CLI). Это может понадобиться, чтобы выполнить несколько действий атомарно — например, 2 YQL-запроса или YQL-запрос и изменение таблиц.

Также прагма позволяет прочитать промежуточные данные в транзакциях (например, в длительной операции, где есть временные файлы).

Пример

PRAGMA yt.ExternalTx = 'a3d149bd-674dfa1-fa68f314-2c22562';   -- ID транзакции (можно посмотреть через CLI)

Результат

Запрос будет выполнен в рамках указанной транзакции.

Особенности и ограничения

Указание прагмы без тела запроса вызовет ошибку.

yt.ExtraTmpfsSize

Возможность увеличить размер tmpfs в дополнение к суммарному размеру всех явно используемых файлов (указывается в мегабайтах). Может быть полезно, если вы из UDF создаете новые файлы локально. Без UseTmpfs игнорируется.

yt.FileCacheTtl

Позволяет управлять TTL файлового кеша YTsaurus. Значение 0 отключает использование TTL для файлового кеша.

yt.FolderInlineDataLimit

Задаёт максимальный размер данных для inline списка, полученного в результате вычисления Folder. При большем размере будет использоваться временный файл.

yt.FolderInlineItemsLimit

Задаёт максимальное количество элементов в inline списке, полученном в результате вычисления Folder. При большем размере будет использоваться временный файл.

yt.ForceJobSizeAdjuster

Задаёт опцию "force_job_size_adjuster" в настройках операций.

yt.HybridDqExecution

Включает гибридное исполнение запросов через DQ

yt.IgnoreTypeV3

При чтении таблиц со схемой type_v3 все поля со сложными типами будут видны в запросе как Yson поля. К сложным типам относятся все не-data типы и data-типы с опциональностью больше одного уровня.

yt.IgnoreWeakSchema

Игнорировать weak схему таблицы (порожденную сортировкой несхематизированной таблицы по некоторому набору полей).

Совместно с yt.InferSchema позволяет выводить схему по данным для таких таблиц.

yt.IgnoreYamrDsv

Игнорировать _format=yamred_dsv, если он указан в метаданных входной таблицы.

yt.InferSchema / yt.ForceInferSchema

Вывод схемы данных по содержимому первых строк таблиц. Если PRAGMA указана без значения, то подразумевается, что по одной первой строке. Если указано несколько строк и типы данных для колонки встречаются разные, то они расширяются вплоть до Yson.

InferSchema включает вывод схемы данных только для тех таблиц, где она совсем не указана в метаданных. При ForceInferSchema схема данных из метаданных игнорируется, за исключением списка ключевых колонок для сортированных таблиц.

В дополнение к обнаруженным колонкам генерируется колонка-словарь _other (строка на строку) со значениями тех колонок, которые не присутствовали на первой строке, но нашлись где-то дальше. Это позволяет использовать на таких таблицах WeakField.

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

yt.InferSchemaTableCountThreshold

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

yt.IntermediateAccount

Позволяет использовать свой account для промежуточных данных внутри операции слитного MapReduce.

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

Если указана PRAGMA yt.TmpFolder, то по умолчанию вместо общего берется account, который указан на временной директории.

yt.IntermediateDataMedium

Установить медиум, используемый для промежуточных данных в операциях (Sort, MapReduce). Подробности см. в документации.

yt.IntermediateReplicationFactor

Фактор репликации промежуточных данных.

yt.JobEnv

Задаёт переменные окружения для map- и reduce-джобов операций. Ключи в словаре задают имена переменных окружения, а значения в словаре — значения переменных окружения.

yt.JoinAllowColumnRenames

Включает использование переименования колонок при выполнении стратегии Ordered JOIN (используется атрибут rename_columns). Если опция выключена, то стратегия Ordered JOIN будет выбрана только при совпадении имён колонок слева и справа.

yt.JoinCollectColumnarStatistics

Управляет использованием поколоночных статистик для точной оценки входов JOIN-ов и выбора соответствующей стратегии. Async включает режим асинхронного сбора поколоночной статистики.

yt.JoinColumnarStatisticsFetcherMode

Управляет режимом запроса поколоночных статистик для точной оценки входов JOIN-ов от YTsaurus. Режим from_nodes обеспечивает точную оценку, но может не укладываться в таймауты для больших таблиц. Режим from_master работает очень быстро, но дает огрубленную статистику. Режим fallback работает как комбинация предыдущих двух.

yt.JoinMergeForce

Форсирует выбор Ordered JOIN стратегии. Если флаг установлен в True, то Ordered JOIN стратегия выбирается, даже если одна или обе стороны JOIN не сортированы. При этом несортированные стороны предварительно сортируются. Ограничения на максимальный размер несортированной таблицы (см. yt.JoinMergeUnsortedFactor) при этом игнорируются.

yt.JoinMergeReduceJobMaxSize

Максимально допустимый размер Reduce джобы при выборе маленькой таблицы в качестве primary при Ordered JOIN стратегии. Если получившийся размер превышает указанное значение, то операция Reduce повторяется с большей таблицей в качестве primary.

yt.JoinMergeTablesLimit

Суммарное допустимое число таблиц слева и справа для включения Ordered стратегии JOIN.

Указав в значении 0 можно совсем отключить данную стратегию.

yt.JoinMergeUnsortedFactor

Минимальное соотношение размера несортированной стороны JOIN к сортированной для её дополнительной сортировки и выбора Ordered стратегии JOIN.

yt.JoinMergeUseSmallAsPrimary

Явное управление выбором primary таблицы в операции Reduce при Ordered JOIN стратегии. Если установлен в true, то в качестве primary таблички всегда будет выбираться меньшая сторона. Если значение флага равно false, то будет выбираться большая сторона за исключением случая уникальных ключей на большей стороне. Выбор большей таблицы в качестве primary безопасен даже при наличии в ней ключей-монстров, но работает медленнее. Если данная прагма не установлена, то выбор primary происходит автоматически исходя из максимального размера получающихся джобов (см. yt.JoinMergeReduceJobMaxSize).

yt.LayerPaths

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

yt.LLVMMemSize

Задаёт фиксированный размер памяти, необходимый при компиляции LLVM-кода в джобах

yt.LLVMPerNodeMemSize

Задаёт размер памяти на каждый узел графа вычислений, необходимый при компиляции LLVM-кода в джобах

yt.LookupJoinLimit

Таблица может быть использована в качестве словаря в Lookup JOIN стратегии, если её размер не превышает минимума из yt.LookupJoinLimit и yt.EvaluationTableSizeLimit.

yt.LookupJoinMaxRows

Максимальное число строк в таблице, при котором она может выступать в качестве словаря в Lookup JOIN стратегии.

yt.MapJoinLimit

Ограничение на размер меньшей таблицы в JOIN, при котором включается Map-side стратегия (создание словаря в памяти из меньшей таблицы и использование его в Map по большей).

Указав в значении 0 можно совсем отключить данную стратегию.

yt.MapJoinShardCount

Map-side стратегия JOIN может выполняться в шардированном варианте: меньшая сторона разбивается на N шардов (где N — меньше или равно значению данной PRAGMA), каждый из которых независимо и параллельно объединяется с большей стороной, а затем результатом JOIN считается конкатенация JOIN с шардами.

yt.MapJoinShardMinRows

Минимально количество записей на шард в map-side стратегии JOIN.

yt.MapLocalityTimeout

Задаёт настройку map_locality_timeout в спецификации операции (настройка пока не задокументирована).

yt.MaxColumnGroups

Задаёт максимальное число поколоночных групп на промежуточную таблицу запроса. Если вычисленное число групп превышает этот лимит, то группы не создаются для данной таблицы.

yt.MaxExtraJobMemoryToFuseOperations

Максимальный размер потребления памяти джобами, допускаемый после слияния операций оптимизаторами.

yt.MaxInputTables

Ограничение на число таблиц, подаваемых на вход каждой конкретной MapReduce операции.

yt.MaxInputTablesForSortedMerge

Ограничение на число таблиц, подаваемых на вход sorted merge операции.

yt.MaxJobCount

Максимальное количество джобов в рамках одной YTsaurus операции. Применяется только для одностадийных операций map, reduce, merge и т. д. При одновременном указании yt.DataSizePerJob и yt.MaxJobCount нарезка джобов будет выполняться с учетом yt.DataSizePerJob, и даже если полученное значение N превысит yt.MaxJobCount, то будет запущено N джобов, а yt.MaxJobCount повлияет только на то, будут ли сплититься джобы, после того как их количество достигнет некоторого порога.

yt.MaxKeyWeight

Увеличить ограничение на максимальную длину ключей таблицы в YTsaurus, по которым она отсортирована.

yt.MaxOutputTables

Ограничение на число выходных таблиц каждой конкретной MapReduce операции.

yt.MaxReplicationFactorToFuseOperations

Максимальный коэффициент размножения данных, допускаемый после слияния операций оптимизаторами.

yt.MaxRowWeight

Увеличить ограничение на максимальную длину строки таблицы в yt.

yt.MaxSpeculativeJobCountPerTask

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

yt.MinColumnGroupSize

Задаёт минимальный размер поколоночной группы. Если вычисленная группа содержит число колонок меньше заданного значения прагмы, то она не создается.

yt.MinLocalityInputDataWeight

Задаёт настройку min_locality_input_data_weight в спецификации операции (настройка пока не задокументирована).

yt.MinPublishedAvgChunkSize

Если средний размер чанка в получившейся выходной таблице оказался меньше, чем указанная настройка, то запускается дополнительная YTsaurus Merge операция, которая укрупняет чанки до указанного размера. Значение 0 имеет специальный смысл — в этом случае merge всегда запускается и укрупняет чанки до 1G.

Если для таблицы используется compression codec, то размер чанков на выходе может отличаться от заданного на коэффициент компрессии. По сути, данная прагма задаёт размер данных на один merge job. После компрессии выходной размер может быть значительно меньше. В этом случае стоит увеличить значение прагмы на ожидаемый коэффициент компрессии.

yt.MinTempAvgChunkSize

Настройка аналогична yt.MinPublishedAvgChunkSize, но работает для промежуточных временных таблиц.

yt.NetworkProject

Задаёт использование указанного сетевого проекта в джобах для регулярных операций в запросе.

yt.NightlyCompress

Управляет процессом фонового сжатия таблиц, чтобы они занимали меньше места.

Значение true устанавливает на таблице атрибут @force_nightly_compress равным true.
Значение false устанавливает на таблице атрибут @nightly_compression_settings с дочерним значением enabled равным false.

Настройка действует только на вновь создаваемые YQL запросом таблицы (а также на перезаписываемые с помощью INSERT INTO ... WITH TRUNCATE).
Настройка не действует на временные таблицы.

yt.OmitInaccessibleRows

Управляет поведением при чтении таблиц с построчным ACL (RLS).

По умолчанию чтение таблицы с установленным построчным ACL завершается ошибкой авторизации, если у пользователя нет права full_read. Прагма yt.OmitInaccessibleRows изменяет это поведение: при включении строки без доступа пропускаются, а запрос завершается успешно. В результат попадают только строки, разрешённые предикатом RLS.

Пример

PRAGMA yt.OmitInaccessibleRows = "true";

SELECT *
FROM `//path/to/table_with_rls`;

Результат

Запрос вернёт только строки, доступные текущему пользователю согласно построчному ACL. Строки, к которым нет доступа, будут пропущены без ошибки.

Ограничения

• Нельзя указывать row_index в ranges при чтении таблицы с построчным ACL — запрос завершится ошибкой. Индексы строк в ranges отсчитываются относительно физических строк на диске, а не строк, доступных пользователю. Например, //path/to/table[:#100] вернёт до 100 строк с диска, часть из которых может быть недоступна и будет отфильтрована.
• RLS не поддерживается для динамических таблиц — любое чтение вернёт ошибку.

yt.OperationReaders

Позволяет выдавать права на чтение создаваемых MapReduce операций в YTsaurus другим пользователям помимо владельца YQL операции.

yt.OperationSpec

Задаёт словарь настроек операций. Позволяет задать, настройки, не имеющие аналогов в виде прагм. Настройки, заданные через специализированные прагмы, имеют больший приоритет и перетирают значения в этом словаре.

yt.OptimizeFor

Управление атрибутом optimize_for на создаваемых таблицах.

yt.Owners

Позволяет выдавать доступ к управлению MapReduce-операциями в YTsaurus (отмена, пауза, run-job-shell и т. п.) другим пользователям — помимо пользователя, запустившего запрос.

Пример

PRAGMA yt.Owners = 'ivanov petrov';    -- логины пользователей через пробел

Результат

Указанные пользователи смогут управлять MapReduce-операциями.

yt.ParallelOperationsLimit

Задаёт максимальное число одновременно запускаемых YTsaurus-операций в пределах запроса.

yt.Pool

Используется для переопределения вычислительного пула, который по умолчанию является логином текущего пользователя или был задан прагмой yt.StaticPool.

Сигнатура

PRAGMA yt.StaticPool = '<pool_1>';
PRAGMA yt.Pool = '<pool_2>';

Результат

После указания прагмы yt.StaticPool запрос выполнится в пуле <pool_1>, а после прагмы yt.Pool — в <pool_2>.

yt.PoolTrees

Возможность выбирать отличные от стандартного «деревья pool'ов».

yt.PrimaryMedium

Задаёт первичный медиум в YTsaurus для Published, Temporary таблиц и промежуточных данных в операциях. Равносильно одновременной установке прагм yt.IntermediateDataMedium, yt.PublishedPrimaryMedium и yt.TemporaryPrimaryMedium.

yt.PublishedCompressionCodec / yt.TemporaryCompressionCodec

Настройки компрессии создаваемых через YQL таблиц.

Published являются таблицы, указанные в INSERT INTO все остальные считаются временными (Temporary). Также кодек, указанный как Temporary, используется для промежуточных данных в рамках одной YTsaurus операции, например слитного MapReduce.

yt.PublishedErasureCodec / yt.TemporaryErasureCodec

Erasure кодирование по умолчанию всегда выключено, для включения рекомендуется использовать значение lrc_12_2_2.

Разница между Published и Temporary аналогична CompressionCodec.

yt.PublishedMedia / yt.TemporaryMedia

Установить на вновь создаваемых таблицах атрибут @media. При его наличии назначает на каких медиумах в YTsaurus будут храниться чанки таблицы.

Published являются таблицы, указанные в INSERT INTO все остальные считаются временными (Temporary).

yt.PublishedPrimaryMedium / yt.TemporaryPrimaryMedium

Установить на вновь создаваемых таблицах атрибут @primary_medium. При его наличии назначает первичный медиум в YTsaurus на который будет осуществляться запись чанков. По умолчанию YTsaurus устанавливает первичный медиум "default".

Published являются таблицы, указанные в INSERT INTO все остальные считаются временными (Temporary).

yt.PublishedReplicationFactor / yt.TemporaryReplicationFactor

Фактор репликации создаваемых через YQL таблиц.

Published являются таблицы, указанные в INSERT INTO все остальные считаются временными (Temporary).

yt.PythonCpu

Множитель для оценки потребления процессора Python UDF, влияет на разбиение MapReduce-операций на джобы.

yt.QueryCacheChunkLimit

Прагма используется для управления способом записи таблиц в кеш в зависимости от количества чанков в таблице: с помощью команды concatenate (как есть) или merge (с объединением).

Пример

PRAGMA yt.QueryCacheChunkLimit = '100000';

Результат

Если количество чанков в таблице меньше установленного лимита, то таблица записывается в кеш командой concatenate как есть.

Если количество чанков превышает заданный лимит — таблица записывается в кеш с помощью команды merge (с объединением чанков).

Таким образом, при значении по умолчанию 0 таблицы записываются в кеш через команду merge.

Особенности и ограничения

Команда concatenate — запись как есть — выполняется быстрее, чем merge, которой требуется время на объединение чанков и последующую запись. Таблицы с относительно небольшим количеством чанков выгоднее записывать в кеш через concatenate.

yt.QueryCacheIgnoreTableRevision

Используйте прагму, чтобы не сбрасывать кеш при изменении данных в таблице. Это ускоряет отладку сложных запросов на больших изменяемых таблицах, когда логика запроса не зависит от изменений данных.

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

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

Пример

PRAGMA yt.QueryCacheIgnoreTableRevision = 'true';

Результат

Если флаг установлен в значение true, то при вычислении хеша из метаданных таблиц исключается номер YTsaurus ревизии, и Query Cache не сбрасывается при изменении содержимого входных таблиц.

Особенности и ограничения

yt.QueryCacheMode

Прагма yt.QueryCacheMode используется для управления кешированием результатов MapReduce‑операций в YTsaurus.

Кеш хранит результаты предыдущих операций: если такая же операция уже выполнялась в одном из предыдущих запросов, то она не будет запускаться. Вместо этого YTsaurus возьмёт готовый результат из кеша. Это ускоряет работу запросов, которые содержат одинаковые с другими запросами вычисления.

Также Query Cache полезен в ситуации, когда вы отлаживаете или вносите относительно небольшие изменения в запрос: в этом случае результат выполнения значительной части операций берётся из кеша.

Пример

PRAGMA yt.QueryCacheMode = 'disable';

Результат

В зависимости от выбранного режима YTsaurus будет использовать, игнорировать или обновлять кеш:

• disable — кеш отключён. YTsaurus не проверяет кеш и не записывает в него результаты. Режим подходит для продакшена, где данные часто меняются: он экономит ресурсы и исключает лишние операции чтения и записи в кеш;
• readonly — режим только для чтения. YTsaurus берёт результат из кеша, если он есть, но не сохраняет в него новые результаты. Подходит для тестирования или отладки: можно использовать старые результаты и не засорять кеш новыми записями;
• refresh — режим только для записи. YTsaurus сохраняет результаты в кеш, но не читает из него. Используется, чтобы обновить кеш: выполнить запрос, не читать из кеша и сохранить его результат для будущего использования;
• normal — режим по умолчанию. YTsaurus и читает из кеша, и записывает в него. Особенно полезен при разработке и отладке, когда один и тот же запрос запускается многократно для ускорения итераций.

В режимах normal и refresh результат операций дополнительно сохраняется по пути //<tmp_folder>/query_cache/<hash>, где:

• tmp_folder — временная директория. По умолчанию — tmp/<login>, можно задать через прагму yt.TmpFolder;
• hash — хеш от значимых метаданных и данных входных таблиц и логической программы, которая выполнялась в операции.

yt.QueryCacheTtl

Прагма используется для установки времени хранения создаваемых операцией таблиц в кеше запросов — TTL (Time to Live) — в директории <tmp_folder>/query_cache/<hash>, где tmp_folder — временная директория. По умолчанию — tmp/<login>, можно задать через прагму yt.TmpFolder.

Пример

PRAGMA yt.QueryCacheTtl = '3h';

Результат

Если в прагме явно указано значение, Query Cache очистится по истечении заданного интервала. Интервал отсчитывается от момента создания таблицы в кеше запросов или от момента последнего использования таблицы (см. прагму yt.QueryCacheUseExpirationTimeout).

Если интервал не задан, Query Cache очистится автоматически через 7 дней (по умолчанию).

yt.QueryCacheUseExpirationTimeout

Прагма определяет режим отсчёта интервала TTL для таблиц в кеше запросов.

Пример

PRAGMA yt.QueryCacheUseExpirationTimeout = 'true';

Результат

При значении по умолчанию false — TTL отсчитывается от момента создания таблицы в кеше запросов.

Если задано значение true — TTL отсчитывается от момента последнего использования таблицы.

Особенности и ограничения

yt.ReduceLocalityTimeout

Задаёт настройку reduce_locality_timeout в спецификации операции (настройка пока не задокументирована).

yt.ReleaseTempData

Позволяет управлять моментом удаления временных объектов (например таблиц), которые создаются при выполнении запроса:

• immediate — удалять объекты сразу как только они становятся не нужны.
• finish — удалять в конце выполнения всего YQL запроса.
• never — никогда не удалять.

yt.SamplingIoBlockSize

Задаёт минимальный размер блока для крупноблочного сэмплирования.

yt.ScriptCpu

Множитель для оценки потребления процессора скриптовых UDF (включая Python UDF. Влияет на разбиение MapReduce-операций на джобы. Может быть переопределён специализированными прагмами yt.PythonCpu / yt.JavascriptCpu для конкретного типа UDF.

yt.SortLocalityTimeout

Задаёт настройку sort_locality_timeout в спецификации операции (настройка пока не задокументирована).

yt.StartedBy

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

yt.StaticNetworkProject

Задаёт использование указанного сетевого проекта в джобах для всех map-reduce операций в запросе (включая evaluation стадию).

yt.StaticPool

Используется для переопределения вычислительного пула, который по умолчанию является логином текущего пользователя.

Новое значение yt.StaticPool может быть только одно — если статическую прагму указать несколько раз, будет использоваться её последнее значение. Если нужно переопределить значение для следующего запроса, задайте его через динамическую прагму yt.Pool.

Сигнатура

PRAGMA yt.StaticPool = '<pool_1>';

Результат

После указания прагмы запрос выполнится в пуле <pool_1>.

Особенности и ограничения

• Указание несуществующего пула приведёт к ошибке выполнения запроса.

• При указании yt.StaticPool несколько раз используется последнее значение прагмы для всех запросов. Например, в pool_2 будут выполнены и запросы, написанные после прагмы со значением pool_1, и запросы после прагмы с pool_2:

  PRAGMA yt.StaticPool = '<pool_1>';
  PRAGMA yt.StaticPool = '<pool_2>';
  

yt.SuspendIfAccountLimitExceeded

Приостанавливать операцию в случае возникновения ошибки "Account limit exceeded" в джобах, см. документацию.

yt.SwitchLimit

Задаёт размер буфера памяти для выполнения Switch узла.

yt.TableContentCompressLevel

Настройка уровня компрессии содержимого таблицы, доставляемого через файл (при yt.TableContentDeliveryMode="file").

yt.TableContentDeliveryMode

Если задано значение native, то содержимое таблицы доставляется в джобы через родные механизмы YTsaurus. При значении file, содержимое таблицы сначала скачивается на сервере YQL, а затем доставляется в джобы как обычный файл.

yt.TableContentMaxChunksForNativeDelivery

Максимальное число чанков в таблице для её доставки в джобы через родные механизмы YTsaurus. При превышении этого числа таблица доставляется через файл.

yt.TableContentMaxInputTables

Максимально число таблиц для доставки в джобы через родные механизмы YTsaurus. При превышении этого числа вставляется предварительный merge.

yt.TableContentMinAvgChunkSize

Минимальный средний размер чанков в таблице для её доставки в джобы через родные механизмы YTsaurus. Для недостаточно больших чанков вставляется предварительный merge.

yt.TableContentTmpFolder

Директория, где будут размещаться временные файлы для таблиц, доставляемых через файл (при yt.TableContentDeliveryMode="file"). Если не задана, то используется стандартный файловый кеш YTsaurus.

yt.TableContentUseSkiff

Включает skiff-формат для доставки таблицы в джобы операций.

yt.TablesTmpFolder

Директория для размещения временных таблиц. Имеет приоритет над yt.TmpFolder.

yt.TempTablesTtl

Позволяет управлять TTL временных таблиц. Имеет эффект для таблиц с полным результатом, остальные временные таблицы безусловно удаляются при завершении запроса независимо от этой прагмы.

yt.TentativePoolTrees

Возможность «осторожно» распространить операции на отличные от стандартных «деревья pool'ов».

yt.TentativeTreeEligibilityMaxJobDurationRatio

Имеет эффект только при наличии прагмы yt.TentativePoolTrees. Задаёт коэффициент допустимого замедления джобов в альтернативном «дереве pool'ов».

yt.TentativeTreeEligibilityMinJobDuration

Имеет эффект только при наличии прагмы yt.TentativePoolTrees. Задаёт минимальную среднюю длительность джобов в альтернативном «дереве pool'ов».

yt.TentativeTreeEligibilitySampleJobCount

Имеет эффект только при наличии прагмы yt.TentativePoolTrees. Задаёт количество джобов в семпле.

yt.TmpFolder

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

Пример

PRAGMA yt.TmpFolder = '//tmp/yql/ivanov/folder';

Результат

Временные таблицы и файлы будут сохраняться в указанную директорию.

yt.TopSortMaxLimit

Максимальное значение LIMIT, используемого в комбинации с ORDER BY, при котором запускается TopSort оптимизация.

yt.TopSortRowMultiplierPerJob

Задаёт ожидаемое число записей на джоб в TopSort операции, вычисляемое как LIMIT * yt.TopSortRowMultiplierPerJob.

yt.TopSortSizePerJob

Задаёт ожидаемый объём данных на джоб в TopSort операции.

yt.UseColumnarStatistics

Включает использование поколоночных статистик для точной оценки размеров джобов при запуске операций поверх таблиц с колоночными выборками. См. документацию.

В режиме auto автоматически отключает использование статистик для операций, на входе которых есть таблицы с optimize_for=lookup.

yt.UseDefaultTentativePoolTrees

Задаёт значение опции use_default_tentative_pool_trees в спецификации операции.

yt.UseNativeYtTypes

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

yt.UserSlots

Ограничение сверху на число выполняющихся параллельно джобов в рамках MapReduce операции.

yt.UseSkiff

Включает skiff-формат для ввода-вывода в джобах операций.

yt.UseTmpfs

Подключает tmpfs к папке _yql_tmpfs в песочнице MapReduce-джобов. Не рекомендуется к использованию.