WITH

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

Поддерживаются следующие значения:

• INFER_SCHEMA — задает флаг вывода схемы таблицы. Поведение аналогично заданию прагмы yt.InferSchema, только для конкретного источника данных. Можно задать число строк для выведения (число от 1 до 1000).
• FORCE_INFER_SCHEMA — задает флаг вывода схемы таблицы. Поведение аналогично заданию прагмы yt.ForceInferSchema, только для конкретного источника данных. Можно задать число строк для выведения (число от 1 до 1000).
• DIRECT_READ — подавляет работу некоторых оптимизаторов и заставляет использовать содержимое таблицы как есть. Поведение аналогично заданию отладочной прагмы DirectRead, только для конкретного источника данных.
• INLINE — указание на то, что содержимое таблицы небольшое и нужно использовать его представление в памяти для обработки запроса. Реальный объем таблицы при этом не контролируется, и если он большой, то запрос может упасть по превышению памяти.
• UNORDERED — подавляет использование исходной сортировки таблицы.
• XLOCK — указание на то, что нужно брать эксклюзивный лок на таблицу. Полезен, когда чтение таблицы происходит на стадии обработки метапрограммы запроса, а затем ее содержимое обновляется в основном запросе. Позволяет избежать потери данных, если между исполнением фазы метапрограммы и основной частью запроса внешний процесс успел изменить таблицу.
• SCHEMA type — указание на то, что следует использовать указанную схему таблицы целиком, игнорируя схему в метаданных.
• COLUMNS type — указание на то, что следует использовать указанные типы для колонок, чьи имена совпадают с именами колонок таблицы в метаданных, а также какие колонки дополнительно присутствуют в таблице.
• IGNORETYPEV3, IGNORE_TYPE_V3 — задает флаг игнорирования type_v3 типов в таблице. Поведение аналогично заданию прагмы yt.IgnoreTypeV3, только для конкретного источника данных.

При работе с внешними файловыми источниками данных можно дополнительно указывать ряд параметров:

• FORMAT - формат хранимых данных в файловых хранилищах в федеративных запросах. Допустимые значения: csv_with_names, tsv_with_names, json_list, json_each_row, json_as_string, parquet, raw.
• COMPRESSION - формат сжатия файлов в файловых хранилищах в федеративных запросах. Допустимые значения: gzip, zstd, lz4, brotli, bzip2, xz.
• PARTITIONED_BY - список колонок партиционирования данных в файловых хранилищах в федеративных запросах. Содержит список колонок в порядке их размещения в файловом хранилище.
• projection.enabled - флаг включения расширенного партиционирования данных. Допустимые значения: true, false.
• projection.<field_name>.type - тип поля расширенного партиционирования данных. Допустимые значения: integer, enum, date.
• projection.<field_name>.<options> - расширенные свойства поля расширенного партиционирования данных.

При чтении из топика в потоковых запросах можно указывать параметры watermarks:

• WATERMARK — выражение для вычисления watermark. Сейчас поддерживается только время записи в топик с константной задержкой. Формат: __ydb_write_time - Interval("<delay>"), где <delay> задаётся в формате ISO 8601.
• WATERMARK_GRANULARITY — периодичность генерации watermarks. Чем она меньше, тем больше потребление CPU запросом и тем меньше задержка ответа. Имеет смысл только для потоковых запросов. Задаётся в формате ISO 8601. Значение по умолчанию — 1 секунда.
• WATERMARK_IDLE_TIMEOUT — период, после которого простаивающая партиция будет исключена из вычисления объединённого watermark. Имеет смысл только для потоковых запросов. Задаётся в формате ISO 8601. Значение по умолчанию — 5 секунд.

При задании подсказок SCHEMA и COLUMNS в качестве значения типа type должен быть задан тип структуры.

Примеры

SELECT key FROM my_table WITH INFER_SCHEMA;
SELECT key FROM my_table WITH FORCE_INFER_SCHEMA="42";

$s = (SELECT COUNT(*) FROM my_table WITH XLOCK);

INSERT INTO my_table WITH TRUNCATE
SELECT EvaluateExpr($s) AS a;

SELECT key, value FROM my_table WITH SCHEMA Struct<key:String, value:Int32>;

SELECT key, value FROM my_table WITH COLUMNS Struct<value:Int32?>;

SELECT key, value FROM EACH($my_tables) WITH SCHEMA Struct<key:String, value:List<Int32>>;

SELECT
    *
FROM
    my_topic
WITH (
    FORMAT = json_each_row,
    SCHEMA = (
        ts String
    ),
    WATERMARK = __ydb_write_time - Interval("PT5S"),
    WATERMARK_GRANULARITY = "PT1S",
    WATERMARK_IDLE_TIMEOUT = "PT5S"
);