ADBC Catalog

Обзор

ADBC (Arrow Database Connectivity) представляет собой интерфейс доступа к базам данных, определенный экосистемой Arrow. ADBC Catalog читает данные из внешнего источника через драйвер ADBC: данные передаются по сети в формате Arrow, а несколько узлов BE читают их параллельно.

Два аспекта отличаются от JDBC Catalog:

• Передача в формате Arrow. Данные передаются по сети в формате Arrow, и Doris читает их напрямую, без построчного преобразования каждого значения, которое выполняет JDBC Catalog.
• Параллельное чтение. Одно сканирование разделяется на разделы результатов, формируемые самим драйвером, и выполняется несколькими узлами BE одновременно, вместо чтения одним узлом BE через одно соединение.

примечание

• Это экспериментальная функция, поддерживаемая начиная с версии 5.0.0.
• Поддерживаются только операции чтения. Запись во внешний источник данных не поддерживается.
• Doris поставляется без драйвера ADBC. Библиотеку драйвера необходимо самостоятельно разместить на FE и на каждом узле BE.

На текущем этапе основное внимание уделяется источникам данных Arrow Flight SQL, включая другие кластеры Doris; этот механизм заменяет Doris Catalog. Для подключения другого источника данных достаточно его собственной библиотеки драйвера ADBC и реализации диалекта, если его SQL отличается от ANSI SQL.

Отличия от JDBC Catalog

Аспект	JDBC Catalog	ADBC Catalog
Передача данных	Строки источника преобразуются в объекты JDBC, а затем по одному значению в данные Doris	Данные передаются в формате Arrow и читаются напрямую, без преобразования отдельных значений
Параллелизм чтения	Один узел BE через одно соединение	Сканирование разделяется на разделы результатов драйвера, которые читаются несколькими узлами BE
Формат драйвера	JAR-файл драйвера JDBC, который можно скачать по удаленному URL	Разделяемая библиотека драйвера ADBC (.so), на которую можно ссылаться только как на локальный файл
Поддержка записи	Обратная запись поддерживается	Пока не поддерживается

Сценарии применения

Сценарий	Описание
Интеграция данных	Чтение из внешнего источника данных во внутреннюю таблицу Doris или выполнение федеративных запросов к внутренним таблицам и таблицам в других Catalog. Данные передаются в формате Arrow и читаются параллельно несколькими узлами BE, что обеспечивает более высокую производительность по сравнению с JDBC.
Обратная запись	Не поддерживается.

Обзор возможностей

Возможность	Поддержка	Описание
Доступ к метаданным	Поддерживается	SHOW DATABASES, SHOW TABLES, DESC, SHOW CREATE TABLE и information_schema
Запросы к данным	Поддерживается	Запросы к внешним таблицам, а также соединения, агрегация, ORDER BY, UNION и подзапросы с внутренними таблицами и таблицами в других Catalog
Отсечение столбцов	Поддерживается	У источника данных запрашиваются только столбцы, необходимые запросу
Проталкивание предикатов	Поддерживается	Некоторые скалярные предикаты включаются в удаленное предложение WHERE
Проталкивание LIMIT	Поддерживается	Применяется после проталкивания всего предложения WHERE
Оптимизация COUNT(*)	Поддерживается	Данные столбцов не читаются
Параллельное чтение	Поддерживается	Сканирование разделяется на разделы результатов драйвера, которые читаются несколькими узлами BE
Сопоставление типов	Поддерживается	Автоматическое, включая ARRAY, MAP, STRUCT, DECIMAL, даты и временные метки с часовым поясом и без него
Кэш метаданных	Поддерживается	По умолчанию данные кэшируются на 10 минут; любой оператор REFRESH очищает кэш
SELECT INTO OUTFILE	Поддерживается	Результаты запроса можно экспортировать в файл
Материализованные представления (MTMV)	Поддерживается	На основе таблицы ADBC можно создать и обновлять MTMV
Запись в источник данных	Пока не поддерживается	INSERT, CREATE TABLE, DROP TABLE и другие операторы записи отклоняются
Статистика	Пока не поддерживается	Сбор статистики недоступен
Проталкивание агрегации	Пока не поддерживается	Агрегация выполняется в Doris

Развертывание драйвера ADBC

Doris поставляется без драйвера ADBC, поэтому разместите библиотеку драйвера на узлах кластера перед созданием Catalog.

Требования к размещению драйвера

предупреждение

При выполнении CREATE CATALOG FE преобразует driver_url в абсолютный путь и передает этот путь узлам BE без изменений. Каждый BE загружает драйвер именно по этому пути. Поэтому:

• Файл драйвера должен находиться по одному и тому же абсолютному пути на FE и на каждом узле BE.
• FE и все BE должны загружать одну и ту же сборку. ADBC описывает информацию о разделах во внутреннем формате драйвера, для которого совместимость между реализациями драйверов не гарантируется. Использование разных версий драйвера может вообще не вызвать ошибку, а просто привести к неверным результатам.

При сборке создаются два каталога для драйверов:

• FE: <FE_HOME>/plugins/adbc_drivers
• BE: <BE_HOME>/plugins/adbc_drivers

FE и BE обычно размещаются в разных каталогах развертывания, поэтому эти два абсолютных пути не совпадают. При развертывании на нескольких узлах разместите драйвер по одному и тому же абсолютному пути на каждом узле FE и BE, например /opt/doris/adbc_drivers, и укажите этот каталог в параметре drivers_dir файла adbc.conf на FE.

adbc.conf

Плагин коннектора ADBC читает настройки из файла <DORIS_HOME>/plugins/connector/adbc/adbc.conf на FE. Этот файл должен существовать на каждом узле FE. Doris не реплицирует его через метаданные Catalog, а изменения вступают в силу после перезапуска FE.

Параметр	По умолчанию	Описание
drivers_dir	<DORIS_HOME>/plugins/adbc_drivers	Каталог, относительно которого разрешается имя файла без пути в driver_url.
driver_secure_path	*	Каталоги, из которых разрешено загружать драйвер, разделенные точками с запятой (;). Значение * или пустое значение разрешает любой каталог. Если заданы конкретные пути, путь к драйверу проверяется по отдельным компонентам, поэтому ограничение нельзя обойти ни с помощью переходов по каталогам, ни за счет совпадения префикса (/opt/drv и /opt/drv-evil).

Пример конфигурации:

drivers_dir=/opt/doris/adbc_drivers
driver_secure_path=/opt/doris/adbc_drivers

Настройка Catalog

Синтаксис

CREATE CATALOG [IF NOT EXISTS] catalog_name PROPERTIES (
    'type' = 'adbc',
    'driver_url' = '<driver_url>',
    'uri' = '<connection_uri>',
    {DriverProperties},
    {ConnectionProperties},
    {ReadProperties},
    {DriverOptions},
    {CommonProperties}
);

• <driver_url>

  Обязательный параметр. Разделяемая библиотека драйвера ADBC, заданная только ссылкой на локальный файл. Допускаются три формы:

  Форма	Описание
  Имя файла без пути	Разрешается относительно каталога drivers_dir из adbc.conf. Имя должно соответствовать шаблону [A-Za-z0-9._-]+.so, при необходимости с суффиксом версии, например .so.1, и не должно содержать разделитель пути.
  URL вида file://	Не содержит компонента authority, строки запроса или фрагмента.
  Абсолютный путь	FE и каждый BE загружают библиотеку драйвера по этому пути.

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

• <connection_uri>

  Обязательный параметр. Строка подключения ADBC.

  Она должна явно указывать один удаленный Catalog, например postgresql://host:5432/mydb, поскольку Doris сопоставляет три уровня имен ADBC со своими двумя. Подробнее см. в разделе Сопоставление пространств имен.

• {DriverProperties}

  Раздел DriverProperties содержит необязательные свойства, управляющие загрузкой драйвера.

  Свойство	По умолчанию	Описание
  driver_checksum	Проверка не выполняется	MD5 файла библиотеки драйвера; проверяется при выполнении CREATE CATALOG.
  driver_entrypoint	Пустое значение	Символ точки входа драйвера. Если значение пустое, драйвер определяет его самостоятельно.

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

  предупреждение

  driver_checksum проверяет только копию на FE, но не копии на BE.

• {ConnectionProperties}

  Раздел ConnectionProperties содержит учетные данные для источника данных и диалект, используемый для формирования проталкиваемого SQL.

  Свойство	По умолчанию	Описание
  user	Не задано	Имя пользователя, передаваемое драйверу без изменений. Обязательность зависит от источника данных.
  password	Не задано	Пароль, передаваемый драйверу без изменений. Обязательность зависит от источника данных.
  sql_dialect	Определяется автоматически	Диалект, используемый для формирования проталкиваемого SQL. По умолчанию драйвер сообщает название поставщика источника данных, и Doris выбирает диалект на его основе. Если название не распознано, используется ansi.

  Задайте sql_dialect явно, если название поставщика, сообщаемое источником данных, не позволяет выбрать подходящий диалект или если его SQL не соответствует ожидаемому для этого названия. Встроены два диалекта:

  Значение	Описание
  ansi	Стандартный SQL. Используется по умолчанию, в том числе для нераспознанного источника данных.
  doris	Совпадает с ansi, за исключением того, что идентификаторы заключаются в обратные кавычки (`). Doris воспринимает имя в двойных кавычках как строковый литерал, поэтому SQL с кавычками ANSI вообще не разбирается источником данных Doris. Для источника данных, название поставщика которого начинается с doris без учета регистра, этот диалект выбирается автоматически.

• {ReadProperties}

  Раздел ReadProperties управляет параллельным чтением.

  Свойство	По умолчанию	Описание
  partitioned_read	auto	Режим параллельного чтения. Недопустимое значение вызывает ошибку вместо перехода к значению по умолчанию.
  max_partitions	1024	Максимальное число разделов, которое можно запланировать для одного сканирования.

  partitioned_read принимает три значения:

  Значение	Описание
  auto	Значение по умолчанию. Разделяет сканирование, если драйвер это поддерживает, а в противном случае выполняет чтение одним оператором.
  disabled	Никогда не запрашивает разделы. Такой запрос требует затрат: в источнике данных Arrow Flight SQL вызов, возвращающий разделы, и есть выполнение запроса, поэтому планирование требует дополнительного сетевого обращения, а источник данных начинает работу до того, как Doris окончательно решит выполнять запрос. Используйте это значение для возврата к чтению одним оператором, если для источника данных такие затраты слишком велики или если Doris не может прочитать возвращаемые им разделы.
  required	Сканирование должно быть разделено, иначе запрос завершается ошибкой с указанием причины. Используйте этот режим, если потеря параллелизма не должна оставаться незамеченной. В режиме auto драйвер, переставший разделять сканирование, по-прежнему обеспечивает успешное выполнение запроса, и результат никак не указывает на переход к резервному способу чтения.

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

• {DriverOptions}

  Раздел DriverOptions содержит параметры, которые передаются непосредственно драйверу и записываются с префиксом adbc..

  предупреждение

  Префикс является частью имени параметра и не удаляется. Собственные имена параметров ADBC уже начинаются с adbc., например adbc.snowflake.sql.db, поэтому в CREATE CATALOG нужно писать adbc.adbc.snowflake.sql.db.

  'adbc.adbc.snowflake.sql.db' = 'my_database'

• {CommonProperties}

  Раздел CommonProperties используется для задания общих свойств. См. раздел «Общие свойства» в обзоре Catalog.

  О свойствах кэша метаданных см. в разделе Кэш метаданных.

Примеры

Запросы к другому кластеру Doris

Чтение из другого кластера Doris через драйвер Arrow Flight SQL. uri указывает на порт Arrow Flight узла FE целевого кластера:

CREATE CATALOG remote_doris PROPERTIES (
    'type' = 'adbc',
    'driver_url' = 'libadbc_driver_flightsql.so',
    'uri' = 'grpc://remote-doris-fe:8070',
    'user' = 'root',
    'password' = '<password>'
);

SELECT id, name FROM remote_doris.some_db.some_table ORDER BY id LIMIT 10;

Здесь driver_url содержит имя файла без пути, которое разрешается относительно drivers_dir из adbc.conf.

Использование абсолютного пути и фиксация сборки драйвера

Укажите абсолютный путь к драйверу и зафиксируйте копию на FE с помощью driver_checksum:

CREATE CATALOG remote_source PROPERTIES (
    'type' = 'adbc',
    'driver_url' = '/opt/doris/adbc_drivers/libadbc_driver_flightsql.so',
    'driver_checksum' = 'd41d8cd98f00b204e9800998ecf8427e',
    'uri' = 'grpc+tls://remote-host:8070',
    'user' = 'analyst',
    'password' = '<password>'
);

Настройка диалекта и обязательного параллельного чтения

Используйте диалект doris для источника данных Doris и потребуйте разделения сканирования, чтобы потеря параллелизма не оставалась незамеченной:

CREATE CATALOG remote_doris_parallel PROPERTIES (
    'type' = 'adbc',
    'driver_url' = 'libadbc_driver_flightsql.so',
    'uri' = 'grpc://remote-doris-fe:8070',
    'user' = 'root',
    'password' = '<password>',
    'sql_dialect' = 'doris',
    'partitioned_read' = 'required',
    'max_partitions' = '256'
);

Отключение параллельного чтения

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

CREATE CATALOG remote_source_single PROPERTIES (
    'type' = 'adbc',
    'driver_url' = 'libadbc_driver_flightsql.so',
    'uri' = 'grpc://remote-host:8070',
    'user' = 'root',
    'password' = '<password>',
    'partitioned_read' = 'disabled'
);

Сопоставление пространств имен

ADBC использует трехуровневые имена объектов (Catalog / db_schema / таблица), а внешняя таблица Doris имеет двухуровневое имя (база данных / таблица). Самый внешний уровень имени уже занят созданным вами Catalog, поэтому один из удаленных уровней нужно исключить из имени:

• uri должен явно указывать один удаленный Catalog. Тогда изменяться может не более одного из двух удаленных уровней, и Doris не требуется объединять два имени в одно имя базы данных.
• Если удаленный db_schema не пуст, именем базы данных Doris становится этот db_schema. В противном случае используется имя удаленного Catalog.

Удаленные имена (Catalog, db_schema)	Имя базы данных Doris
mydb, public	public
mydb, пустое значение	mydb

Если источник данных сообщает об объекте, у которого нет ни имени Catalog, ни имени db_schema, Doris не может обратиться к нему как к базе данных и выдает ошибку.

Если uri не указывает конкретный удаленный Catalog, Doris сообщает об этом при выполнении CREATE CATALOG и предлагает указать имя удаленного Catalog в uri, например postgresql://host:5432/mydb, или через параметр драйвера. Некоторые драйверы не реализуют интерфейс, который Doris использует для этой проверки. Их Catalog принимаются с указанными настройками, а проблема проявляется при первом выполнении SHOW DATABASES.

Сопоставление типов столбцов

Doris сопоставляет типы Arrow, возвращаемые источником данных, со своими типами.

Тип Arrow	Тип Doris	Комментарий
bool	BOOLEAN
int8	TINYINT
int16	SMALLINT
int32	INT
int64	BIGINT
uint8	SMALLINT	Беззнаковые целые числа расширяются до следующего по размеру типа
uint16	INT	Беззнаковые целые числа расширяются до следующего по размеру типа
uint32	BIGINT	Беззнаковые целые числа расширяются до следующего по размеру типа
uint64	LARGEINT	Беззнаковые целые числа расширяются до следующего по размеру типа
float16, float32	FLOAT
float64	DOUBLE
decimal128(P,S)	DECIMAL(P,S)	Максимальная точность 38; при ее превышении столбец отклоняется
decimal256(P,S)	DECIMAL(P,S)	Максимальная точность 76; при ее превышении столбец отклоняется
date32(day)	DATE
date64(ms)	DATETIME(3)	date64 содержит время суток, которое было бы потеряно при преобразовании в DATE
timestamp(s) без часового пояса	DATETIME(0)
timestamp(ms) без часового пояса	DATETIME(3)
timestamp(us), timestamp(ns) без часового пояса	DATETIME(6)	Наносекундная точность усекается до микросекунд
timestamp с часовым поясом	TIMESTAMPTZ(0-6)	Действуют те же правила точности. Временная метка Arrow с часовым поясом задает конкретный момент времени, а при преобразовании в DATETIME часовой пояс был бы потерян
utf8, large_utf8, utf8_view	STRING
binary, large_binary, binary_view, fixed_size_binary	STRING	При работе с внешними таблицами в Doris нет универсального типа столбца для двоичных данных
list, large_list, fixed_size_list, list_view, large_list_view	ARRAY	Тип элемента сопоставляется рекурсивно
struct	STRUCT	Типы полей сопоставляются рекурсивно, а имена полей переводятся в нижний регистр
map	MAP	Типы ключей и значений сопоставляются рекурсивно
dictionary	Сопоставляется по типу значений словаря
run_end_encoded	Сопоставляется по типу значений
Другие	Не поддерживаются

примечание

• В Doris нет беззнаковых целочисленных типов, поэтому беззнаковый тип расширяется до следующего по размеру. uint32 сопоставляется с BIGINT, а не с INT, поскольку более узкий тип без предупреждения преобразовал бы каждое значение выше 2^31 в отрицательное число из-за переполнения.
• Если тип невозможно сопоставить, Doris выдает ошибку при описании таблицы и указывает имя столбца и его тип Arrow, вместо того чтобы использовать преобразование с потерей данных. Приведите тип столбца на стороне источника или исключите его из запроса.
• При чтении из источника данных Doris столбец IPV4 поступает как INT, поскольку обе стороны кодируют его как int32, а исходный столбец DATETIME поступает как TIMESTAMPTZ.

Операции с запросами

Базовый запрос

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

-- 1. switch to catalog, use database and query
SWITCH adbc_ctl;
USE adbc_db;
SELECT * FROM adbc_tbl LIMIT 10;

-- 2. use adbc database directly
USE adbc_ctl.adbc_db;
SELECT * FROM adbc_tbl LIMIT 10;

-- 3. use full qualified name to query
SELECT * FROM adbc_ctl.adbc_db.adbc_tbl LIMIT 10;

Операции с метаданными

SHOW DATABASES FROM adbc_ctl;

SHOW TABLES FROM adbc_ctl.adbc_db;

DESC adbc_ctl.adbc_db.adbc_tbl;

SHOW CREATE TABLE adbc_ctl.adbc_db.adbc_tbl;

Списки баз данных и таблиц всегда читаются непосредственно из источника, поэтому созданная в нем таблица видна без выполнения REFRESH. Схемы таблиц кэшируются; см. раздел Кэш метаданных.

примечание

Представления в источнике данных не включаются в список таблиц.

Интеграция данных

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

INSERT INTO internal.demo.local_tbl
SELECT * FROM adbc_ctl.adbc_db.adbc_tbl;

Также поддерживаются федеративные запросы с внутренними таблицами и таблицами в других Catalog, SELECT ... INTO OUTFILE и материализованные представления (MTMV), построенные на таблицах ADBC.

Отсечение столбцов

Doris запрашивает только те столбцы, которые нужны запросу. Неиспользуемые столбцы не включаются в формируемый удаленный SQL.

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

Следующие предикаты включаются в предложение WHERE удаленного SQL:

Категория	Поддерживаемые формы
Сравнение	=, !=, <, <=, >, >=
Проверки на NULL	IS NULL, IS NOT NULL
Множества	IN, NOT IN
Логические операторы	AND, OR, NOT над перечисленными выше предикатами

Вызовы функций, арифметические выражения, LIKE и BETWEEN не проталкиваются и обрабатываются в Doris.

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

Проталкивание LIMIT

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

Оптимизация COUNT(*)

COUNT(*) не читает данные столбцов из источника данных.

Просмотр сформированного удаленного SQL

EXPLAIN показывает оператор SQL, который фактически отправляется источнику данных:

EXPLAIN
SELECT id, name
FROM adbc_ctl.adbc_db.adbc_tbl
WHERE id > 100 AND name IS NOT NULL
LIMIT 10;

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

подсказка

Для источника данных Arrow Flight SQL вызов, запрашивающий разделы, сам по себе является выполнением запроса. Поэтому при запуске EXPLAIN для таблицы ADBC Doris не запрашивает разделы у источника данных, и источник фактически не выполняет запрос.

Параллельное чтение

Когда partitioned_read имеет значение auto (по умолчанию) или required, Doris просит драйвер разделить одно сканирование на несколько разделов результатов. Каждый раздел читается одним узлом BE, а узлы работают параллельно.

Если источник данных не может разделить сканирование:

• auto: выполняется переход к чтению одним оператором на одном узле BE.
• required: запрос завершается ошибкой с указанием причины.

Если число разделов превышает max_partitions, запрос завершается ошибкой.

Кэш метаданных

Чтобы ускорить доступ к внешнему источнику данных, Doris кэширует часть метаданных ADBC Catalog: результаты разрешения имен баз данных, результаты разрешения имен таблиц и схемы таблиц.

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

Настройка свойств кэша

Кэш метаданных ADBC Catalog настраивается с помощью унифицированных ключей meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}.

Свойство	По умолчанию	Значение
meta.cache.adbc.metadata.enable	true	Включен ли кэш метаданных.
meta.cache.adbc.metadata.ttl-second	600	0 отключает кэш; изменение вступает в силу немедленно и позволяет увидеть актуальные метаданные; -1 задает бессрочное хранение; другие положительные целые числа задают TTL в секундах, отсчитываемый от времени доступа.
meta.cache.adbc.metadata.capacity	1000	Максимальное число записей в кэше. 0 отключает кэш.

Условия работы: кэш активен только при enable=true, ttl-second != 0 и capacity > 0.

подсказка

TTL по умолчанию, равный 10 минутам, значительно меньше значения по умолчанию для других Catalog. Источник данных ADBC представляет собой другую работающую базу данных: другие пользователи могут в любой момент изменить ее таблицы с помощью DDL, и Doris не получает об этом уведомлений. Это значение ограничивает время, в течение которого пользователь, забывший выполнить REFRESH, продолжает видеть старую схему таблицы.

Модули кэша

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

Модуль (<entry>)	Префикс ключа свойства	Кэшируемые данные и влияние
metadata	meta.cache.adbc.metadata.	Кэширует результаты разрешения имен баз данных, результаты разрешения имен таблиц и схемы таблиц. Влияет на то, как скоро в Doris станут видны добавление или удаление столбца в источнике либо изменение его типа.

Обновление вручную

Каждый из этих операторов очищает кэш в своей области действия:

REFRESH CATALOG adbc_ctl;
REFRESH DATABASE adbc_ctl.adbc_db;
REFRESH TABLE adbc_ctl.adbc_db.adbc_tbl;

Рекомендации

• Доступ к актуальным метаданным в реальном времени: если нужно, чтобы каждый запрос читал текущую схему таблицы из источника данных, задайте для ttl-second значение 0:

  ALTER CATALOG adbc_ctl SET PROPERTIES ("meta.cache.adbc.metadata.ttl-second" = "0");

• Источники данных с часто меняющимися схемами: уменьшите ttl-second или выполните REFRESH, как только узнаете об изменении.

Наблюдаемость

Метрики кэша доступны в системной таблице information_schema.catalog_meta_cache_statistics:

SELECT catalog_name, engine_name, entry_name,
       effective_enabled, ttl_second, capacity,
       estimated_size, hit_rate, load_failure_count, last_error
FROM information_schema.catalog_meta_cache_statistics
WHERE catalog_name = 'adbc_ctl' AND engine_name = 'adbc'
ORDER BY entry_name;

Описание системной таблицы приведено в разделе catalog_meta_cache_statistics.

предупреждение

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

Ограничения

• Только чтение. INSERT, CREATE TABLE, DROP TABLE и другие операторы записи в источник данных отклоняются.
• Сбор статистики и проталкивание агрегации не поддерживаются.
• Представления в источнике данных не включаются в список таблиц.
• driver_checksum проверяет только копию драйвера на FE. Копии на BE не проверяются, а файлы на FE и BE не сравниваются между собой.
• driver_url принимает только ссылки на локальные файлы. Doris не скачивает драйвер по удаленному URL.
• При чтении из источника данных Doris столбец IPV4 поступает как INT, а исходный столбец DATETIME поступает как TIMESTAMPTZ.

Приложение

Часто задаваемые вопросы

Симптом или ошибка	Причина	Что делать
Driver file not found	FE не может найти файл драйвера по разрешенному пути.	Убедитесь, что файл, заданный именем без пути в driver_url, находится в каталоге drivers_dir из adbc.conf, а файл, заданный абсолютным путем или URL вида file://, существует и доступен для чтения на узле FE.
Driver path does not match any path allowed by driver_secure_path	Путь к драйверу не входит в список разрешенных в adbc.conf.	Переместите драйвер в разрешенный каталог или измените driver_secure_path и перезапустите FE.
scheme 'xxx' is not supported, only a local file is	В driver_url используется удаленная схема, например http://.	Драйвер ADBC не скачивается отдельно на каждый узел. Разместите файл драйвера на FE и всех BE, затем укажите его имя без пути, абсолютный путь или URL вида file://.
The ADBC source reports no current catalog, so 'uri' does not pin one	uri не указывает конкретный удаленный Catalog.	Укажите имя удаленного Catalog в uri, например postgresql://host:5432/mydb, или задайте его через параметр драйвера с префиксом adbc..
Запрос завершается ошибкой о том, что для типа Arrow одного из столбцов нет эквивалента в Doris	Тип этого столбца невозможно сопоставить.	Приведите его к поддерживаемому типу на стороне источника данных или исключите столбец из запроса вместо использования SELECT *.
Результаты запроса выглядят неверными, но ошибок нет	На FE и разных BE могут находиться разные сборки файла драйвера. ADBC описывает информацию о разделах во внутреннем формате драйвера, и разные реализации могут неверно читать данные друг друга без каких-либо ошибок.	Используйте driver_checksum, чтобы зафиксировать сборку на FE, и вручную сравните MD5 файла драйвера на каждом BE.
Удаленный SQL завершается синтаксической ошибкой	Диалект SQL источника данных не соответствует используемому.	Задайте sql_dialect явно, например 'sql_dialect' = 'doris' для источника данных Doris.