Skip to content

unload_using_insert_into_files.md

Latest commit

 

History

History
268 lines (211 loc) · 11.8 KB

unload_using_insert_into_files.md

File metadata and controls

268 lines (211 loc) · 11.8 KB
Raw
displayed_sidebar docs
description StarRocks v3.2 以降は INSERT INTO FILES でテーブル関数 FILES() を使用してリモートストレージにデータをアンロードできます。

INSERT INTO FILES を使用したデータのアンロード

このトピックでは、INSERT INTO FILES を使用して StarRocks からリモートストレージにデータをアンロードする方法について説明します。

バージョン 3.2 以降、StarRocks はテーブル関数 FILES() を使用してリモートストレージに書き込み可能なファイルを定義することをサポートしています。その後、FILES() を INSERT 文と組み合わせて、StarRocks からリモートストレージにデータをアンロードできます。

StarRocks がサポートする他のデータエクスポート方法と比較して、INSERT INTO FILES を使用したデータのアンロードは、より統一された使いやすいインターフェースを提供します。データをロードする際に使用したのと同じ構文を使用して、リモートストレージに直接データをアンロードできます。さらに、この方法は、指定された列の値を抽出することによって、異なるストレージパスにデータファイルを保存することをサポートしており、エクスポートされたデータをパーティション化されたレイアウトで管理することができます。

NOTE

INSERT INTO FILES を使用したデータのアンロードは、ローカルファイルシステムへの直接エクスポートをサポートしていません。ただし、NFS を使用してローカルファイルにデータをエクスポートすることができます。詳細は Unload to local files using NFS を参照してください。

準備

次の例では、データベース unload とテーブル sales_records を作成し、以下のチュートリアルで使用できるデータオブジェクトとして使用します。ご自身のデータを使用することもできます。

CREATE DATABASE unload;
USE unload;
CREATE TABLE sales_records(
    record_id     BIGINT,
    seller        STRING,
    store_id      INT,
    sales_time    DATETIME,
    sales_amt     DOUBLE
)
DUPLICATE KEY(record_id)
PARTITION BY date_trunc('day', sales_time)
DISTRIBUTED BY HASH(record_id);

INSERT INTO sales_records
VALUES
    (220313001,"Amy",1,"2022-03-13 12:00:00",8573.25),
    (220314002,"Bob",2,"2022-03-14 12:00:00",6948.99),
    (220314003,"Amy",1,"2022-03-14 12:00:00",4319.01),
    (220315004,"Carl",3,"2022-03-15 12:00:00",8734.26),
    (220316005,"Carl",3,"2022-03-16 12:00:00",4212.69),
    (220317006,"Bob",2,"2022-03-17 12:00:00",9515.88);

テーブル sales_records には、各トランザクションのトランザクション ID record_id、販売員 seller、店舗 ID store_id、時間 sales_time、販売額 sales_amt が含まれています。これは sales_time に基づいて日次でパーティション化されています。

また、書き込みアクセス権を持つリモートストレージシステムを準備する必要があります。以下の例では、次のリモートストレージにデータをエクスポートします。

  • シンプル認証方式が有効な HDFS クラスター。
  • IAM ユーザー資格情報を使用した AWS S3 バケット。

FILES() がサポートするリモートストレージシステムと資格情報方法の詳細については、SQL reference - FILES() を参照してください。

データのアンロード

INSERT INTO FILES は、単一ファイルまたは複数ファイルへのデータのアンロードをサポートしています。これらのデータファイルを別々のストレージパスに指定することで、さらにパーティション化することができます。

INSERT INTO FILES を使用してデータをアンロードする際には、プロパティ compression を使用して圧縮アルゴリズムを手動で設定する必要があります。FILES がサポートするデータ圧縮アルゴリズムの詳細については、unload_data_param を参照してください。

複数ファイルへのデータのアンロード

デフォルトでは、INSERT INTO FILES はデータを複数のデータファイルにアンロードし、各ファイルのサイズは 1 GB です。プロパティ target_max_file_size を使用してファイルサイズを設定できます（単位: バイト）。

次の例では、sales_records のすべてのデータ行を data1 というプレフィックスの付いた複数の Parquet ファイルとしてアンロードします。各ファイルのサイズは 1 KB です。

:::note

ここで target_max_file_size を 1 KB に設定しているのは、小さなデータセットで複数ファイルにアンロードすることを示すためです。本番環境では、この値を数百 MB から数 GB の範囲内に設定することを強くお勧めします。

:::

  • S3 へのアンロード:
INSERT INTO 
FILES(
    "path" = "s3://mybucket/unload/data1",
    "format" = "parquet",
    "compression" = "uncompressed",
    "target_max_file_size" = "1024", -- 1KB
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "yyyyyyyyyy",
    "aws.s3.region" = "us-west-2"
)
SELECT * FROM sales_records;
  • HDFS へのアンロード:
INSERT INTO 
FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/data1",
    "format" = "parquet",
    "compression" = "uncompressed",
    "target_max_file_size" = "1024", -- 1KB
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx"
)
SELECT * FROM sales_records;

異なるパスの下に複数ファイルへのデータのアンロード

プロパティ partition_by を使用して、指定された列の値を抽出することで、異なるストレージパスにデータファイルをパーティション化することもできます。

次の例では、sales_records のすべてのデータ行を /unload/partitioned/ パスの下にある複数の Parquet ファイルとしてアンロードします。これらのファイルは、列 sales_time の値によって区別される異なるサブパスに保存されます。

  • S3 へのアンロード:
INSERT INTO 
FILES(
    "path" = "s3://mybucket/unload/partitioned/",
    "format" = "parquet",
    "compression" = "lz4",
    "partition_by" = "sales_time",
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "yyyyyyyyyy",
    "aws.s3.region" = "us-west-2"
)
SELECT * FROM sales_records;
  • HDFS へのアンロード:
INSERT INTO 
FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/partitioned/",
    "format" = "parquet",
    "compression" = "lz4",
    "partition_by" = "sales_time",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx"
)
SELECT * FROM sales_records;

単一ファイルへのデータのアンロード

データを単一のデータファイルにアンロードするには、プロパティ single を true に指定する必要があります。

次の例では、sales_records のすべてのデータ行を data2 というプレフィックスの付いた単一の Parquet ファイルとしてアンロードします。

  • S3 へのアンロード:
INSERT INTO 
FILES(
    "path" = "s3://mybucket/unload/data2",
    "format" = "parquet",
    "compression" = "lz4",
    "single" = "true",
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "yyyyyyyyyy",
    "aws.s3.region" = "us-west-2"
)
SELECT * FROM sales_records;
  • HDFS へのアンロード:
INSERT INTO 
FILES(
    "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/data2",
    "format" = "parquet",
    "compression" = "lz4",
    "single" = "true",
    "hadoop.security.authentication" = "simple",
    "username" = "xxxxx",
    "password" = "xxxxx"
)
SELECT * FROM sales_records;

MinIO へのアンロード

MinIO 用のパラメータは、AWS S3 用のパラメータとは異なります。

例:

INSERT INTO 
FILES(
    "path" = "s3://huditest/unload/data3",
    "format" = "parquet",
    "compression" = "zstd",
    "single" = "true",
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "yyyyyyyyyy",
    "aws.s3.region" = "us-west-2",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.enable_ssl" = "false",
    "aws.s3.enable_path_style_access" = "true",
    "aws.s3.endpoint" = "http://minio:9000"
)
SELECT * FROM sales_records;

NFS を使用したローカルファイルへのアンロード

file:// プロトコルを介して NFS 内のファイルにアクセスするには、各 BE または CN ノードの同じディレクトリの下に NAS デバイスを NFS としてマウントする必要があります。

例:

-- CSV ファイルへのデータのアンロード。
INSERT INTO FILES(
  'path' = 'file:///home/ubuntu/csvfile/',
  'format' = 'csv',
  'csv.column_separator' = ',',
  'csv.row_delimitor' = '\n'
)
SELECT * FROM sales_records;

-- フィールド囲み (RFC 4180 スタイル) で CSV ファイルにアンロード。
-- カンマや引用符を含むフィールド値は enclose 文字で囲まれ、内部の
-- 引用符は重複によってエスケープされます (csv.escape と csv.enclose が
-- 同じため)。NULL 値は囲まずに \N として出力されます。
INSERT INTO FILES(
  'path' = 'file:///home/ubuntu/csvfile_enclosed/',
  'format' = 'csv',
  'csv.column_separator' = ',',
  'csv.row_delimiter' = '\n',
  'csv.enclose' = '"',
  'csv.escape' = '"',
  'csv.include_header' = 'true'
)
SELECT * FROM sales_records;

-- データを Parquet ファイルに書き出し、Parquet バージョンを 1.0 に設定します。
INSERT INTO FILES(
  'path' = 'file:///home/ubuntu/parquetfile/',
  'format' = 'parquet',
  'parquet.version' = '1.0'
)
SELECT * FROM sales_records;

:::note

csv.enclose が設定されると、すべての非 NULL フィールド値は enclose 文字で囲まれ、 フィールド値内に現れる enclose 文字 (および csv.escape が異なる場合は escape 文字 自身) は csv.escape 文字でエスケープされます。NULL 値は囲まずに \N として出力 されます。

RFC 4180 形式の二重引用符出力 (csv.escape が csv.enclose と等しい) を StarRocks に再インポートする場合、読み取り側では csv.enclose のみを設定し、csv.escape は 設定しないでください。StarRocks の CSV reader は ENCLOSE 状態を通じて二重引用符を ネイティブに処理します。

また、NULL 値が正しく roundtrip するのは csv.escape がバックスラッシュ (\) で ない場合に限られます。NULL マーカーは \N に固定されており、csv.escape = '\\' の 場合、読み取り側の ESCAPE 状態が先頭のバックスラッシュを取り除くため、\N は NULL ではなく文字リテラル N として解釈されます。NULL の roundtrip が必要なデータセット では csv.escape = '"' (RFC 4180 の二重引用符) を使用してください。

:::

参照