File external table
File external table
ファイル外部テーブルは、外部ストレージシステムに保存されたParquetおよびORCデータファイルをロードせずにStarRocksで直接クエリを実行できる特別な外部テーブルです。また、ファイル外部テ ーブルはメタストアに依存しません。現在のバージョンでは、StarRocksは次の外部ストレージシステムをサポートしています：HDFS、Amazon S3、およびその他のS3互換のストレージシステム。
この機能はStarRocks v2.5からサポートされています。
制限事項
- ファイル外部テーブルは、default_catalog内のデータベースに作成する必要があります。クラスタで作成されたカタログをクエリするには、SHOW CATALOGSを実行できます。
- ParquetおよびORCデータファイルのみがサポートされています。
- ファイル外部テーブルを使用してターゲットデータファイルのデータをクエリすることができますが、INSERT、DELETE、およびDROPのようなデータ書き込み操作はサポートされていません。
前提条件
ファイル外部テーブルを作成する前に、StarRocksクラスタを構成し、StarRocksがターゲットデータファイルが保存されている外部ストレージシステムにアクセスできるようにする必要があります。ファイル外部テーブルに必要な設定は、Hiveカタログに必要な設定と同じですが、メタストアを構成する必要はありません。設定についての詳細は、Hiveカタログ - 統合の準備を参照してください。
データベースを作成する（オプション）
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 | Yes | ファイル外部テーブルの名前です。次の命名規則に従う必要があります：
|
col_name | Yes | ファイル外部テーブルの列名です。ファイル外部テーブルの列名は、ターゲットのデータファイルと同じである必要がありますが、大文字と小文字は区別されません。ファイル外部テーブルの列の順序は、ターゲットのデータファイルと異なる場合があります。 |
col_type | Yes | ファイル外部テーブルの列の型です。このパラメータは、ターゲットのデータファイルの列の型に基づいて指定する必要があります。詳細については、 列の型のマッピング を参照してください。 |
NULL | NOT NULL | No | ファイル外部テーブルの列にNULLを許可するかどうかを指定します。
次のルールに基づいて、この修飾子を指定する必要があります：
|
comment | No | ファイル外部テーブルの列のコメントです。 |
ENGINE | Yes | エンジンのタイプです。値をfileに設定します。 |
comment | No | ファイル外部テーブルの説明です。 |
PROPERTIES | Yes |
|
FileLayoutParams
ターゲットデータファイルにアクセスするためのパラメータセットです。
"path" = "<file_path>",
"format" = "<file_format>"
"enable_recursive_listing" = "{ true | false }"
パラメータ | 必須 | 説明 |
|---|---|---|
path | Yes | データファイルのパスです。
パスを入力する際には、次のルールに注意してください：
|
format | Yes | データファイルのフォーマットです。ParquetおよびORCがサポートされています。 |
enable_recursive_listing | No | 現在のパスの下のすべてのファイルを再帰的に走査するかどうかを指定します。デフォルト値：false。 |
StorageCredentialParams（オプション）
ターゲットストレージシステムとの統合に関するパラメータセットです。このパラメータセットはオプションです。
ターゲットストレージシステムが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" = "<Amazonリソースネーム（ARN）のアサームドロール>",
"aws.s3.region" = "<aws_s3_region>"
- IAMユーザーベースの認証方法を選択する場合、
StorageCredentialParamsを次のように設定します：
"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<IAMユーザーのアクセスキー>",
"aws.s3.secret_key" = "<IAMユーザーのシークレットキー>",
"aws.s3.region" = "<aws_s3_region>"
パラメータ名 | 必須 | 説明 |
|---|---|---|
aws.s3.use_instance_profile | Yes | AWS S3にアクセスする際にインスタンスプロファイルベースの認証方法とアサームドロールベースの認証方法を有効にするかどうかを指定します。有効な値は |
aws.s3.iam_role_arn | Yes | AWS S3バケットに特権を持つIAMロールのARNです。 AWS S3へのアクセスにアサームドロールベースの認証方法を使用する場合、このパラメータを指定する必要があります。その後、StarRocksはこのロールを使用してターゲットデータファイルにアクセスします。 |
aws.s3.region | Yes | AWS S3バケットが存在するリージョンです。例：us-west-1。 |
aws.s3.access_key | No | IAMユーザーのアクセスキーです。IAMユーザーベースの認証方法を使用してAWS S3にアクセスする場合、このパラメータを指定する必要があります。 |
aws.s3.secret_key | No | IAMユーザーのシークレットキーです。IAMユーザーベースの認証方法を使用してAWS S3にアクセスする場合、このパラメータを指定する必要があります。 |
AWS S3へのアクセスの認証方法とAWS IAMコンソールでアクセス制御ポリシーを構成する方法の詳細については、「AWS S3へのアクセスの認証パラメータ」を参照してください。
S3互換のストレージ
MinIOなどのS3互換のストレージシステ ムにアクセスする必要がある場合は、StarRocksが正常に統合されるように、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 | Yes | SSL接続を有効にするかどうかを指定します。 有効な値： |
aws.s3.enable_path_style_access | Yes | パススタイルのアクセスを有効にするかどうかを指定します。 有効な値： パススタイルのURLは次の形式を使用します： たとえば、『US West（Oregon）』リージョンに『DOC-EXAMPLE-BUCKET1』という名前のバケットを作成し、このバケット内の |
aws.s3.endpoint | Yes | AWS S3ではなくS3互換のストレージシステムに接続するために使用されるエンドポイントです。 |
aws.s3.access_key | Yes | IAMユーザーのアクセスキーです。 |
aws.s3.secret_key | Yes | 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を使用してテーブルを削除できます。