Прагмы

Заявление PRAGMA является расширением SQL, принятым DuckDB от SQLite. PRAGMA заявления могут быть выпущены аналогично обычным SQL-заявлениям. PRAGMA команды могут изменить внутреннее состояние движка базы данных и повлиять на последующее выполнение или поведение движка.

PRAGMA заявления, которые присваивают значение параметру, также могут быть выпущены с помощью SET заявления, и значение параметра может быть получено с помощью SELECT current_setting(option_name).

Для встроенных параметров конфигурации DuckDB см. Справочник по конфигурации. DuckDB расширения могут регистрировать дополнительные параметры конфигурации. Они документированы на страницах документации соответствующих расширений.

Эта страница содержит поддерживаемые PRAGMA настройки.

Метаданные

Информация о схеме

Список всех баз данных:

PRAGMA database_list;

Список всех таблиц:

PRAGMA show_tables;

Список всех таблиц со дополнительной информацией, аналогично DESCRIBE:

PRAGMA show_tables_expanded;

Чтобы получить список всех функций:

PRAGMA functions;

Информация о таблицах

Получение информации о конкретной таблице:

PRAGMA table_info('table_name');
CALL pragma_table_info('table_name');

table_info возвращает информацию о столбцах таблицы с именем table_name. Точный формат возвращаемой таблицы приведен ниже:

cid INTEGER,        -- cid of the column
name VARCHAR,       -- name of the column
type VARCHAR,       -- type of the column
notnull BOOLEAN,    -- if the column is marked as NOT NULL
dflt_value VARCHAR, -- default value of the column, or NULL if not specified
pk BOOLEAN          -- part of the primary key or not

Размер базы данных

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

SET database_size;
CALL pragma_database_size();

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

database_name VARCHAR, -- database name
database_size VARCHAR, -- total block count times the block size
block_size BIGINT,     -- database block size
total_blocks BIGINT,   -- total blocks in the database
used_blocks BIGINT,    -- used blocks in the database
free_blocks BIGINT,    -- free blocks in the database
wal_size VARCHAR,      -- write ahead log size
memory_usage VARCHAR,  -- memory used by the database buffer manager
memory_limit VARCHAR   -- maximum memory allowed for the database

Информация о хранилище

Для получения информации о хранилище:

PRAGMA storage_info('table_name');
CALL pragma_storage_info('table_name');

Этот вызов возвращает следующую информацию для заданной таблицы:

См. Хранилище для получения дополнительной информации.

Показать базы данных

Следующее утверждение эквивалентно SHOW DATABASES заявлению:

PRAGMA show_databases;

Управление ресурсами

Предел памяти

Установите предел памяти для буферного менеджера:

SET memory_limit = '1GB';
SET max_memory = '1GB';

Предупреждение Установленный предел памяти применяется только к буферному менеджеру. Для большинства запросов буферный менеджер обрабатывает большую часть обрабатываемых данных. Однако некоторые структуры данных в памяти, такие как векторы и результаты запроса, выделены за пределами буферного менеджера. Кроме того, функции агрегирования со сложным состоянием (например, list, mode, quantile, string_agg, и approx функции) используют память за пределами буферного менеджера. Поэтому фактическое потребление памяти может быть выше установленного предела памяти.

Потоки

Установите количество потоков для параллельного выполнения запросов:

SET threads = 4;

Сортировки

Список всех доступных сортировок:

PRAGMA collations;

Установите значение по умолчанию сортировки на одно из доступных значений:

SET default_collation = 'nocase';

По умолчанию сортировка для NULL

Установите значение по умолчанию сортировки для NULL на NULLS_FIRST, NULLS_LAST, NULLS_FIRST_ON_ASC_LAST_ON_DESC или NULLS_LAST_ON_ASC_FIRST_ON_DESC:

SET default_null_order = 'NULLS_FIRST';
SET default_null_order = 'NULLS_LAST_ON_ASC_FIRST_ON_DESC';

Установите значение по умолчанию направления сортировки результата на ASCENDING или DESCENDING:

SET default_order = 'ASCENDING';
SET default_order = 'DESCENDING';

Сортировка по нецелочисленным литералам

По умолчанию сортировка по нецелочисленным литералам не разрешена:

SELECT 42 ORDER BY 'hello world';

-- Binder Error: ORDER BY non-integer literal has no effect.

Чтобы разрешить это поведение, используйте параметр order_by_non_integer_literal:

SET order_by_non_integer_literal = true;

Неявное преобразование к VARCHAR

До версии 0.10.0 DuckDB автоматически разрешал любое неявное преобразование типов к VARCHAR во время привязки функции. В результате можно было, например, вычислить подстроку целого числа без явного преобразования. Для версии v0.10.0 и выше требуется явное преобразование. Чтобы вернуться к старому поведению с неявным преобразованием, установите переменную old_implicit_casting в true:

SET old_implicit_casting = true;

Python: Просмотр всех DataFrames

До версии 1.1.0 механизм замены сканирования DuckDB в Python сканировал глобальное пространство имен Python. Чтобы вернуться к этому старому поведению, используйте следующую настройку:

SET python_scan_all_frames = true;

Информация о DuckDB

Версия

Показать версию DuckDB:

PRAGMA version;
CALL pragma_version();

Платформа

platform возвращает идентификатор платформы, для которой был скомпилирован текущий исполняемый файл DuckDB, например, osx_arm64. Формат этого идентификатора соответствует имени платформы, описанному в разъяснении загрузки расширений:

PRAGMA platform;
CALL pragma_platform();

Пользовательский агент

Следующее утверждение возвращает информацию о пользовательском агенте, например, duckdb/v0.10.0(osx_arm64):

PRAGMA user_agent;

Информация о метаданных

Следующее утверждение возвращает информацию о хранилище метаданных (block_id, total_blocks, free_blocks, и free_list):

PRAGMA metadata_info;

Строка прогресса

Отображение строки прогресса при выполнении запросов:

PRAGMA enable_progress_bar;

Или:

PRAGMA enable_print_progress_bar;

Не отображать строку прогресса при выполнении запросов:

PRAGMA disable_progress_bar;

Или:

PRAGMA disable_print_progress_bar;

Вывод EXPLAIN

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

Конфигурация по умолчанию EXPLAIN:

SET explain_output = 'physical_only';

Чтобы отобразить только оптимизированный план запроса:

SET explain_output = 'optimized_only';

Чтобы отобразить все планы запросов:

SET explain_output = 'all';

Профилирование

Включить профилирование

Следующий запрос включает профилирование с форматом по умолчанию, query_tree. Независимо от формата, enable_profiling является обязательным для включения профилирования.

PRAGMA enable_profiling;
PRAGMA enable_profile;

Формат профилирования

Формат enable_profiling может быть указан как query_tree, json, query_tree_optimizer, или no_output. Каждый формат выводит свой вывод в конфигурируемый выход, за исключением no_output.

Формат по умолчанию — query_tree. Он выводит физический план запроса и метрики каждого оператора в дереве.

SET enable_profiling = 'query_tree';

В качестве альтернативы, json возвращает физический план запроса в формате JSON:

SET enable_profiling = 'json';

Чтобы вернуть физический план запроса, включая метрики оптимизатора и планировщика:

SET enable_profiling = 'query_tree_optimizer';

Драйверы базы данных и другие приложения также могут получать доступ к информации о профилировании через API-вызовы, в этом случае пользователи могут отключить любой другой вывод. Несмотря на то, что параметр считывает no_output, важно отметить, что это только влияет на вывод в настраиваемый выход. При доступе к информации о профилировании через API-вызовы все же важно включить профилирование:

SET enable_profiling = 'no_output';

Вывод профилирования

По умолчанию DuckDB выводит информацию о профилировании в стандартный вывод. Однако, если вы предпочитаете записывать информацию о профилировании в файл, вы можете использовать PRAGMA profiling_output для указания пути к файлу.

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

SET profiling_output = '/path/to/file.json';
SET profile_output = '/path/to/file.json';

Режим профилирования

По умолчанию предоставляется ограниченное количество информации о профилировании (standard).

SET profiling_mode = 'standard';

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

SET profiling_mode = 'detailed';

Настраиваемые метрики

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

Используя custom_profiling_settings PRAGMA, каждую метрику, включая те, которые получены с помощью подробного профилирования, можно индивидуально включить или выключить. Этот PRAGMA принимает JSON-объект с именами метрик в качестве ключей и булевыми значениями для их включения или выключения. Настройки, заданные этим PRAGMA, переопределяют поведение по умолчанию.

Примечание Это влияет только на метрики, когда enable_profiling установлен на json или no_output. query_tree и query_tree_optimizer всегда используют набор метрик по умолчанию.

В следующем примере метрика CPU_TIME отключена. Метрики EXTRA_INFO, OPERATOR_CARDINALITY и OPERATOR_TIMING включены.

SET custom_profiling_settings = '{"CPU_TIME": "false", "EXTRA_INFO": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TIMING": "true"}';

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

Отключить профилирование

Чтобы отключить профилирование:

PRAGMA disable_profiling;
PRAGMA disable_profile;

Оптимизация запросов

Оптимизатор

Чтобы отключить оптимизатор запросов:

PRAGMA disable_optimizer;

Чтобы включить оптимизатор запросов:

PRAGMA enable_optimizer;

Выборочное отключение оптимизаторов

Вариант disabled_optimizers позволяет выборочно отключать шаги оптимизации. Например, чтобы отключить filter_pushdown и statistics_propagation, выполните:

SET disabled_optimizers = 'filter_pushdown,statistics_propagation';

Доступные оптимизации можно запросить, используя duckdb_optimizers() табличную функцию.

Чтобы снова включить оптимизаторы, выполните:

SET disabled_optimizers = '';

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

Ведение журналов

Укажите путь для ведения журнала запросов:

SET log_query_path = '/tmp/duckdb_log/';

Отключить ведение журнала запросов:

SET log_query_path = '';

Индексы полнотекстового поиска

Варианты create_fts_index и drop_fts_index доступны только при загрузке fts расширения. Их использование описано на странице расширения полнотекстового поиска.

Проверка

Проверка внешних операторов

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

PRAGMA verify_external;

Отключить проверку внешних операторов:

PRAGMA disable_verify_external;

Проверка возможностей обратного преобразования

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

PRAGMA verify_serializer;

Отключить проверку возможностей обратного преобразования:

PRAGMA disable_verify_serializer;

Кэш объектов

Включить кэширование объектов, например, метаданных Parquet:

PRAGMA enable_object_cache;

Отключить кэширование объектов:

PRAGMA disable_object_cache;

Фиксация

Вынужденная фиксация

Когда CHECKPOINT вызывается при отсутствии изменений, выполнить фиксацию независимо от этого:

PRAGMA force_checkpoint;

Фиксация при выключении

Выполнить CHECKPOINT при успешном выключении и удалить WAL, оставив только один файл базы данных:

PRAGMA enable_checkpoint_on_shutdown;

Не выполнять CHECKPOINT при выключении:

PRAGMA disable_checkpoint_on_shutdown;

Временный каталог для вывода данных на диск

По умолчанию DuckDB использует временный каталог с именем ⟨database_file_name⟩.tmp для вывода на диск, расположенный в том же каталоге, что и файл базы данных. Чтобы изменить это, используйте:

SET temp_directory = '/path/to/temp_dir.tmp/';

Возвращение ошибок в формате JSON

Вариант errors_as_json можно установить для получения информации об ошибках в формате JSON. Для определенных ошибок предоставляется дополнительная или разложенная информация для более удобной обработки машиной. Например:

SET errors_as_json = true;

Затем, при запуске запроса, который приводит к ошибке, генерируется JSON-вывод:

SELECT * FROM nonexistent_tbl;

{
   "exception_type":"Catalog",
   "exception_message":"Table with name nonexistent_tbl does not exist!\nDid you mean \"temp.information_schema.tables\"?",
   "name":"nonexistent_tbl",
   "candidates":"temp.information_schema.tables",
   "position":"14",
   "type":"Table",
   "error_subtype":"MISSING_ENTRY"
}

Семантика операций с плавающей точкой IEEE

DuckDB следует семантике операций с плавающей точкой IEEE. Если вы хотите отключить это, выполните:

SET ieee_floating_point_ops = false;

В этом случае деление на ноль с плавающей точкой (например, 1.0 / 0.0, 0.0 / 0.0 и -1.0 / 0.0) вернет NULL.

Проверка запросов (для разработки)

Следующие PRAGMA в основном используются для разработки и внутренних тестов.

Включить проверку запросов:

PRAGMA enable_verification;

Отключить проверку запросов:

PRAGMA disable_verification;

Включить принудительное параллельное выполнение запросов:

PRAGMA verify_parallelism;

Отключить принудительное параллельное выполнение запросов:

PRAGMA disable_verify_parallelism;

Размеры блоков

При сохранении базы данных на диск DuckDB записывает в отдельный файл список блоков, содержащих данные. В случае файла, содержащего очень мало данных, например, небольшой таблицы, размер блока по умолчанию 256 КБ может быть не оптимальным. Поэтому формат хранения DuckDB поддерживает различные размеры блоков.

Существуют некоторые ограничения на возможные значения размера блока.

• Должен быть степенью двойки.
• Должен быть больше или равен 16384 (16 КБ).
• Должен быть меньше или равен 262144 (256 КБ).

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

SET default_block_size = '16384';

Также можно установить размер блока для каждого файла, см. ATTACH для получения подробностей.