ApsaraDB for SelectDB:SELECT INTO OUTFILE

機能紹介

SELECT INTO OUTFILE は、SelectDB でのデータのバックアップまたは移行に使用できます。このコマンドには、次の特性があります。

• これは 同期コマンドです。

  • コマンドの実行が完了すると、エクスポートの実行ステータスとしてすぐに 1 行の結果が返されます。

  • 同期メカニズムのため、タスクステータスは完了後にのみ返されます。 接続が中断された場合、システムは中間ステータスを取得できないため、エクスポートが完全に完了したかどうかを判断できません。

    タスクの中断後にエクスポートの完了を判断できないことを回避するために、エクスポートタスクの作成時に プロパティ で "success_file_name" = "SUCCESS" を構成できます。 タスクが成功すると、指定された識別子ファイルが出力ディレクトリに生成されます。 このファイルが存在するかどうかを確認することで、エクスポートの完了を確認できます。

• 本質的には SQL クエリを実行します。

  このコマンドは本質的には SQL クエリを実行し、デフォルトでは単一スレッドを使用して結果を出力します。

• エクスポート時間: 合計エクスポート時間 = クエリ実行時間 + 結果セット書き込み時間

  大規模なクエリの場合、セッション変数 query_timeout を使用してタイムアウトのしきい値を上げる必要があります。 クエリセッション変数の設定方法については、「クエリ変数」をご参照ください。

• エクスポート結果はファイルです。

  このコマンドは、クエリ結果をファイルとしてエクスポートするために使用します。現在、S3 プロトコルまたは HDFS プロトコルを介して、OSS や HDFS などのリモートストレージへのエクスポートをサポートしています。

• エクスポート中にファイルとファイルパスが存在するかどうかは確認しません。

  このコマンドは、ファイルとファイルパスが存在するかどうかを確認せず、ディレクトリを自動的に作成したり、既存のファイルを上書きしたりしません。 具体的な動作は、リモートストレージシステム（S3/HDFS など）のルールによって完全に異なります。

  SelectDB は、エクスポートされたファイルを管理しません。 リモートストレージ側で、エクスポートされたすべてのファイル（成功したプロダクトと失敗した残存ファイルを含む）を管理およびクリーンアップする必要があります。

制限事項

現在、S3 または HDFS プロトコルを介したデータエクスポートのみがサポートされています。

注意事項

• データ型によって、エクスポートできるファイル型が異なります。

  • 基本データ型: CSV、PARQUET、CSV_WITH_NAMES、CSV_WITH_NAMES_AND_TYPES、および ORC 形式のファイルへのエクスポートをサポートします。

  • 複合データ型:

    • 複合データ型（ARRAY、MAP、STRUCT）の CSV、CSV_WITH_NAMES、CSV_WITH_NAMES_AND_TYPES、および ORC 形式のファイルへのエクスポートのみをサポートします。

    • ネストされた複合データ型のエクスポートはサポートしていません。

• 結果ファイルの注意事項:

  • 結果セットが空のクエリの場合でも、ファイルが生成されます。

  • ファイル分割により、データの完全な行が単一のファイルに格納されるため、ファイルサイズは max_file_size と厳密に等しくありません。

• 結果ファイルのコンテンツ出力の注意事項:

  • BITMAP 型や HLL 型など、表示されない文字を出力する関数の場合、出力は \N（NULL を意味する）です。

  • 現在、一部の地理位置情報関数は、エンコードされたバイナリ文字を出力します。 出力には ST_AsText を使用してください。 これらの地理位置情報関数には、次のものが含まれます。

    ST_CIRCLE、ST_POINT、ST_POLYGON、ST_GEOMETRYFROMTEXT、ST_LINEFROMTEXT、ST_GEOMETRYFROMWKB

<query_stmt>
INTO OUTFILE "<file_path>"
[format_as]
[properties]

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

並列エクスポート

デフォルトでは、クエリ結果セットのエクスポートは並列ではありません。つまり、単一の BE ノードによって単一スレッドでエクスポートされます。 したがって、エクスポート時間はエクスポート結果セットのサイズに直接関係します。

エクスポート時間を短縮するためにクエリ結果セットを並列でエクスポートする場合は、並列エクスポートを有効にできます。 手順は次のとおりです。

1. セッション変数を設定して並列エクスポートを有効にします: set enable_parallel_outfile = true;.

2. クエリを並列でエクスポートできるかどうかを確認します。

   並列エクスポートを有効にした後、現在のクエリを並列でエクスポートできるかどうかを確認する場合は、EXPLAIN を使用してクエリエクスポート文を分析できます。 構文は次のとおりです。

   EXPLAIN <select_into_outfile>;

   select_into_outfile は、実行する SELECT INTO OUTFILE 文です。 具体的な構文については、「構文」をご参照ください。

   クエリで EXPLAIN を使用した後、SelectDB はそのクエリのプランを返します。 クエリプランを分析して、クエリを並列でエクスポートできるかどうかを判断する必要があります。

   • RESULT FILE SINK が PLAN FRAGMENT 1 にある場合: クエリは並列でエクスポートできます。

     並列条件を満たすクエリの場合、be_instance_num * parallel_fragment_exec_instance_num を使用して、クエリ結果セットをエクスポートする並列度を計算できます。

     • be_instance_num は、BE クラスタ内のノードの数です。

       • 計算リソースが 32 コア以下のクラスタは単一ノードです。

       • 計算リソースが 32 コアを超えるクラスタは、32 コアごとに 1 つのノードがあります。

     • parallel_fragment_exec_instance_num は並列度パラメーターです。

       次の文を使用して、このパラメーターを表示できます。

       SHOW variables LIKE  '% parallel_fragment_exec_instance_num%'; 

       次の文を使用して、このパラメーターを設定します。

       SET  parallel_fragment_exec_instance_num = <parallel_fragment_exec_instance_num>;  

   • RESULT FILE SINK が PLAN FRAGMENT 0 にある場合: クエリは並列でエクスポートできません。

     以下は、SELECT INTO OUTFILE タスクのクエリプランです。ここで、RESULT FILE SINK は PLAN FRAGMENT 0 にあります。この SELECT INTO OUTFILE は並列でエクスポートできます。

     並列エクスポートプランの例:
     +-----------------------------------------------------------------------------+
     | Explain String                                                              |
     +-----------------------------------------------------------------------------+
     | PLAN FRAGMENT 0                                                             |
     |  OUTPUT EXPRS:<slot 2> | <slot 3> | <slot 4> | <slot 5>                     |
     |   PARTITION: UNPARTITIONED                                                  |
     |                                                                             |
     |   RESULT SINK                                                               |
     |                                                                             |
     |   1:EXCHANGE                                                                |
     |                                                                             |
     | PLAN FRAGMENT 1                                                             |
     |  OUTPUT EXPRS:`k1` + `k2`                                                   |
     |   PARTITION: HASH_PARTITIONED: `default_cluster:test`.`multi_tablet`.`k1`   |
     |                                                                             |
     |   RESULT FILE SINK                                                          |
     |   FILE PATH: s3://ml-bd-repo/bpit_test/outfile_1951_                        |
     |   STORAGE TYPE: S3                                                          |
     |                                                                             |
     |   0:OlapScanNode                                                            |
     |      TABLE: multi_tablet                                                    |
     +-----------------------------------------------------------------------------+

3. エクスポートを作成するSELECT INTO OUTFILE 構文データをエクスポートするためです。 に従ってエクスポートタスクを作成し、データをエクスポートします。

例

-- fileSystem_port のデフォルト値は 9000 です
SELECT * FROM tbl
INTO OUTFILE "hdfs://${host}:${fileSystem_port}/path/to/result_"
FORMAT AS CSV
PROPERTIES
(
    "fs.defaultFS" = "hdfs://ip:port",
    "hadoop.username" = "work"
);

--HA fileSystem_port のデフォルト値は 8020 です
SELECT * FROM tbl
INTO OUTFILE "hdfs:///path/to/result_"
FORMAT AS CSV
PROPERTIES
(
'fs.defaultFS'='hdfs://hacluster/',
'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'
);

SELECT k1 FROM tbl1 UNION SELECT k2 FROM tbl1
INTO OUTFILE "s3://oss-bucket/result_"
FORMAT AS PARQUET
PROPERTIES
(
    "s3.endpoint" = "oss-cn-hangzhou-internal.aliyuncs.com",
    "s3.access_key" = "****",
    "s3.secret_key" = "****",
    "s3.region" = "cn-hangzhou"
);

SET enable_parallel_outfile = true;

SELECT k1 FROM tb1 LIMIT 1000
INTO outfile "s3://my_bucket/export/my_file_"
format AS csv
properties
(
    "s3.endpoint" = "oss-cn-hangzhou-internal.aliyuncs.com",
    "s3.access_key" = "****",
    "s3.secret_key" = "****",
    "s3.region" = "cn-hangzhou"
)

SET enable_parallel_outfile = true;

SELECT k1 FROM tb1 ORDER BY k1 LIMIT 1000
INTO outfile "s3://my_bucket/export/my_file_"
format AS csv
properties
(
    "s3.endpoint" = "oss-cn-hangzhou-internal.aliyuncs.com",
    "s3.access_key" = "****",
    "s3.secret_key" = "****",
    "s3.region" = "cn-hangzhou"
)

データ型マッピング

Parquet ファイル形式と ORC ファイル形式の両方には、独自のデータ型があります。 SelectDB のエクスポート機能は、SelectDB データ型を Parquet/ORC ファイル形式の対応するデータ型に自動的にエクスポートできます。

• SelectDB から ORC ファイル形式へのデータ型マッピング:

  SelectDB 型	Orc 型
  boolean	boolean
  tinyint	tinyint
  smallint	smallint
  int	int
  bigint	bigint
  largeInt	string
  date	string
  datev2	string
  datetime	string
  datetimev2	timestamp
  float	float
  double	double
  char / varchar / string	string
  decimal	decimal
  struct	struct
  map	map
  array	array

• SelectDB から Parquet ファイル形式にデータをエクスポートする場合、SelectDB メモリ内のデータは最初に Arrow メモリデータ形式に変換され、次に Arrow によって Parquet ファイル形式に書き込まれます。 SelectDB データ型から Arrow データ型へのマッピング関係は次のとおりです。

  SelectDB 型	Arrow 型
  boolean	boolean
  tinyint	int8
  smallint	int16
  int	int32
  bigint	int64
  largeInt	utf8
  date	utf8
  datev2	utf8
  datetime	utf8
  datetimev2	utf8
  float	float32
  double	float64
  char / varchar / string	utf8
  decimal	decimal128
  struct	struct
  map	map
  array	list