バージョン: 4.x

SELECT INTO OUTFILE

このドキュメントでは、クエリ結果のエクスポート操作を実行するためのSELECT INTO OUTFILEコマンドの使用方法を紹介します。

SELECT INTO OUTFILEコマンドは、SELECT部分の結果データを指定されたファイル形式でターゲットストレージシステム（オブジェクトストレージやHDFSを含む）にエクスポートします。

SELECT INTO OUTFILEは同期コマンドで、コマンドの復帰はエクスポートが完了したことを意味します。エクスポートが成功した場合、エクスポートされたファイルの数、サイズ、パスなどの情報が返されます。エクスポートが失敗した場合、エラー情報が返されます。

SELECT INTO OUTFILEとEXPORTのどちらを選択するかについては、Export 概要を参照してください。

SELECT INTO OUTFILEコマンドの詳細な説明については、以下を参照してください：SELECT INTO OUTFILE

適用シナリオ

SELECT INTO OUTFILEは以下のシナリオに適用されます：

エクスポートされるデータが、フィルタリング、集計、結合などの複雑な計算ロジックを経る必要がある場合
同期タスクを実行する必要があるシナリオに適している

SELECT INTO OUTFILEを使用する際は、以下の制限事項に注意してください：

テキストの圧縮形式はサポートされていません
バージョン2.1のパイプラインエンジンは並行エクスポートをサポートしていません

クイックスタート

Table作成とデータインポート

CREATE TABLE IF NOT EXISTS tbl (
    `c1` int(11) NULL,
    `c2` string NULL,
    `c3` bigint NULL
)
DISTRIBUTED BY HASH(c1) BUCKETS 20
PROPERTIES("replication_num" = "1");


insert into tbl values
    (1, 'doris', 18),
    (2, 'nereids', 20),
    (3, 'pipelibe', 99999),
    (4, 'Apache', 122123455),
    (5, null, null);

HDFSへのエクスポート

クエリ結果をディレクトリhdfs://path/to/にエクスポートし、エクスポート形式をParquetとして指定します：

SELECT c1, c2, c3 FROM tbl
INTO OUTFILE "hdfs://ip:port/path/to/result_"
FORMAT AS PARQUET
PROPERTIES
(
    "fs.defaultFS" = "hdfs://ip:port",
    "hadoop.username" = "hadoop"
);

Object Storageへのエクスポート

クエリ結果をs3ストレージのs3://bucket/export/ディレクトリにエクスポートし、エクスポート形式をORCとして指定します。sk（secret key）やak（access key）などの情報を提供する必要があります。

SELECT * FROM tbl
INTO OUTFILE "s3://bucket/export/result_"
FORMAT AS ORC
PROPERTIES(
    "s3.endpoint" = "xxxxx",
    "s3.region" = "xxxxx",
    "s3.secret_key"="xxxx",
    "s3.access_key" = "xxxxx"
);

Export手順

Export Desctination

SELECT INTO OUTFILEは現在、以下のストレージロケーションへのエクスポートをサポートしています：

Object Storage: Amazon S3, COS, OSS, OBS, Google GCS
HDFS

サポートされているファイルタイプ

SELECT INTO OUTFILEは現在、以下のファイル形式のエクスポートをサポートしています：

Parquet
ORC
csv
csv_with_names
csv_with_names_and_types

Export並行性

セッション変数enable_parallel_outfileを通じて並行エクスポートを有効にできます。

SET enable_parallel_outfile=true;

並行エクスポートは、マルチノードとマルチスレッドを使用して結果データをエクスポートし、全体的なエクスポートスループットを向上させます。ただし、並行エクスポートではより多くのファイルが生成される可能性があります。

この変数が有効になっていても、グローバルソートを含むクエリなど、一部のクエリでは並行エクスポートを実行できないことに注意してください。エクスポートコマンドによって返される行数が1より大きい場合、並行エクスポートが有効になっていることを意味します。

Exportの例

High Availabilityが有効なHDFSクラスターへのエクスポート

HDFSでhigh availabilityが有効になっている場合、以下のようなHA（High Availability）情報を提供する必要があります：

SELECT c1, c2, c3 FROM tbl
INTO OUTFILE "hdfs://HDFS8000871/path/to/result_"
FORMAT AS PARQUET
PROPERTIES
(
    "fs.defaultFS" = "hdfs://HDFS8000871",
    "hadoop.username" = "hadoop",
    "dfs.nameservices" = "your-nameservices",
    "dfs.ha.namenodes.your-nameservices" = "nn1,nn2",
    "dfs.namenode.rpc-address.HDFS8000871.nn1" = "ip:port",
    "dfs.namenode.rpc-address.HDFS8000871.nn2" = "ip:port",
    "dfs.client.failover.proxy.provider.HDFS8000871" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
);

高可用性とKerberos認証が有効なHDFSクラスターへのエクスポート

HDFSクラスターで高可用性が有効になっており、Kerberos認証が有効になっている場合は、以下のSQL文を参照してください：

SELECT * FROM tbl
INTO OUTFILE "hdfs://path/to/result_"
FORMAT AS PARQUET
PROPERTIES
(
    "fs.defaultFS"="hdfs://hacluster/",
    "hadoop.username" = "hadoop",
    "dfs.nameservices"="hacluster",
    "dfs.ha.namenodes.hacluster"="n1,n2",
    "dfs.namenode.rpc-address.hacluster.n1"="192.168.0.1:8020",
    "dfs.namenode.rpc-address.hacluster.n2"="192.168.0.2:8020",
    "dfs.client.failover.proxy.provider.hacluster"="org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider",
    "dfs.namenode.kerberos.principal"="hadoop/_HOST@REALM.COM",
    "hadoop.security.authentication"="kerberos",
    "hadoop.kerberos.principal"="doris_test@REALM.COM",
    "hadoop.kerberos.keytab"="/path/to/doris_test.keytab"
);

エクスポート成功インジケーターファイルの生成

SELECT INTO OUTFILEコマンドは同期コマンドです。そのため、SQLの実行中にタスク接続が切断される可能性があり、エクスポートされたデータが正常に終了したか、または完了しているかを知ることができません。この場合、success_file_nameパラメータを使用して、エクスポート成功後にディレクトリにファイルインジケーターを生成することを要求できます。

Hiveと同様に、ユーザーはエクスポートディレクトリにsuccess_file_nameパラメータで指定されたファイルが存在するかどうかを確認することで、エクスポートが正常に終了したか、およびエクスポートディレクトリ内のファイルが完全かどうかを判断できます。

例：selectステートメントのクエリ結果をオブジェクトストレージs3://bucket/export/にエクスポートします。エクスポート形式をcsvとして指定します。エクスポート成功インジケーターファイルの名前をSUCCESSとして指定します。エクスポートが完了すると、インジケーターファイルが生成されます。

SELECT k1,k2,v1 FROM tbl1 LIMIT 100000
INTO OUTFILE "s3://bucket/export/result_"
FORMAT AS CSV
PROPERTIES
(
    "s3.endpoint" = "xxxxx",
    "s3.region" = "xxxxx",
    "s3.secret_key"="xxxx",
    "s3.access_key" = "xxxxx",
    "column_separator" = ",",
    "line_delimiter" = "\n",
    "success_file_name" = "SUCCESS"
);

エクスポートが完了すると、もう1つファイルが書き込まれ、このファイルのファイル名はSUCCESSです。

エクスポート前のエクスポートディレクトリのクリア

SELECT * FROM tbl1
INTO OUTFILE "s3://bucket/export/result_"
FORMAT AS CSV
PROPERTIES
(
    "s3.endpoint" = "xxxxx",
    "s3.region" = "xxxxx",
    "s3.secret_key"="xxxx",
    "s3.access_key" = "xxxxx",
    "column_separator" = ",",
    "line_delimiter" = "\n",
    "delete_existing_files" = "true"
);

"delete_existing_files" = "true"が設定されている場合、エクスポートジョブは最初にs3://bucket/export/ディレクトリ下のすべてのファイルとディレクトリを削除し、その後このディレクトリにデータをエクスポートします。

delete_existing_filesパラメータを使用する場合は、fe.confに設定enable_delete_existing_files = trueを追加し、FEを再起動する必要もあります。そうして初めてdelete_existing_filesパラメータが有効になります。この操作は外部システムのデータを削除するため、高リスクな操作です。外部システムの権限とデータセキュリティについてはご自身で確保してください。

エクスポートファイルのサイズの設定

SELECT * FROM tbl
INTO OUTFILE "s3://path/to/result_"
FORMAT AS ORC
PROPERTIES(
    "s3.endpoint" = "xxxxx",
    "s3.region" = "xxxxx",
    "s3.secret_key"="xxxx",
    "s3.access_key" = "xxxxx",
    "max_file_size" = "2048MB"
);

"max_file_size" = "2048MB"が指定されているため、最終的に生成されるファイルが2GBより大きくない場合は、ファイルは1つだけになります。2GBより大きい場合は、複数のファイルになります。

注意事項

エクスポートデータ量とエクスポート効率

SELECT INTO OUTFILE機能は本質的にSQLクエリコマンドを実行しています。同時エクスポートが有効でない場合、クエリ結果は単一のBEノードで単一スレッドによってエクスポートされます。したがって、全体のエクスポート時間には、クエリ自体が消費する時間と最終結果セットの書き出しが消費する時間が含まれます。同時エクスポートを有効にすることで、エクスポート時間を短縮できます。
エクスポートタイムアウト

エクスポートコマンドのタイムアウト期間は、クエリのタイムアウト期間と同じです。大量のデータが原因でエクスポートデータがタイムアウトする場合は、セッション変数query_timeoutを設定してクエリタイムアウト期間を適切に延長できます。
エクスポートファイルの管理

Dorisはエクスポートされたファイルを管理しません。ファイルが正常にエクスポートされたか、エクスポート失敗後に残されたかにかかわらず、ユーザーが自分で処理する必要があります。

さらに、SELECT INTO OUTFILEコマンドは、ファイルやファイルパスが存在するかどうかをチェックしません。SELECT INTO OUTFILEコマンドが自動的にパスを作成するか、既存のファイルを上書きするかは、完全にリモートストレージシステムのセマンティクスによって決定されます。
クエリ結果セットが空の場合

結果セットが空のエクスポートの場合でも、空のファイルが生成されます。
ファイル分割

ファイル分割は、1行のデータが1つのファイルに完全に格納されることを保証します。したがって、ファイルのサイズはmax_file_sizeと厳密に等しくありません。
非表示文字を持つ関数

BITMAPやHLL型など、出力が非表示文字である一部の関数では、CSVファイル形式にエクスポートされる際、出力は\Nになります。

付録

ローカルファイルシステムへのエクスポート

ローカルファイルシステムへのエクスポート機能は、デフォルトで無効になっています。この機能はローカルデバッグと開発でのみ使用され、本番環境では使用すべきではありません。

この機能を有効にしたい場合は、fe.confにenable_outfile_to_local=trueを追加してFEを再起動してください。

例：tblTableのすべてのデータをローカルファイルシステムにエクスポートし、エクスポートジョブのファイル形式をcsv（デフォルト形式）に設定し、列区切り文字を,に設定します。

SELECT c1, c2 FROM db.tbl
INTO OUTFILE "file:///path/to/result_"
FORMAT AS CSV
PROPERTIES(
    "column_separator" = ","
);

この関数は、BEが配置されているノードのディスクにデータをエクスポートして書き込みます。複数のBEノードが存在する場合、エクスポートタスクの並行性に応じてデータは異なるBEノードに分散され、各ノードがデータの一部を保持します。

この例のように、最終的にBEノードの /path/to/ 配下に result_c6df5f01bd664dde-a2168b019b6c2b3f_0.csv のようなファイルセットが生成されます。

具体的なBEノードIPは、返却される結果に次のように表示されます：

+------------+-----------+----------+--------------------------------------------------------------------------+
| FileNumber | TotalRows | FileSize | URL                                                                      |
+------------+-----------+----------+--------------------------------------------------------------------------+
|          1 |   1195072 |  4780288 | file:///172.20.32.136/path/to/result_c6df5f01bd664dde-a2168b019b6c2b3f_* |
|          1 |   1202944 |  4811776 | file:///172.20.32.136/path/to/result_c6df5f01bd664dde-a2168b019b6c2b40_* |
|          1 |   1198880 |  4795520 | file:///172.20.32.137/path/to/result_c6df5f01bd664dde-a2168b019b6c2b43_* |
|          1 |   1198880 |  4795520 | file:///172.20.32.137/path/to/result_c6df5f01bd664dde-a2168b019b6c2b45_* |
+------------+-----------+----------+--------------------------------------------------------------------------+

注意

この関数は本番環境には適していません。エクスポートディレクトリの権限とデータセキュリティについては、ご自身で確保してください。

適用シナリオ​

クイックスタート​

Table作成とデータインポート​

HDFSへのエクスポート​

Object Storageへのエクスポート​

Export手順​

Export Desctination​

サポートされているファイルタイプ​

Export並行性​

Exportの例​

High Availabilityが有効なHDFSクラスターへのエクスポート​

高可用性とKerberos認証が有効なHDFSクラスターへのエクスポート​

エクスポート成功インジケーターファイルの生成​

エクスポート前のエクスポートディレクトリのクリア​

エクスポートファイルのサイズの設定​

注意事項​

付録​

ローカルファイルシステムへのエクスポート​