バージョン: 4.x

データカタログ概要

Data Catalogはデータソースのプロパティを記述します。

Dorisでは、異なるデータソース（Hive、Iceberg、Paimon、PostgreSQLなど）を指す複数のdata catalogを作成できます。Dorisは、data catalogを通じて対応するデータソースからデータベース、テーブル、スキーマ、パーティション、およびデータの場所を自動的に取得します。ユーザーは標準のSQL文を使用してこれらのdata catalogにアクセスしてデータ分析を行い、複数のdata catalog間のデータを結合したクエリを実行できます。

Dorisには2種類のdata catalogがあります：

タイプ	説明
Internal Catalog	`internal`という固定名を持つ組み込みdata catalogで、Doris内部テーブルデータを格納するために使用されます。作成、変更、削除はできません。
External Catalog	外部data catalogで、Internal Catalog以外のすべてのdata catalogを指します。ユーザーは外部data catalogを作成、変更、削除できます。

Data catalogは主に以下の3種類のシナリオに適用されますが、異なるdata catalogには異なる適用シナリオがあります。詳細については、対応するdata catalogのドキュメントを参照してください。

シナリオ	説明
Query Acceleration	Hive、Iceberg、Paimonなどのlakehouseデータに対するクエリを直接高速化します。
Data Integration	ZeroETLアプローチで異なるデータソースに直接アクセスして結果データを生成するか、異なるデータソース間での便利なデータフローを可能にします。
Data Write-Back	Dorisを通じてデータを処理・変換し、外部データソースに書き戻します。

この記事では、Iceberg Catalogを例として、data catalogの基本操作を紹介します。異なるdata catalogの詳細な説明については、対応するdata catalogのドキュメントを参照してください。

Data Catalogの作成

CREATE CATALOG文を使用してIceberg 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は、データカタログの接続プロパティやその他の情報のみを保存し、対応するデータソースの実際のメタデータやデータは保存しません。

Common Properties

各データカタログ固有のプロパティセットに加えて、このセクションでは、すべてのデータカタログで共有される共通プロパティ{CommonProperties}について説明します。

Property	Description	Example
`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`	カタログレベルのテーブル名の大文字小文字制御。値とその意味については、以下のTable Name Case Sensitivityセクションを参照してください。デフォルト値はグローバル変数`lower_case_table_names`から継承されます。	`'lower_case_table_names' = '1'`
`lower_case_database_names`	カタログレベルのデータベース名の大文字小文字制御。値とその意味については、以下のDatabase Name Case Sensitivityセクションを参照してください。デフォルト値は`0`（大文字小文字を区別）です。	`'lower_case_database_names' = '2'`

Specifying Table List

この機能はバージョン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配下のテーブル一覧表示時、リモートメタデータサービスの完全テーブル一覧APIを呼び出すことなく、table1とtable2のみが返されます。
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レベルでテーブル名の大文字小文字の処理を制御できます。このプロパティは3つのモードをサポートします:

値	モード	説明
`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レベルでデータベース名の大文字小文字の処理を制御できます。このプロパティは3つのモードをサポートしています：

値	モード	説明
`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 Property

Dorisは現在、外部テーブルカラムのNullableプロパティサポートに特別な制限があります。具体的な動作は以下の通りです：

Source Type	Doris Read Behavior	Doris Write Behavior
Nullable	Nullable	Null値の書き込みを許可
Not Null	Nullable、つまり、依然としてNULLを許可するカラムとして読み取られる	Null値の書き込みを許可、つまり、Null値に対する厳密なチェックなし。ユーザーは自身でデータの整合性と一貫性を確保する必要があります。

Data Catalogsの使用

Data Catalogsの表示

作成後、SHOW CATALOGSコマンドを使用してcatalogを表示できます：

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を使用できます。

データカタログの切り替え

Dorisは、接続セッションコンテキストを対応するデータカタログに切り替えるためのSWITCH文を提供しており、これはUSE文を使用してデータベースを切り替えるのと同様です。

データカタログに切り替えた後、USE文を使用して特定のデータベースにさらに切り替えたり、SHOW DATABASESを使用して現在のデータカタログ下のデータベースを表示したりできます。

SWITCH iceberg_catalog;

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

USE iceberg_db;

完全修飾名 catalog_name.database_name を使用した USE 文を使って、特定のデータカタログ下の特定のデータベースに直接切り替えることもできます：

USE iceberg_catalog.iceberg_db;

完全修飾名はMySQL command lineや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という固定名を持ちます。切り替え方法は外部データカタログと同じです。

デフォルトデータカタログ

ユーザープロパティdefault_init_catalogを使用して、特定のユーザーのデフォルトデータカタログを設定します。設定すると、指定されたユーザーがDorisに接続した際に、セッションは自動的に設定されたデータカタログに切り替わります。

SET PROPERTY default_init_catalog=hive_catalog;

注記 1: MySQLコマンドラインまたはJDBC接続文字列でdata catalogが明示的に指定されている場合、指定されたものが優先され、default_init_catalogユーザープロパティは効果を持ちません。

注記 2: ユーザープロパティdefault_init_catalogによって設定されたdata catalogがもう存在しない場合、セッションは自動的にデフォルトのinternal data catalogに切り替わります。

注記 3: この機能はバージョン3.1.x以降で利用可能です。

Simple Queries

Dorisでサポートされている任意のSQL文を使用して、外部data catalog内のテーブルをクエリできます。

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

Cross-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テーブル間でjoinクエリを実行します：

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;

外部データソースからDoris内部テーブルを作成してデータをインポートするために、CTAS (Create Table As Select)文を使用することもできます：

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

データ書き戻し

DorisはINSERT文を使用して、外部データソースに直接データを書き戻すことをサポートしています。詳細については、以下を参照してください：

データカタログの更新

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は、最新のメタデータへのリアルタイムアクセスを可能にするため、メタデータキャッシュの無効化もサポートしています。

メタデータキャッシュの詳細情報と設定については、次を参照してください：Metadata Cache

データカタログの変更

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';

データカタログの削除

DROP CATALOGを使用して、指定された外部データカタログを削除できます。

DROP CATALOG [IF EXISTS] iceberg_catalog;

DorisからEXTERNAL DATA CATALOGを削除しても、実際のデータは削除されません。Dorisに保存されているDATA CATALOGマッピングのみが削除されます。

権限管理

EXTERNAL DATA CATALOG内のデータベースとテーブルの権限管理は、内部テーブルと同じです。詳細については、認証と認可のドキュメントを参照してください。

Data Catalogの作成​

Common Properties​

Specifying Table List​

テーブル名の大文字小文字の区別​

データベース名の大文字小文字の区別​

カラム型マッピング​

Nullable Property​

Data Catalogsの使用​

Data Catalogsの表示​

データカタログの切り替え​

デフォルトデータカタログ​

Simple Queries​

Cross-Catalog クエリ​

データ取り込み​

データ書き戻し​

データカタログの更新​

データカタログの変更​

データカタログの削除​

権限管理​

Data Catalogの作成

Common Properties

Specifying Table List

テーブル名の大文字小文字の区別

データベース名の大文字小文字の区別

カラム型マッピング

Nullable Property

Data Catalogsの使用

Data Catalogsの表示

データカタログの切り替え

デフォルトデータカタログ

Simple Queries

Cross-Catalog クエリ

データ取り込み

データ書き戻し

データカタログの更新

データカタログの変更

データカタログの削除

権限管理