Коннектор DuckDB#

Коннектор DuckDB позволяет запрашивать и создавать таблицы во внешнем экземпляре DuckDB. Его можно использовать для объединения данных между разными системами, например DuckDB и Hive, или между двумя разными экземплярами DuckDB.

Требования#

Все узлы кластера должны включать libstdc++, необходимую для JDBC-драйвера DuckDB.
Путь к постоянной базе данных DuckDB должен быть одинаковым, доступным на всех узлах кластера и указывать на одно и то же расположение хранилища.

Конфигурация#

Коннектор может запрашивать базу данных DuckDB. Создайте файл свойств каталога, который указывает коннектор DuckDB, задав connector.name равным duckdb.

Например, чтобы обращаться к базе данных как к каталогу example, создайте файл etc/catalog/example.properties. Замените свойства подключения в соответствии с вашей средой:

connector.name=duckdb
connection-url=jdbc:duckdb:<path>

connection-url задает сведения о подключении и параметры, передаваемые JDBC-драйверу DuckDB. Параметры URL доступны в документации JDBC-драйвера DuckDB.

<path> должен указывать на существующий постоянный файл базы данных DuckDB. Например, используйте jdbc:duckdb:/opt/duckdb/trino.duckdb для базы данных, созданной командой duckdb /opt/duckdb/trino.duckdb. База данных автоматически содержит схему main и схему information_schema. Используйте схему main для новых таблиц или создайте новую схему.

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

Использование базы данных DuckDB в памяти jdbc:duckdb: не поддерживается.

Рекомендации по защите DuckDB см. в документации DuckDB. Обратите внимание, что Trino подключается к базе данных с помощью JDBC-драйвера и не использует DuckDB CLI.

Несколько серверов DuckDB#

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

Сопоставление типов#

Поскольку Trino и DuckDB поддерживают типы, которых нет в другой системе, этот коннектор изменяет некоторые типы при чтении или записи данных. Типы данных могут сопоставляться по-разному в направлениях между Trino и источником данных. В следующих разделах описано сопоставление типов для каждого направления.

Список типов данных DuckDB.

Сопоставление типов DuckDB с типами Trino#

Коннектор сопоставляет типы DuckDB с соответствующими типами Trino согласно следующей таблице:

Сопоставление типов DuckDB с типами Trino#
Тип DuckDB	Тип Trino	Примечания
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`FLOAT`	`REAL`
`DOUBLE`	`DOUBLE`
`DECIMAL`	`DECIMAL`	Точность и масштаб по умолчанию равны (18,3).
`VARCHAR`	`VARCHAR`
`DATE`	`DATE`

Другие типы не поддерживаются.

Сопоставление типов Trino с типами DuckDB#

Коннектор сопоставляет типы Trino с соответствующими типами DuckDB согласно следующей таблице:

Сопоставление типов Trino с типами DuckDB#
Тип Trino	Тип DuckDB	Примечания
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`REAL`	`REAL`
`DOUBLE`	`DOUBLE`
`DECIMAL`	`DECIMAL`
`CHAR`	`VARCHAR`
`VARCHAR`	`VARCHAR`
`DATE`	`DATE`

Другие типы не поддерживаются.

Свойства конфигурации сопоставления типов#

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

Имя свойства

Описание

Значение по умолчанию

unsupported-type-handling

Настраивает обработку неподдерживаемых типов данных столбцов:

IGNORE — столбец недоступен.
CONVERT_TO_VARCHAR — столбец преобразуется в неограниченный VARCHAR.

Соответствующее свойство сеанса каталога — unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

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

Поддержка SQL#

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

Процедуры#

`system.flush_metadata_cache()`#

Очищает кэши метаданных JDBC. Например, следующий системный вызов очищает кэши метаданных для всех схем в каталоге example:

USE example.example_schema;
CALL system.flush_metadata_cache();

`system.execute('query')`#

Процедура execute позволяет выполнить запрос напрямую в базовом источнике данных. Запрос должен использовать поддерживаемый синтаксис подключенного источника данных. Используйте процедуру для доступа к возможностям, которые недоступны в Trino, или для выполнения запросов, которые не возвращают набор результатов и поэтому не могут использоваться с транзитной табличной функцией query или raw_query. Типичные случаи применения — операторы, создающие или изменяющие объекты и требующие нативных возможностей, таких как ограничения, значения по умолчанию, автоматическое создание идентификаторов или индексы. Запросы также могут вызывать операторы, которые вставляют, обновляют или удаляют данные и не возвращают данных в результате.

Текст запроса не разбирается Trino, а только передается дальше, поэтому он подчиняется только правилам безопасности и контроля доступа базового источника данных.

В следующем примере текущая база данных устанавливается в example_schema каталога example. Затем в этой схеме вызывается процедура, чтобы удалить значение по умолчанию из your_column в таблице your_table с помощью стандартного SQL-синтаксиса в значении параметра query:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

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

Табличные функции#

Коннектор предоставляет специальные табличные функции для доступа к DuckDB.

`query(varchar) -> table`#

Функция query позволяет напрямую запрашивать базовую базу данных. Она требует синтаксис, родной для DuckDB, поскольку весь запрос проталкивается вниз и обрабатывается в DuckDB. Это может быть полезно для доступа к нативным возможностям, недоступным в Trino, или для повышения производительности запросов в ситуациях, когда выполнение запроса нативно может быть быстрее.

Сведения о поддержке SQL в DuckDB, которую можно использовать в запросе, см. в справочнике команд SQL DuckDB и в документации по другим операторам и функциям.

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

Как простой пример, запросите каталог example и выберите всю таблицу:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        *
      FROM
        tpch.nation'
    )
  );

Note

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