Обзор Catalog

Каталог данных (Catalog) описывает свойства источника данных.

В Doris можно создавать несколько каталогов данных, указывающих на разные источники данных, например Hive, Iceberg, Paimon и PostgreSQL. Через каталоги данных Doris автоматически получает из соответствующего источника сведения о базах данных, таблицах, схемах, партициях и расположении данных. Пользователи могут обращаться к этим каталогам для анализа данных с помощью стандартных операторов SQL и выполнять запросы с соединением данных из нескольких каталогов.

В Doris есть два типа каталогов данных:

Тип	Описание
Внутренний Catalog	Встроенный каталог данных с фиксированным именем internal, предназначенный для хранения данных внутренних таблиц Doris. Его нельзя создать, изменить или удалить.
Внешний Catalog	Внешние каталоги данных, то есть все каталоги, кроме внутреннего Catalog. Пользователи могут создавать, изменять и удалять внешние каталоги данных.

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

Сценарий	Описание
Ускорение запросов	Ускорение запросов непосредственно к данным lakehouse, например Hive, Iceberg, Paimon и др.
Интеграция данных	Подход ZeroETL для прямого доступа к разным источникам данных и получения результирующих данных либо удобной передачи данных между источниками.
Обратная запись данных	Обработка и преобразование данных в Doris с последующей записью во внешние источники данных.

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

Создание Catalog

Создайте Iceberg Catalog с помощью оператора CREATE CATALOG.

CREATE CATALOG iceberg_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hadoop',
    'warehouse' = 's3://bucket/dir/key',
    's3.endpoint' = 'https://s3.us-east-1.amazonaws.com',
    's3.access_key' = 'ak',
    's3.secret_key' = 'sk'
);

По сути, каталог данных, созданный в Doris, выступает посредником для доступа к службе метаданных, например Hive Metastore, и службе хранения, например HDFS/S3, соответствующего источника данных. Doris хранит только параметры подключения и другую информацию о каталоге данных, но не сами метаданные или данные соответствующего источника.

Общие свойства

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

Свойство	Описание	Пример
include_database_list	Задаёт несколько баз данных для синхронизации, разделённых символом ,. По умолчанию синхронизируются все базы данных. Имена баз данных чувствительны к регистру. Если во внешнем источнике много баз данных, но доступ нужен лишь к нескольким, этот параметр позволяет избежать синхронизации большого объёма метаданных.	'include_database_list' = 'db1,db2'
exclude_database_list	Задаёт несколько баз данных, которые нужно исключить из синхронизации, разделённых символом ,. По умолчанию фильтрация не применяется и синхронизируются все базы данных. Имена баз данных чувствительны к регистру. Применяется в том же сценарии, что и предыдущее свойство, но позволяет исключить базы данных, доступ к которым не нужен. При конфликте exclude имеет приоритет над include.	'exclude_database_list' = 'db1,db2'
include_table_list	Задаёт несколько таблиц для синхронизации в формате db.tbl, разделённых символом ,. Если свойство задано, при получении списка таблиц базы данных возвращаются только указанные таблицы без запроса полного списка из удалённой службы метаданных. Применяется, когда во внешнем источнике много таблиц и получение полного списка может завершиться по тайм-ауту.	'include_table_list' = 'db1.tbl1,db1.tbl2,db2.tbl3'
lower_case_table_names	Управляет обработкой регистра имён таблиц на уровне Catalog. Допустимые значения и их смысл см. ниже в разделе Чувствительность имён таблиц к регистру. По умолчанию наследуется значение глобальной переменной lower_case_table_names.	'lower_case_table_names' = '1'
lower_case_database_names	Управляет обработкой регистра имён баз данных на уровне Catalog. Допустимые значения и их смысл см. ниже в разделе Чувствительность имён баз данных к регистру. Значение по умолчанию: 0 (с учётом регистра).	'lower_case_database_names' = '2'

Указание списка таблиц

Эта функция поддерживается начиная с версии 4.1.0.

Если внешний источник данных, например Hive Metastore, содержит много таблиц, получение полного списка таблиц из удалённой службы метаданных может занимать очень много времени или даже завершаться по тайм-ауту. Свойство include_table_list позволяет указать таблицы для синхронизации и избежать получения полного списка таблиц из удалённого источника.

include_table_list использует формат db.tbl; несколько таблиц разделяются запятыми ,.

CREATE CATALOG hive_catalog PROPERTIES (
    'type' = 'hms',
    'hive.metastore.uris' = 'thrift://hms-host:9083',
    'include_table_list' = 'db1.table1,db1.table2,db2.table3'
);

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

• При получении списка таблиц в db1 возвращаются только table1 и table2, без вызова API удалённой службы метаданных для получения полного списка таблиц.
• При получении списка таблиц в db2 возвращается только table3.
• Для баз данных, не указанных в include_table_list, например db3, полный список таблиц по-прежнему запрашивается из удалённой службы метаданных.
• Записи в include_table_list с неверным форматом (не соответствующие формату db.tbl) игнорируются.

подсказка

Это свойство можно использовать вместе с include_database_list. Например, сначала отфильтровать нужные базы данных с помощью include_database_list, а затем дополнительно указать нужные таблицы с помощью include_table_list.

Чувствительность имён таблиц к регистру

Эта функция поддерживается начиная с версии 4.1.0.

Свойство lower_case_table_names позволяет управлять обработкой регистра имён таблиц на уровне Catalog. Оно поддерживает три режима:

Значение	Режим	Описание
0	С учётом регистра (по умолчанию)	Имена таблиц хранятся в исходном регистре и сравниваются с учётом регистра. При обращении к таблице регистр её имени должен точно совпадать с регистром в удалённых метаданных.
1	Хранение в нижнем регистре	Имена таблиц хранятся в Doris в нижнем регистре. Подходит для случаев, когда для доступа к внешним источникам данных нужно единообразно использовать имена таблиц в нижнем регистре.
2	Сравнение без учёта регистра	Имена таблиц сравниваются без учёта регистра, но при отображении сохраняется исходный регистр из удалённых метаданных. Подходит для случаев, когда во внешнем источнике данных имена таблиц имеют разный регистр и требуется обращаться к таблицам без учёта регистра.

Если свойство не задано, по умолчанию наследуется значение глобальной переменной lower_case_table_names.

CREATE CATALOG hive_catalog PROPERTIES (
    'type' = 'hms',
    'hive.metastore.uris' = 'thrift://hms-host:9083',
    'lower_case_table_names' = '2'
);

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

Если lower_case_table_names имеет значение 1 или 2, а в удалённых метаданных есть таблицы с именами, различающимися только регистром, например MyTable и mytable, возможны конфликты. Doris обнаруживает такие конфликты и сообщает об ошибке.

Чувствительность имён баз данных к регистру

Эта функция поддерживается начиная с версии 4.1.0.

Свойство lower_case_database_names позволяет управлять обработкой регистра имён баз данных на уровне Catalog. Оно поддерживает три режима:

Значение	Режим	Описание
0	С учётом регистра (по умолчанию)	Имена баз данных хранятся в исходном регистре и сравниваются с учётом регистра. При обращении к базе данных регистр её имени должен точно совпадать с регистром в удалённых метаданных.
1	Хранение в нижнем регистре	Имена баз данных хранятся в Doris в нижнем регистре. Подходит для случаев, когда для доступа к внешним источникам данных нужно единообразно использовать имена баз данных в нижнем регистре.
2	Сравнение без учёта регистра	Имена баз данных сравниваются без учёта регистра, но при отображении сохраняется исходный регистр из удалённых метаданных. Подходит для случаев, когда во внешнем источнике данных имена баз данных имеют разный регистр и требуется обращаться к базам данных без учёта регистра.

Значение по умолчанию: 0 (с учётом регистра).

CREATE CATALOG hive_catalog PROPERTIES (
    'type' = 'hms',
    'hive.metastore.uris' = 'thrift://hms-host:9083',
    'lower_case_database_names' = '2',
    'lower_case_table_names' = '2'
);

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

Если lower_case_database_names имеет значение 1 или 2, а в удалённых метаданных есть базы данных с именами, различающимися только регистром, например MyDB и mydb, возможны конфликты. Doris обнаруживает такие конфликты и сообщает об ошибке.

к сведению

lower_case_database_names и lower_case_table_names можно задавать независимо друг от друга. Например, для имён баз данных можно включить учёт регистра (0), а для имён таблиц отключить его (2).

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

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

Для внешних типов данных, которые пока нельзя сопоставить с типами столбцов Doris, например UNION, INTERVAL и др., Doris задаёт тип столбца UNSUPPORTED. Примеры запросов, затрагивающих типы UNSUPPORTED, приведены ниже.

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

k1 INT,
k2 INT,
k3 UNSUPPORTED,
k4 INT

Поведение запросов будет следующим:

SELECT * FROM table;                -- Error: Unsupported type 'UNSUPPORTED_TYPE' in 'k3'
SELECT * EXCEPT(k3) FROM table;     -- Query OK.
SELECT k1, k3 FROM table;           -- Error: Unsupported type 'UNSUPPORTED_TYPE' in 'k3'
SELECT k1, k4 FROM table;           -- Query OK.

Свойство Nullable

В настоящее время поддержка свойства Nullable для столбцов внешних таблиц в Doris имеет определённые ограничения. Поведение описано ниже:

Тип в источнике	Поведение Doris при чтении	Поведение Doris при записи
Nullable	Nullable	Разрешена запись значений Null
Not Null	Nullable, то есть столбец всё равно читается как допускающий NULL	Разрешена запись значений Null, то есть строгая проверка значений Null не выполняется. Пользователи должны самостоятельно обеспечивать целостность и согласованность данных.

Использование Catalog

Просмотр Catalog

После создания каталог можно просмотреть с помощью команды SHOW CATALOGS:

mysql> SHOW CATALOGS;
+-----------+-----------------+----------+-----------+-------------------------+---------------------+------------------------+
| CatalogId | CatalogName     | Type     | IsCurrent | CreateTime              | LastUpdateTime      | Comment                |
+-----------+-----------------+----------+-----------+-------------------------+---------------------+------------------------+
|     10024 | iceberg_catalog | iceberg  | yes       | 2023-12-25 16:11:41.687 | 2023-12-25 20:43:18 | NULL                   |
|         0 | internal        | internal |           | NULL                    | NULL                | Doris internal catalog |
+-----------+-----------------+----------+-----------+-------------------------+---------------------+------------------------+

Оператор CREATE CATALOG можно просмотреть с помощью SHOW CREATE CATALOG.

Переключение между Catalog

В Doris оператор SWITCH переключает контекст сеанса подключения на соответствующий каталог данных, аналогично тому, как оператор USE переключает базу данных.

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

SWITCH iceberg_catalog;

SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| test               |
| iceberg_db         |
+--------------------+

USE iceberg_db;

Также можно использовать оператор USE с полным именем catalog_name.database_name, чтобы сразу перейти к конкретной базе данных в определённом каталоге данных:

USE iceberg_catalog.iceberg_db;

Полное имя также можно указывать в командной строке MySQL или строках подключения JDBC для совместимости с протоколом подключения MySQL.

# Command line tool
mysql -h host -P9030 -uroot -Diceberg_catalog.iceberg_db

# JDBC url
jdbc:mysql://host:9030/iceberg_catalog.iceberg_db

Встроенный каталог данных имеет фиксированное имя internal. Переключение на него выполняется так же, как на внешние каталоги данных.

Catalog по умолчанию

Свойство пользователя default_init_catalog позволяет задать каталог данных по умолчанию для конкретного пользователя. После настройки при подключении этого пользователя к Doris сеанс автоматически переключается на указанный каталог данных.

SET PROPERTY default_init_catalog=hive_catalog;

Примечание 1: если каталог данных явно указан в командной строке MySQL или строке подключения JDBC, он имеет приоритет, а свойство пользователя default_init_catalog не применяется.

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

Примечание 3: эта функция поддерживается начиная с версии 3.1.x.

Простые запросы

К таблицам во внешних каталогах данных можно обращаться с помощью любого оператора SQL, поддерживаемого Doris.

SELECT id, SUM(cost) FROM iceberg_db.table1
GROUP BY id ORDER BY id;

Запросы к нескольким Catalog

Doris поддерживает запросы с соединением данных из разных каталогов.

Создадим ещё один каталог MySQL Catalog:

CREATE CATALOG mysql_catalog properties(
    'type' = 'jdbc',
    'user' = 'root',
    'password' = '123456',
    'jdbc_url' = 'jdbc:mysql://host:3306/mysql_db',
    'driver_url' = 'mysql-connector-java-8.0.25.jar',
    'driver_class' = 'com.mysql.cj.jdbc.Driver'
);

Затем выполним с помощью SQL запрос с соединением таблицы Iceberg и таблицы MySQL:

SELECT * FROM
iceberg_catalog.iceberg_db.table1 tbl1 JOIN mysql_catalog.mysql_db.dim_table tbl2
ON tbl1.id = tbl2.id;

Загрузка данных

С помощью команды INSERT можно импортировать данные из источников данных в Doris.

INSERT INTO internal.doris_db.tbl1
SELECT * FROM iceberg_catalog.iceberg_db.table1;

Также можно использовать оператор CTAS (Create Table As Select), чтобы создать внутреннюю таблицу Doris на основе внешнего источника данных и импортировать в неё данные:

CREATE TABLE internal.doris_db.tbl1
PROPERTIES('replication_num' = '1')
AS
SELECT * FROM iceberg_catalog.iceberg_db.table1;

Обратная запись данных

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

• Hive Catalog

• Iceberg Catalog

• JDBC Catalog

Обновление Catalog

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

-- Refresh catalog
REFRESH CATALOG catalog_name;

-- Refresh specified database
REFRESH DATABASE catalog_name.db_name;

-- Refresh specified table
REFRESH TABLE catalog_name.db_name.table_name;

Doris также позволяет отключить кэширование метаданных, чтобы получать актуальные метаданные в реальном времени.

• Для версий до Doris 4.1.x см. Кэш метаданных.
• Для Doris 4.1.x и более поздних версий см. раздел «Кэш метаданных» в документации каждого Catalog.
  • Hive Catalog
  • Iceberg Catalog
  • Hudi Catalog
  • Paimon Catalog
  • MaxCompute Catalog

Изменение Catalog

Свойства или имя каталога данных можно изменить с помощью ALTER CATALOG:

-- Rename a catalog
ALTER CATALOG iceberg_catalog RENAME iceberg_catalog2;

-- Modify properties of a catalog
ALTER CATALOG iceberg_catalog SET PROPERTIES ('key1' = 'value1' [, 'key' = 'value2']); 

-- Modify the comment of a catalog
ALTER CATALOG iceberg_catalog MODIFY COMMENT 'my iceberg catalog';

Удаление Catalog

Указанный внешний каталог данных можно удалить с помощью DROP CATALOG.

DROP CATALOG [IF EXISTS] iceberg_catalog;

Удаление внешнего каталога данных из Doris не приводит к удалению самих данных. Удаляется только сопоставление каталога данных, хранящееся в Doris.

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

Управление правами доступа к базам данных и таблицам во внешних каталогах данных выполняется так же, как для внутренних таблиц. Подробности см. в документации Аутентификация и авторизация.

Проверка партиционирования внешних таблиц (начиная с 4.1.5)

Начиная с 4.1.5, при создании внешней таблицы перед преобразованием определения партиционирования проверяется модель партиционирования Catalog:

Catalog	Поддерживаемое определение	Неподдерживаемое определение
Hive	PARTITION BY LIST с использованием имён существующих столбцов	RANGE, выражения партиционирования и явно заданные значения партиций
Paimon / MaxCompute	Ключи партиционирования, заданные именами столбцов	Выражения с функциями партиционирования и явно заданные значения партиций
Iceberg	Поддерживаемые определения партиционирования по столбцам или преобразованиям	Явно заданные значения партиций в синтаксисе внутренних таблиц Doris

Не используйте для внешних таблиц определения внутренних таблиц, в которых перечислены значения партиций. Например, Hive создаёт партиции на основе записываемых данных, поэтому заранее указывать VALUES IN (...) не требуется.