EXPORT

説明

EXPORTコマンドは、指定されたテーブルから指定された場所のファイルにデータをエクスポートするために使用されます。現在、Brokerプロセス、S3プロトコル、またはHDFSプロトコルを通じて、HDFS、S3、BOS、COS（Tencent Cloud）などのリモートストレージへのエクスポートをサポートしています。

EXPORTは非同期操作です。このコマンドはEXPORT JOBをDorisに送信し、送信が成功すると即座に戻ります。実行後はSHOW EXPORTコマンドを使用して進行状況を確認できます。

構文:

EXPORT TABLE <table_name>
[ PARTITION ( <partation_name> [ , ... ] ) ]
[ <where_clause> ]
TO <export_path>
[ <properties> ]
WITH <target_storage>
[ <broker_properties> ];

必須パラメータ

1. <table_name>

エクスポートするテーブルの名前。Dorisローカルテーブル、ビュー、およびcatalog外部テーブルからのデータエクスポートをサポートします。

2. <export_path>

エクスポートファイルのパス。ディレクトリまたはhdfs://path/to/my_file_のようなファイルプレフィックス付きのファイルディレクトリを指定できます。

オプションパラメータ

1. <where_clause>

エクスポートするデータのフィルタ条件を指定できます。

2. <partation_name>

指定したテーブルの特定のパーティションのみをエクスポートできます。Dorisローカルテーブルでのみ有効です。

3. <properties>

一部のエクスポートパラメータを指定するために使用します。

[ PROPERTIES ("<key>"="<value>" [, ... ]) ]

以下のパラメータを指定できます：

• label: このExportタスクのLabelを指定するオプションパラメータ。指定されていない場合、システムはランダムにLabelを生成します。

• column_separator: エクスポート用の列区切り文字を指定します。デフォルトは\tで、マルチバイトをサポートします。このパラメータはCSVファイル形式でのみ使用されます。

• line_delimiter: エクスポート用の行区切り文字を指定します。デフォルトは\nで、マルチバイトをサポートします。このパラメータはCSVファイル形式でのみ使用されます。

• columns: エクスポートテーブルの特定の列を指定します。

• format: エクスポートジョブのファイル形式を指定します。サポート形式: parquet, orc, csv, csv_with_names, csv_with_names_and_types。デフォルトはCSV形式です。

• max_file_size: エクスポートジョブの単一ファイルサイズ制限。結果がこの値を超える場合、複数のファイルに分割されます。max_file_sizeの値の範囲は[5MB, 2GB]で、デフォルトは1GBです。（orcファイル形式へのエクスポートを指定する場合、実際の分割ファイルサイズは64MBの倍数になります。例：max_file_size = 5MBを指定すると実際には64MBで分割され、max_file_size = 65MBを指定すると実際には128MBで分割されます）

• parallelism: エクスポートジョブの並行度、デフォルトは1です。エクスポートジョブはparallelism数のスレッドを開始してselect into outfile文を実行します。（Parallelismの数がテーブル内のTablets数より多い場合、システムは自動的にParallelismをTablets数のサイズに設定します。つまり、各select into outfile文が1つのTabletを担当します）

• delete_existing_files: デフォルトはfalseです。trueに指定すると、export_pathで指定されたディレクトリ内のすべてのファイルが最初に削除され、その後そのディレクトリにデータがエクスポートされます。例："export_path" = "/user/tmp"の場合、"/user/"配下のすべてのファイルとディレクトリが削除されます；"file_path" = "/user/tmp/"の場合、"/user/tmp/"配下のすべてのファイルとディレクトリが削除されます。

• with_bom: デフォルトはfalseです。trueに指定すると、エクスポートファイルのエンコーディングはBOM付きUTF8エンコーディングになります（csv関連ファイル形式でのみ有効）。

• data_consistency: none / partitionに設定可能で、デフォルトはpartitionです。エクスポートテーブルを分割する粒度を示し、noneはTabletsレベル、partitionはPartitionレベルを表します。

• timeout: エクスポートジョブのタイムアウト、デフォルトは2時間、単位は秒です。

• compress_type: （2.1.5以降サポート）エクスポートファイル形式をParquet / ORCファイルに指定する場合、Parquet / ORCファイルで使用される圧縮方法を指定できます。Parquetファイル形式では圧縮方法としてSNAPPY、GZIP、BROTLI、ZSTD、LZ4、PLAINを指定でき、デフォルト値はSNAPPYです。ORCファイル形式では圧縮方法としてPLAIN、SNAPPY、ZLIB、ZSTDを指定でき、デフォルト値はZLIBです。このパラメータはバージョン2.1.5以降でサポートされています。（PLAINは圧縮なしを意味します）。バージョン3.1.1以降、CSV形式の圧縮アルゴリズムの指定をサポートし、現在"plain"、"gz"、"bz2"、"snappyblock"、"lz4block"、"zstd"をサポートしています。

注意

delete_existing_filesパラメータを使用するには、fe.confに設定enable_delete_existing_files = trueを追加してfeを再起動する必要があります。その後delete_existing_filesが有効になります。delete_existing_files = trueは危険な操作であり、テスト環境でのみ使用することを推奨します。

4. <target_storage>
ストレージメディア、オプションでBROKER、S3、HDFS。

5. <broker_properties>
<target_storage>の異なるストレージメディアに応じて異なるプロパティを指定する必要があります。

• BROKER
  データはBrokerプロセスを通じてリモートストレージに書き込むことができます。ここではBrokerが使用するための関連する接続情報を定義する必要があります。

  WITH BROKER "broker_name"
  ("<key>"="<value>" [,...])

Broker関連のプロパティ:

• username: ユーザー名

• password: パスワード

• hadoop.security.authentication: 認証方式をkerberosとして指定

• kerberos_principal: kerberos principalを指定

• kerberos_keytab: kerberos keytabファイルへのパスを指定。このファイルはBrokerプロセスが配置されているサーバー上のファイルへの絶対パスである必要があり、Brokerプロセスからアクセス可能である必要があります

• HDFS

  データはリモートHDFSに直接書き込むことができます。

  WITH HDFS ("<key>"="<value>" [,...])

HDFS関連プロパティ:

• fs.defaultFS: namenodeアドレスとポート
• hadoop.username: HDFSユーザー名
• dfs.nameservices: ネームサービス名、hdfs-site.xmlと一致させる
• dfs.ha.namenodes.[nameservice ID]: namenodeのIDリスト、hdfs-site.xmlと一致させる
• dfs.namenode.rpc-address.[nameservice ID].[name node ID]: Name nodeのrpcアドレス、namenode数と同じ数、hdfs-site.xmlと一致させる

kerberos認証が有効なHadoopクラスターの場合、以下の追加のPROPERTIES属性を設定する必要があります:

• dfs.namenode.kerberos.principal: HDFS namenodeサービスのプリンシパル名

• hadoop.security.authentication: 認証方式をkerberosに設定

• hadoop.kerberos.principal: DorisがHDFSに接続する際に使用するKerberosプリンシパルを設定

• hadoop.kerberos.keytab: keytabのローカルファイルパスを設定

• S3

  データは直接リモートS3オブジェクトストレージに書き込むことができます。

  WITH S3 ("<key>"="<value>" [,...])

S3関連プロパティ:

• s3.endpoint
• s3.region
• s3.secret_key
• s3.access_key
• use_path_style: （オプション）デフォルトはfalse。S3 SDKはデフォルトでVirtual-hosted Styleを使用します。ただし、一部のオブジェクトストレージシステムではVirtual-hosted Styleアクセスが有効になっていない、またはサポートされていない場合があります。この場合、use_path_styleパラメータを追加してPath Styleアクセスを強制的に使用することができます。

戻り値

カラム名	型	説明
jobId	long	エクスポートジョブの一意の識別子。
label	string	エクスポートジョブのラベル。
dbId	long	データベースの識別子。
tableId	long	テーブルの識別子。
state	string	ジョブの現在の状態。
path	string	エクスポートファイルのパス。
partitions	string	エクスポートされたパーティション名のリスト、複数のパーティション名はカンマで区切られます。
progress	int	エクスポートジョブの現在の進捗（パーセンテージ）。
createTimeMs	string	ジョブ作成時刻のミリ秒値、日時形式でフォーマット。
exportStartTimeMs	string	エクスポートジョブ開始時刻のミリ秒値、日時形式でフォーマット。
exportFinishTimeMs	string	エクスポートジョブ終了時刻のミリ秒値、日時形式でフォーマット。
failMsg	string	エクスポートジョブが失敗した際のエラーメッセージ。

アクセス制御

このSQLコマンドを実行するユーザーは、少なくとも以下の権限を持つ必要があります：

権限	オブジェクト	説明
SELECT_PRIV	Database	データベースとテーブルに対する読み取り権限が必要。

注意事項

同時実行

Exportジョブはparallelismパラメータを設定してデータを同時にエクスポートできます。parallelismパラメータは実際にEXPORTジョブを実行するスレッド数を指定します。"data_consistency" = "none"が設定されている場合、各スレッドはテーブルのTabletsの一部をエクスポートする責任を持ちます。

Exportジョブの基底実行ロジックは実際にはSELECT INTO OUTFILE文です。parallelismパラメータで設定された各スレッドは独立したSELECT INTO OUTFILE文を実行します。

Exportジョブを複数のSELECT INTO OUTFILEに分割する具体的なロジックは：テーブルのすべてのtabletsを全ての並列スレッドに均等に分散すること、例えば：

• num(tablets) = 40、parallelism = 3の場合、これら3つのスレッドはそれぞれ14、13、13個のtabletsを担当します。
• num(tablets) = 2、parallelism = 3の場合、Dorisは自動的にparallelismを2に設定し、各スレッドが1つのtabletを担当します。

スレッドが担当するtabletsがmaximum_tablets_of_outfile_in_export値（デフォルトは10、fe.confでmaximum_tablets_of_outfile_in_exportパラメータを追加して変更可能）を超える場合、そのスレッドは複数のSELECT INTO OUTFILE文に分割されます。例えば：

• スレッドが14個のtabletsを担当し、maximum_tablets_of_outfile_in_export = 10の場合、このスレッドは2つのSELECT INTO OUTFILE文を担当します。最初のSELECT INTO OUTFILE文は10個のtabletsをエクスポートし、2番目のSELECT INTO OUTFILE文は4個のtabletsをエクスポートします。この2つのSELECT INTO OUTFILE文はこのスレッドによって逐次実行されます。

エクスポートするデータ量が非常に大きい場合、parallelismパラメータを適切に増加させて同時エクスポートを増やすことを検討できます。マシンのコアが不足しておりparallelismを増やすことができない一方で、エクスポートテーブルに多くのTabletsがある場合、maximum_tablets_of_outfile_in_exportを増やしてSELECT INTO OUTFILE文が担当するtablets数を増加させることを検討でき、これによりエクスポートの高速化も可能です。

Partition粒度でTableをエクスポートしたい場合、Exportプロパティ"data_consistency" = "partition"を設定できます。この場合、ExportタスクのConcurrentスレッドはPartition粒度で複数のOutfile文に分割されます。異なるOutfile文は異なるPartitionsをエクスポートし、同じOutfile文によってエクスポートされたデータは同じPartitionに属する必要があります。例えば："data_consistency" = "partition"を設定した後

• num(partition) = 40、parallelism = 3の場合、これら3つのスレッドはそれぞれ14、13、13個のPartitionsを担当します。
• num(partition) = 2、parallelism = 3の場合、Dorisは自動的にParallelismを2に設定し、各スレッドが1つのPartitionを担当します。

メモリ制限

通常、Exportジョブのクエリプランはscan-exportの2つの部分のみで、過度なメモリを必要とする計算ロジックは含まれません。そのため、通常はデフォルトの2GBのメモリ制限で要件を満たすことができます。

しかし、一部のシナリオでは、クエリプランが同一BE上で過度に多くのTabletsをスキャンする必要がある場合や、Tabletデータバージョンが過度に多い場合、メモリ不足を引き起こす可能性があります。セッション変数exec_mem_limitを調整してメモリ使用制限を増やすことができます。

その他の事項

• 大量のデータを一度にエクスポートすることは推奨されません。1つのExportジョブの推奨最大エクスポートデータ量は数十GBです。過度に大きなエクスポートは、より多くのガベージファイルとより高い再試行コストを引き起こします。テーブルデータ量が過度に大きい場合は、パーティション別にエクスポートすることを推奨します。

• Exportジョブが失敗した場合、すでに生成されたファイルは削除されず、ユーザーが手動で削除する必要があります。

• Exportジョブはデータをスキャンし、IOリソースを占有するため、システムクエリレイテンシに影響を与える可能性があります。

• 現在Export中は、Tabletsバージョンが一致しているかの簡単なチェックのみが実行されます。Export実行中はテーブルに対するデータインポート操作を実行しないことを推奨します。

• Export Jobは最大2000パーティションのエクスポートが可能です。fe.confでパラメータmaximum_number_of_export_partitionsを追加し、FEを再起動してこの設定を変更できます。

例

ローカルへのデータエクスポート

ローカルファイルシステムにデータをエクスポートするには、fe.confでenable_outfile_to_local=trueを追加し、FEを再起動する必要があります。

• Testテーブルのすべてのデータをローカルストレージにエクスポート、デフォルトでCSV形式ファイルをエクスポート

EXPORT TABLE test TO "file:///home/user/tmp/";

• Test テーブルの k1,k2 カラムをローカルストレージにエクスポートし、デフォルトで CSV ファイル形式でエクスポートして、Label を設定する

EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "label" = "label1",
  "columns" = "k1,k2"
);

• Test テーブルで k1 < 50 の行をローカルストレージにエクスポートし、デフォルトで CSV フォーマットファイルをエクスポートし、, を列の区切り文字として使用する

EXPORT TABLE test WHERE k1 < 50 TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "column_separator"=","
);

• Testテーブルのパーティションp1、p2をローカルストレージにエクスポートし、デフォルトでcsvフォーマットファイルをエクスポートします

EXPORT TABLE test PARTITION (p1,p2) TO "file:///home/user/tmp/" 
PROPERTIES ("columns" = "k1,k2");

• Test tableの全データをローカルストレージにエクスポートし、他の形式のファイルをエクスポートする

-- parquet
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "format" = "parquet"
);

-- orc
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "columns" = "k1,k2",
  "format" = "orc"
);

-- csv(csv_with_names) , Use 'AA' as the column separator and 'zz' as the row separator
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "csv_with_names",
  "column_separator"="AA",
  "line_delimiter" = "zz"
);

-- csv(csv_with_names_and_types) 
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "csv_with_names_and_types"
);

• max_file_sizesプロパティを設定する
  エクスポートされたファイルが5MBより大きい場合、データは複数のファイルに分割され、各ファイルは最大5MBになります。

-- When the exported file is larger than 5MB, the data will be split into multiple files, with each file having a maximum size of 5MB.
EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB"
);

• parallelismプロパティを設定する

EXPORT TABLE test TO "file:///home/user/tmp/"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB",
  "parallelism" = "5"
);

• delete_existing_filesプロパティを設定する
  Exportがデータをエクスポートする際、まず/home/user/ディレクトリ下のすべてのファイルとディレクトリを削除してから、このディレクトリにデータをエクスポートします。

-- When exporting data, all files and directories under the `/home/user/` directory will be deleted first, and then the data will be exported to this directory.
EXPORT TABLE test TO "file:///home/user/tmp"
PROPERTIES (
  "format" = "parquet",
  "max_file_size" = "5MB",
  "delete_existing_files" = "true"
);

S3へのエクスポート

• s3_testテーブルの全データをS3にエクスポートし、非表示文字\x07を列または行の区切り文字として使用します。データをminioにエクスポートする必要がある場合は、use_path_style=trueも指定する必要があります。

EXPORT TABLE s3_test TO "s3://bucket/a/b/c" 
PROPERTIES (
  "column_separator"="\\x07", 
  "line_delimiter" = "\\x07"
) WITH S3 (
  "s3.endpoint" = "xxxxx",
  "s3.region" = "xxxxx",
  "s3.access_key" = "xxxxx",
  "s3.secret_key"="xxxx"
  
)

HDFSへのエクスポート

• Testテーブルの全データをHDFSにエクスポートし、エクスポートファイル形式はParquet、エクスポートジョブの単一ファイルサイズ制限は512MB、指定されたディレクトリ内に全ファイルを保持します。

EXPORT TABLE test TO "hdfs://hdfs_host:port/a/b/c/" 
PROPERTIES(
    "format" = "parquet",
    "max_file_size" = "512MB",
    "delete_existing_files" = "false"
)
with HDFS (
"fs.defaultFS"="hdfs://hdfs_host:port",
"hadoop.username" = "hadoop"
);

Broker Node経由でのエクスポート

最初にBrokerプロセスを開始し、このBrokerをFEに追加する必要があります。

• TestテーブルのすべてのデータをHDFSにエクスポート

EXPORT TABLE test TO "hdfs://hdfs_host:port/a/b/c" 
WITH BROKER "broker_name" 
(
  "username"="xxx",
  "password"="yyy"
);

• testTblテーブルのパーティションp1、p2をHDFSにエクスポートし、列区切り文字として","を使用し、Labelを指定する

EXPORT TABLE testTbl PARTITION (p1,p2) TO "hdfs://hdfs_host:port/a/b/c" 
PROPERTIES (
  "label" = "mylabel",
  "column_separator"=","
) 
WITH BROKER "broker_name" 
(
  "username"="xxx",
  "password"="yyy"
);

• testTblテーブルの全データをHDFSにエクスポートし、不可視文字\x07を列または行の区切り文字として使用する。

EXPORT TABLE testTbl TO "hdfs://hdfs_host:port/a/b/c" 
PROPERTIES (
  "column_separator"="\\x07", 
  "line_delimiter" = "\\x07"
) 
WITH BROKER "broker_name" 
(
  "username"="xxx", 
  "password"="yyy"
)