path: root/yql/essentials/docs/ru/syntax/pragma.md

# PRAGMA

## Определение

Переопределение настроек.

### Синтаксис

`PRAGMA x.y = "z";` или `PRAGMA x.y("z", "z2", "z3");`:

* `x` — (опционально) категория настройки.
* `y` — название настройки.
* `z` — (опционально для флагов) значение настройки. Допустимо использование следующих суффиксов:

  * `Kb`, `Mb`, `Gb` — для объема информации.
  * `sec`, `min`, `h`, `d` — для временных значений.

За некоторым исключением, значение настроек можно вернуть в состояние по умолчанию с помощью `PRAGMA my_pragma = default;`.

### Примеры

```yql
PRAGMA AutoCommit;
```

```yql
PRAGMA TablePathPrefix = "home/yql";
```

```yql
PRAGMA Warning("disable", "1101");
```

Полный список доступных настроек [см. в таблице ниже](#pragmas).

### Область действия {#pragmascope}

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

Существуют также специальные scoped прагмы, область действия которых определяется по тем же правилам, что и область видимости [именованных выражений](expressions.md#named-nodes).

В отличие от scoped прагм, обычные прагмы могут использоваться только в глобальной области видимости (не внутри [DEFINE ACTION](action.md#define-action) и [DEFINE SUBQUERY](subquery.md#define-subquery)).

## Глобальные {#pragmas}

### AutoCommit {#autocommit}

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Автоматически выполнять [COMMIT](select/index.md#commit) после каждого выражения.

### TablePathPrefix {#table-path-prefix}

| Тип значения | По умолчанию |
| --- | --- |
| Строка | — |

Добавить указанный префикс к путям таблиц внутри кластеров. Работает по принципу объединения путей в файловой системе: поддерживает ссылки на родительский каталог `..` и не требует добавления слеша справа. Например,

```yql
PRAGMA TablePathPrefix = "home/yql";
SELECT * FROM test;
```

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

### UDF {#udf}

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Строка | — | Статическая |
| Строка &mdash; имя префикса, добавляемого ко всем модулям | "" | Статическая |

Импорт всех UDF из указанной библиотеки. Чтобы прагма сработала, библиотеку необходимо приложить к запросу. Обратите внимание: библиотека должна быть разделяемой (.so) и она должна быть скомпилирована под Linux x64.

При указании префикса, он добавляется перед названием всех загруженных модулей, например, CustomPrefixIp::IsIPv4 вместо Ip::IsIPv4. Указание префикса позволяет подгрузить одну и ту же UDF разных версий.

### RuntimeLogLevel {#runtime-log-level}

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Строка, одно из `Trace`, `Debug`, `Info`, `Notice`, `Warn`, `Error`, `Fatal` | `Info` | Статическая |

Позволяет поменять уровень логирования вычислений (например, для UDF) во время выполнения запроса или на этапе декларации сигнатуры UDF.

### UseTablePrefixForEach {#use-table-prefix-for-each}

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

`EACH` использует [TablePathPrefix](#table-path-prefix) для каждого элемента списка.

### Warning {#warning}

| Тип значения | По умолчанию |
| --- | --- |
| 1. Действие<br/>2. Код предупреждения либо символ "*"| — |

Действие:

* `disable` — отключить;
* `error` — приравнять к ошибке;
* `default` — вернуть поведение по умолчанию.

Код предупреждения возвращается вместе с самим текстом (в веб-интерфейсе отображается справа).

Примеры:

`PRAGMA Warning("error", "*");`
`PRAGMA Warning("disable", "1101");`
`PRAGMA Warning("default", "4503");`

В данном случае все предупреждения будут считаться ошибками, за исключением предупреждения с кодом `1101`, которое будет отключено, и `4503`, которое будет обрабатываться по умолчанию (то есть останется предупреждением). Поскольку предупреждения могут добавляться в новых релизах YQL, следует с осторожностью пользоваться конструкцией `PRAGMA Warning("error", "*");` (как минимум покрывать такие запросы автотестами).

### Greetings {#greetings}

| Тип значения | По умолчанию |
| --- | --- |
| Текст | — |

Выдать указанный текст в качестве Info сообщения запроса.

Пример: `PRAGMA Greetings("It's a good day!");`

### WarningMsg {#warningmsg}

| Тип значения | По умолчанию |
| --- | --- |
| Текст | — |

Выдать указанный текст в качестве Warning сообщения запроса.

Пример:
`PRAGMA WarningMsg("Attention!");`

### SimpleColumns {#simplecolumns}

`SimpleColumns` / `DisableSimpleColumns`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | true |

При использовании `SELECT foo.* FROM ... AS foo` убрать префикс  `foo.` у имен результирующих колонок.

Работает в том числе и для [JOIN](join.md), но в этом случае имеет право упасть в случае конфликта имен (который можно разрешить с помощью [WITHOUT](select/without.md) и переименования колонок). Для JOIN в режиме SimpleColumns производится неявный Coalesce для ключевых колонок: запрос `SELECT * FROM T1 AS a JOIN T2 AS b USING(key)` в режиме SimpleColumns работает как `SELECT a.key ?? b.key AS key, ... FROM T1 AS a JOIN T2 AS b USING(key)`

### CoalesceJoinKeysOnQualifiedAll

`CoalesceJoinKeysOnQualifiedAll` / `DisableCoalesceJoinKeysOnQualifiedAll`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | true |

Управляет неявным Coalesce для ключевых колонок `JOIN` в режиме SimpleColumns. Если флаг установлен, то Coalesce ключевых колонок происходит при наличии хотя бы одного выражения вида `foo.*` или `*` в SELECT &mdash; например `SELECT a.* FROM T1 AS a JOIN T2 AS b USING(key)`. Если флаг сброшен, то Coalesce ключей JOIN происходит только при наличии '*' после `SELECT`.

### StrictJoinKeyTypes

`StrictJoinKeyTypes` / `DisableStrictJoinKeyTypes`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Если флаг установлен, то [JOIN](join.md) будет требовать строгого совпадения типов ключей.
По умолчанию JOIN предварительно конвертирует ключи к общему типу, что может быть нежелательно с точки зрения производительности.

StrictJoinKeyTypes является [scoped](#pragmascope) настройкой.


### AnsiInForEmptyOrNullableItemsCollections

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Наличие этой прагмы приводит поведение оператора `IN` в соответствие со стандартом в случае наличия `NULL` в левой или правой части оператора `IN`. Также изменено поведение `IN` в случае, когда справа был Tuple с элементами разных типов. Примеры:

`1 IN (2, 3, NULL) = NULL (было Just(False))`
`NULL IN () = Just(False) (было NULL)`
`(1, null) IN ((2, 2), (3, 3)) = Just(False) (было NULL)`

Подробнее про поведение `IN` при наличии NULL-ов в операндах можно почитать [здесь](expressions.md#in). Явным образом выбрать старое поведение можно, указав прагму `DisableAnsiInForEmptyOrNullableItemsCollections`. Если никакой прагмы не задано, то выдается предупреждение и работает старый вариант.

### AnsiRankForNullableKeys

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Приводит поведение RANK/DENSE_RANK в соответствие со стандартом при наличии опциональных типов в ключах сортировки окна или в аргументе этих оконных функций. А именно:

* типом результата всегда является Uint64, а не Uint64?;
* null-ы в ключах считаются равными друг другу (текущая реализация возвращает NULL).

Явным образом выбрать старое поведение можно, указав прагму `DisableAnsiRankForNullableKeys`. Если никакой прагмы не задано, то выдается предупреждение и работает старый вариант.

### AnsiCurrentRow

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Приводит неявное задание рамки окна при наличии [ORDER BY](select/order_by.md) в соответствие со стандартом.

Если AnsiCurrentRow не установлен, то окно `(ORDER BY key)` эквивалентно `(ORDER BY key ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)`. Стандарт же требует, чтобы такое окно вело себя как `(ORDER BY key RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)`.

Разница состоит в трактовке `CURRENT ROW`. В режиме `ROWS` `CURRENT ROW` трактуется буквально – текущая строка в партиции.
А в режиме `RANGE` конец рамки `CURRENT ROW` означает "последняя строка в партиции с ключом сортировки, равным текущей строке".

### OrderedColumns {#orderedcolumns}

`OrderedColumns` / `DisableOrderedColumns`

Выводить [порядок колонок](select/index.md#orderedcolumns) в SELECT/JOIN/UNION ALL и сохранять его при записи результатов. По умолчанию порядок колонок не определен.

### PositionalUnionAll {#positionalunionall}

Включить соответствующий стандарту поколоночный режим выполнения [UNION ALL](select/index.md#unionall). При этом автоматически включается [упорядоченность колонок](#orderedcolumns).

### RegexUseRe2

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Использовать Re2 UDF вместо Pcre для выполнения SQL операторов `REGEX`,`MATCH`,`RLIKE`. Re2 UDF поддерживает корректную обработку Unicode-символов в отличие от используемой по умолчанию Pcre UDF.

### ClassicDivision

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | true |

В классическом варианте результат целочисленного деления остается целочисленным (по умолчанию). Если отключить &mdash; результат всегда становится Double.

`ClassicDivision` является [scoped](#pragmascope) настройкой.

### CheckedOps

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

При включенном режиме: если в результате выполнения агрегационных функций SUM/SUM_IF, бинарных операций `+`,`-`,`*`,`/`,`%` или унарной операции `-` над целыми числами происходит выход за границы целевого типа аргументов или результата, то возвращается `NULL`. Если отключить &mdash; переполнение не проверяется.

Не влияет на операции с числами с  плавающей точкой или `Decimal`.

`CheckedOps` является [scoped](#pragmascope) настройкой.

### UnicodeLiterals

`UnicodeLiterals`/`DisableUnicodeLiterals`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

При включенном режиме строковые литералы без суффиксов вида "foo"/'bar'/@@multiline@@ будут иметь тип `Utf8`, при выключенном &mdash; `String`.

`UnicodeLiterals` является [scoped](#pragmascope) настройкой.

### WarnUntypedStringLiterals

`WarnUntypedStringLiterals`/`DisableWarnUntypedStringLiterals`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

При включенном режиме для строковых литералов без суффиксов вида "foo"/'bar'/@@multiline@@ будет генерироваться предупреждение. Его можно подавить, если явно выбрать суффикс `s` для типа `String`, либо `u` для типа `Utf8`.

`WarnUntypedStringLiterals` является [scoped](#pragmascope) настройкой.

### AllowDotInAlias

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

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

### WarnUnnamedColumns

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Генерировать предупреждение, если для безымянного выражения в `SELECT` было автоматически сгенерировано имя колонки (вида `column[0-9]+`).

### GroupByLimit

| Тип значения | По умолчанию |
| --- | --- |
| Положительное число | 32 |

Увеличение лимита на число группировок в [GROUP BY](group_by.md).

### GroupByCubeLimit

| Тип значения | По умолчанию |
| --- | --- |
| Положительное число | 5 |

Увеличение лимита на число размерностей [GROUP BY](group_by.md#rollup-cube-group-sets).

Использовать нужно аккуратно, так как вычислительная сложность запроса растет экспоненциально по отношению к числу размерностей.


## Yson

Управление поведением Yson UDF по умолчанию, подробнее см. в [документации](../udf/list/yson.md) и в частности [Yson::Options](../udf/list/yson.md#ysonoptions).

### `yson.AutoConvert`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

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

### `yson.Strict`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | true |

Управление строгим режимом во всех вызовах Yson UDF, в том числе и неявных. Без значения или при значении `"true"` &mdash; включает строгий режим. Со значением `"false"` &mdash; отключает.

### `yson.DisableStrict`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Инвертированная версия `yson.Strict`. Без значения или при значении `"true"` &mdash; отключает строгий режим. Со значением `"false"` &mdash; включает.


## Работа с файлами

### File

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Два или три строковых аргумента — алиас, URL и опциональное имя токена | — | Статическая |

Приложить файл к запросу по URL. Использовать приложенные файлы можно с помощью встроенных функций [FilePath и FileContent](../builtins/basic.md#filecontent).

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

### FileOption

| Тип значения                                    | По умолчанию | Статическая /<br/> динамическая |
|-------------------------------------------------|--------------|--------------------------------|
| Три строковых аргумента — алиас, ключ, значение | —            | Статическая                    |

Установить для указанного файла опцию по заданному ключу в заданное значение. Файл с этим алиасом уже должен быть объявлен через [PRAGMA File](#file) или приложен к запросу.



### Folder

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Два или три строковых аргумента — префикс, URL и опциональное имя токена | — | Статическая |

Приложить набор файлов к запросу по URL. Работает аналогично добавлению множества файлов через [PRAGMA File](#file) по прямым ссылкам на файлы с алиасами, полученными объединением префикса с именем файла через `/`.

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

### Library

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Один или два аргумента &mdash; имя файла и опциональный URL | — | Статическая |

Интерпретировать указанный приложенный файл как библиотеку, из которой можно делать [IMPORT](export_import.md). Тип синтаксиса библиотеки определяется по расширению файла:
* `.sql` для YQL диалекта SQL <span style="color: green;">(рекомендуется)</span>;
* `.yqls` для [s-expressions](/docs/s_expressions).

Пример с приложенным файлом к запросу:

```yql
PRAGMA library("a.sql");
IMPORT a SYMBOLS $x;
SELECT $x;
```

В случае указания URL библиотека скачивается с него, а не с предварительного приложенного файла, как в следующем примере:

```yql
PRAGMA library("a.sql","http://intranet.site/5618566/text");
IMPORT a SYMBOLS $x;
SELECT $x;
```

При этом можно использовать подстановку текстовых параметров в URL:

```yql
DECLARE $_ver AS STRING; -- "5618566"
PRAGMA library("a.sql","http://intranet.site/{$_ver}/text");
IMPORT a SYMBOLS $x;
SELECT $x;
```

### Package

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Два или три аргумента &mdash; имя пакета, URL и опциональный токен | — | Статическая |

Приложить иерархический набор файлов к запросу по URL, интерпретируя их в качестве пакета с указанным именем &mdash; взаимосвязанного набора библиотек.

Имя пакета ожидается в формате ``project_name.package_name``; из библиотек пакета в дальнейшем можно делать [IMPORT](export_import.md) с именем модуля вида ``pkg.project_name.package_name.maybe.nested.module.name``.

Пример для пакета с плоской иерархией, состоящего из двух библиотек &mdash; foo.sql и bar.sql:

```yql
PRAGMA package("project.package", "http://intranet.site/path/to/package");
IMPORT pkg.project.package.foo SYMBOLS $foo;
IMPORT pkg.project.package.bar SYMBOLS $bar;
SELECT $foo, $bar;
```

При этом можно использовать подстановку текстовых параметров в URL:

```yql
DECLARE $_path AS STRING; -- "path"
PRAGMA package("project.package","http://intranet.site/{$_path}/to/package");
IMPORT pkg.project.package.foo SYMBOLS $foo;
IMPORT pkg.project.package.bar SYMBOLS $bar;
SELECT $foo, $bar;
```

### OverrideLibrary

| Тип значения | По умолчанию | Статическая /<br/>динамическая |
| --- | --- | --- |
| Один аргумент &mdash; имя файла | — | Статическая |

Интерпретировать указанный приложенный файл как библиотеку и перекрыть ей одну из библиотек пакета.

Имя файла ожидается в формате ``project_name/package_name/maybe/nested/module/name.EXTENSION``, поддерживаются аналогичные [PRAGMA Library](#library) расширения.

Пример:

```yql
PRAGMA package("project.package", "http://intranet.site/path/to/package");
PRAGMA override_library("project/package/maybe/nested/module/name.sql");

IMPORT pkg.project.package.foo SYMBOLS $foo;
SELECT $foo;
```

## Отладочные и служебные {#debug}

### `config.flags("ValidateUdf", "Lazy")`

| Тип значения | По умолчанию |
| --- | --- |
| Строка: None / Lazy / Greedy | None |

Валидация результатов UDF на соответствие объявленной сигнатуре. Greedy режим форсирует материализацию «ленивых» контейнеров, а Lazy — нет.

### `config.flags("Diagnostics")`

| Тип значения | По умолчанию |
| --- | --- |
| Флаг | false |

Получение диагностической информации от YQL в виде дополнительного результата запроса.