ファイル外部テーブル
ファイル外部テーブルは、特別なタイプの外部テーブルです。データを StarRocks にロードすることなく、外部ストレージシステム内の Parquet および ORC データファイルを直接クエリできます。さらに、ファイル外部テーブルはメタストアに依存しません。現在のバージョンでは、StarRocks は次の外部スト レージシステムをサポートしています: HDFS、Amazon S3、およびその他の S3 互換ストレージシステム。
この機能は StarRocks v2.5 からサポートされています。
- v3.1 以降、StarRocks は INSERT コマンドと FILES 関数を使用してクラウドストレージ上のファイルから直接データをロードすることをサポートしており、最初に external catalog またはファイル外部テーブルを作成する必要はありません。さらに、FILES() はファイルのテーブルスキーマを自動的に推測でき、データロードのプロセスを大幅に簡素化します。
- ファイル外部テーブル機能は、StarRocks にデータをロードするために設計されており、通常の操作として外部システムに対して効率的なクエリを実行するためのものではありません。よりパフォーマンスの高いソリューションは、データを StarRocks にロードすることです。
制限事項
- ファイル外部テーブルは、default_catalog 内のデータベースに作成する必要があります。クラスター内に作成されたカタログをクエリするには、SHOW CATALOGS を実行できます。
- Parquet、ORC、Avro、RCFile、および SequenceFile データファイルのみがサポートされています。
- ファイル外部テーブルを使用してターゲットデータファイルのデータをクエリすることのみが可能です。INSERT、DELETE、DROP などのデータ書き込み操作はサポートされていません。
前提条件
ファイル外部テーブルを作成する前に、ターゲットデータファイルが保存されている外部ストレージシステムに StarRocks がアクセスできるように、StarRocks クラスターを構成する必要があります。ファイル外部テーブルに必要な構成は、Hive catalog に必要な構成と同じですが、メタストアを構成する必要はありません。構成の詳細については、Hive catalog - 統合準備 を参照してください。
データベースの作成 (オプション)
StarRocks クラスターに接続した後、既存のデータベースにファイル外部テーブルを作成するか、ファイル外部テーブルを管理するための新しいデータベースを作成できます。クラスター内の既存のデータベースをクエリするには、SHOW DATABASES を実行します。その後、USE <db_name> を実行してターゲットデータベースに切り替えることができます。
データベースを作成するための構文は次のとおりです。
CREATE DATABASE [IF NOT EXISTS] <db_name>
ファイル外部テーブルの作成
ターゲットデータベースにアクセスした後、このデータベースにファイル外部テーブルを作成できます。
構文
CREATE EXTERNAL TABLE <table_name>
(
<col_name> <col_type> [NULL | NOT NULL] [COMMENT "<comment>"]
)
ENGINE=file
COMMENT ["comment"]
PROPERTIES
(
FileLayoutParams,
StorageCredentialParams
)
パラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
| table_name | はい | ファイル外部テーブルの名前。命名規則は次のとおりです:
|
| col_name | はい | ファイル外部テーブルの列名。ファイル外部テーブルの列名はターゲットデータファイルの列名と同じである必要がありますが、大文字と小文字は区別されません。ファイル外部テーブルの列の順序はターゲットデータファイルの順序と異なる場合があります。 |
| col_type | はい | ファイル外部テーブルの列タイプ。このパラメータは、ターゲットデータファイルの列タイプに基づいて指定する必要があります。詳細については、列タイプのマッピング を参照してください。 |
| NULL | NOT NULL | いいえ | ファイル外部テーブルの列が NULL を許可するかどうか。
|
| comment | いいえ | ファイル外部テーブルの列のコメント。 |
| ENGINE | はい | エンジンのタイプ。値を file に設定します。 |
| comment | いいえ | ファイル外部テーブルの説明。 |
| PROPERTIES | はい |
|
FileLayoutParams
ターゲットデータファイルにアクセスするための一連のパラメータ。
"path" = "<file_path>",
"format" = "<file_format>"
"enable_recursive_listing" = "{ true | false }"
"enable_wildcards" = "{ true | false }"
| パラメータ | 必須 | 説明 |
|---|---|---|
| path | はい | データファイルのパス。
|
| format | はい | データファイルの形式。有効な値: parquet, orc, avro, rctext または rcbinary, sequence。 |
| enable_recursive_listing | いいえ | 現在のパス下のすべてのファイルを再帰的にトラバースするかどうかを指定します。デフォルト値: true。値 true はサブディレクトリを再帰的にリストすることを指定し、値 false はサブディレクトリを無視することを指定します。 |
| enable_wildcards | いいえ | path でワイルドカード (*) を使用することをサポートするかどうか。デフォルト値: false。例: 2024-07-* は 2024-07- プレフィックスを持つすべてのファイルに一致します。このパラメータは v3.1.9 からサポートされています。 |
StorageCredentialParams (オプション)
ターゲットストレージシステムと StarRocks が統合する方法に関する一連のパラメータ。このパラメータセットは オプション です。
ターゲットストレージシステムが AWS S3 またはその他の S3 互換ストレージである場合にのみ StorageCredentialParams を構成する必要があります。
その他のストレージシステムの場合、StorageCredentialParams を無視できます。
AWS S3
AWS S3 に保存されているデータファイルにアクセスする必要がある場合、StorageCredentialParams に次の認証パラメータを構成します。
- インスタンスプロファイルベースの認証方法を選択した場合、
StorageCredentialParamsを次のように構成します:
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "<aws_s3_region>"
- 想定ロールベースの認証方法を選択した場合、
StorageCredentialParamsを次のように構成します:
"aws.s3.use_instance_profile" = "true",
"aws.s3.iam_role_arn" = "<ARN of your assumed role>",
"aws.s3.region" = "<aws_s3_region>"
- IAM ユーザーベースの認証方法を選択した場合、
StorageCredentialParamsを次のように構成します:
"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>",
"aws.s3.region" = "<aws_s3_region>"
| パラメータ名 | 必須 | 説明 |
|---|---|---|
| aws.s3.use_instance_profile | はい | AWS S3 にアクセスする際にインスタンスプロファイルベースの認証方法と想定ロールベースの認証方法を有効にするかどうか を指定します。有効な値: true および false。デフォルト値: false。 |
| aws.s3.iam_role_arn | はい | AWS S3 バケットに対する権限を持つ IAM ロールの ARN。 想定ロールベースの認証方法を使用して AWS S3 にアクセスする場合、このパラメータを指定する必要があります。その後、StarRocks はターゲットデータファイルにアクセスする際にこのロールを想定します。 |
| aws.s3.region | はい | AWS S3 バケットが存在するリージョン。例: us-west-1。 |
| aws.s3.access_key | いいえ | IAM ユーザーのアクセスキー。IAM ユーザーベースの認証方法を使用して AWS S3 にアクセスする場合、このパラメータを指定する必要があります。 |
| aws.s3.secret_key | いいえ | IAM ユーザーのシークレットキー。IAM ユーザーベースの認証方法を使用して AWS S3 にアクセスする場合、このパラメータを指定する必要があります。 |
AWS S3 にアクセスするための認証方法の選択方法および AWS IAM コンソールでのアクセス制御ポリシーの構成方法については、AWS S3 へのアクセスのための認証パラメータ を参照してください。
S3 互換ストレージ
MinIO などの S3 互換ストレージシステムにアクセスする必要がある場合、StorageCredentialParams を次のよう に構成して、統合を成功させます:
"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"
次の表は、StorageCredentialParams に構成する必要があるパラメータを説明しています。
| パラメータ | 必須 | 説明 |
|---|---|---|
| aws.s3.enable_ssl | はい | SSL 接続を有効にするかどうかを指定します。 有効な値: true および false。デフォルト値: true。 |
| aws.s3.enable_path_style_access | はい | パススタイルアクセスを有効にするかどうかを指定します。 有効な値: true および false。デフォルト値: false。MinIO の場合、値を true に設定する必要があります。パススタイルの URL は次の形式を使用します: https://s3.<region_code>.amazonaws.com/<bucket_name>/<key_name>。たとえば、US West (オレゴン) リージョンに DOC-EXAMPLE-BUCKET1 というバケットを作成し、そのバケット内の alice.jpg オブジェクトにアクセスしたい場合、次のパススタイルの URL を使用できます: https://s3.us-west-2.amazonaws.com/DOC-EXAMPLE-BUCKET1/alice.jpg。 |
| aws.s3.endpoint | はい | AWS S3 の 代わりに S3 互換ストレージシステムに接続するために使用されるエンドポイント。 |
| aws.s3.access_key | はい | IAM ユーザーのアクセスキー。 |
| aws.s3.secret_key | はい | IAM ユーザーのシークレットキー。 |
列タイプのマッピング
次の表は、ターゲットデータファイルとファイル外部テーブル間の列タイプのマッピングを示しています。
| データファイル | ファイル外部テーブル |
|---|---|
| INT/INTEGER | INT |
| BIGINT | BIGINT |
| TIMESTAMP | DATETIME。 TIMESTAMP は現在のセッションのタイムゾーン設定に基づいてタイムゾーンなしの DATETIME に変換され、精度が一部失われることに注意してください。 |
| STRING | STRING |
| VARCHAR | VARCHAR |
| CHAR | CHAR |
| DOUBLE | DOUBLE |
| FLOAT | FLOAT |
| DECIMAL | DECIMAL |
| BOOLEAN | BOOLEAN |
| ARRAY | ARRAY |
| MAP | MAP |
| STRUCT | STRUCT |
例
HDFS
HDFS パスに保存されている Parquet データファイルをクエリするために t0 という名前のファイル外部テーブルを作成します。
USE db_example;
CREATE EXTERNAL TABLE t0
(
name string,
id int
)
ENGINE=file
PROPERTIES
(
"path"="hdfs://x.x.x.x:8020/user/hive/warehouse/person_parq/",
"format"="parquet"
);
AWS S3
例 1: ファイル外部テーブルを作成し、AWS S3 内の 単一の Parquet ファイル にアクセスするために インスタンスプロファイル を使用します。
USE db_example;
CREATE EXTERNAL TABLE table_1
(
name string,
id int
)
ENGINE=file
PROPERTIES
(
"path" = "s3://bucket-test/folder1/raw_0.parquet",
"format" = "parquet",
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "us-west-2"
);
例 2: ファイル外部テーブルを作成し、AWS S3 内のターゲットファイルパス下の すべての ORC ファイル にアクセスするために 想定ロール を使用します。
USE db_example;
CREATE EXTERNAL TABLE table_1
(
name string,
id int
)
ENGINE=file
PROPERTIES
(
"path" = "s3://bucket-test/folder1/",
"format" = "orc",
"aws.s3.use_instance_profile" = "true",
"aws.s3.iam_role_arn" = "arn:aws:iam::51234343412:role/role_name_in_aws_iam",
"aws.s3.region" = "us-west-2"
);
例 3: ファイル外部テーブルを作成し、AWS S3 内のファイルパス下の すべての ORC ファイル にアクセスするために IAM ユーザー を使用します。
USE db_example;
CREATE EXTERNAL TABLE table_1
(
name string,
id int
)
ENGINE=file
PROPERTIES
(
"path" = "s3://bucket-test/folder1/",
"format" = "orc",
"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_access_key>",
"aws.s3.region" = "us-west-2"
);
ファイル外部テーブルをクエリする
構文:
SELECT <clause> FROM <file_external_table>
例えば、例 - HDFS で作成したファイル外部テーブル t0 からデータをクエリするには、次のコマンドを実行します:
SELECT * FROM t0;
+--------+------+
| name | id |
+--------+------+
| jack | 2 |
| lily | 1 |
+--------+------+
2 rows in set (0.08 sec)
ファイル外部テーブルを管理する
DESC を使用してテーブルのスキーマを表示したり、DROP TABLE を使用してテーブルを削除したりできます。
