📣新登場！TiDB Cloud BYOC、TiDB Cloud Filesystem、PostgreSQL-compatible TiDB Cloud Starter がパブリックプレビュー中。このページは自動翻訳されたものです。原文はこちらからご覧ください。
AI
開発者
ベストプラクティス
API

COPY INTO <location>

COPY INTO を使用すると、テーブルまたはクエリからデータを、以下のいずれかの場所にある 1 つ以上のファイルへアンロードできます。

  • ユーザー / 内部 / 外部 stage: TiDB Cloud Lake の stage については、Stage とは？ を参照してください。
  • ストレージサービスで作成されたバケットまたはコンテナ。

関連情報: COPY INTO <table>

構文

COPY INTO { internalStage | externalStage | externalLocation }
FROM { [<database_name>.]<table_name> | ( <query> ) }
[ PARTITION BY ( <expr> ) ]
[ FILE_FORMAT = (
         FORMAT_NAME = '<your-custom-format>'
         | TYPE = { CSV | TSV | NDJSON | PARQUET | LANCE } [ formatTypeOptions ]
       ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_ROWS ]
[ DETAILED_OUTPUT = true | false ]

internalStage

internalStage ::= @<internal_stage_name>[/<path>]

externalStage

externalStage ::= @<external_stage_name>[/<path>]

externalLocation

    externalLocation ::=
  's3://<bucket>[<path>]'
  CONNECTION = (
        <connection_parameters>
  )

    Amazon S3 互換ストレージサービスへのアクセスに使用できる接続パラメータについては、接続パラメータ を参照してください。

    externalLocation ::=
  'azblob://<container>[<path>]'
  CONNECTION = (
        <connection_parameters>
  )

    Azure Blob Storage へのアクセスに使用できる接続パラメータについては、接続パラメータ を参照してください。

    externalLocation ::=
  'gcs://<bucket>[<path>]'
  CONNECTION = (
        <connection_parameters>
  )

    Google Cloud Storage へのアクセスに使用できる接続パラメータについては、接続パラメータ を参照してください。

    externalLocation ::=
  'oss://<bucket>[<path>]'
  CONNECTION = (
        <connection_parameters>
  )

    Alibaba Cloud OSS へのアクセスに使用できる接続パラメータについては、接続パラメータ を参照してください。

    externalLocation ::=
  'cos://<bucket>[<path>]'
  CONNECTION = (
        <connection_parameters>
  )

    Tencent Cloud Object Storage へのアクセスに使用できる接続パラメータについては、接続パラメータ を参照してください。

    FILE_FORMAT

    詳細は 入出力ファイル形式 を参照してください。

    LANCE は COPY INTO <location> でのみサポートされます。TiDB Cloud Lake は、単一のファイルではなく、対象パス配下に Lance データセットディレクトリを書き込みます。

    PARTITION BY

    アンロードされたデータを個別のフォルダに分割するために使用する式を指定します。この式は STRING 型として評価される必要があります。式によって生成される値ごとに、宛先パスの下にサブフォルダが作成され、対応する行はそのサブフォルダ配下のファイルに書き込まれます。

    • 式が NULL と評価された場合、行は特別な _NULL_ フォルダに配置されます。
    • この式では、ソーステーブルまたはクエリの任意のカラムを参照できます。
    • パーティション値でのパストラバーサル (..) は許可されません。

    以下のオプションは PARTITION BY と互換性がなく、設定するとエラーになります。

    オプション制約
    SINGLEPARTITION BY 使用時は TRUE にできません。
    OVERWRITEPARTITION BY 使用時は TRUE にできません。
    INCLUDE_QUERY_IDPARTITION BY 使用時は FALSE にできません。

    copyOptions

    copyOptions ::=
  [ SINGLE = true | false ]
  [ MAX_FILE_SIZE = <num> ]
  [ OVERWRITE = true | false ]
  [ INCLUDE_QUERY_ID = true | false ]
  [ USE_RAW_PATH = true | false ]
    パラメータデフォルト説明
    SINGLEfalsetrue の場合、このコマンドはデータを 1 つの単一ファイルにアンロードします。
    MAX_FILE_SIZE67108864 bytes (64 MB)作成される各ファイルの最大サイズ（バイト単位）です。SINGLE が false の場合に有効です。
    OVERWRITEfalsetrue の場合、対象パスに同名の既存ファイルがあると上書きされます。注: OVERWRITE = true には USE_RAW_PATH = true と INCLUDE_QUERY_ID = false が必要です。
    INCLUDE_QUERY_IDtruetrue の場合、エクスポートされるファイル名に一意の UUID が含まれます。
    USE_RAW_PATHfalsetrue の場合、ユーザーが指定したパスそのもの（完全なファイル名を含む）がデータのエクスポートに使用されます。false に設定した場合、ユーザーはディレクトリパスを指定する必要があります。

    DETAILED_OUTPUT

    データのアンロード結果の詳細を返すかどうかを決定します。デフォルト値は false です。詳細については、出力 を参照してください。

    出力

    COPY INTO は、データのアンロード結果の要約を以下のカラムで提供します。

    カラム説明
    rows_unloaded宛先へのアンロードに成功した行数。
    input_bytesアンロード操作中にソーステーブルから読み取られたデータの合計サイズ（バイト単位）。
    output_bytes宛先に書き込まれたデータの合計サイズ（バイト単位）。

    DETAILED_OUTPUT を true に設定すると、COPY INTO は以下のカラムを含む結果を返します。これは、特に MAX_FILE_SIZE を使用してアンロードされたデータを複数ファイルに分割する場合に、アンロードされたファイルの場所を特定するのに役立ちます。

    カラム説明
    file_nameアンロードされたファイルの名前。
    file_sizeアンロードされたファイルのサイズ（バイト単位）。
    row_countアンロードされたファイルに含まれる行数。

    例

    このセクションでは、以下のテーブルとデータを使用して例を示します。

    -- Create sample table
CREATE TABLE canadian_city_population (
     city_name VARCHAR(50),
     population INT
);

-- Insert sample data
INSERT INTO canadian_city_population (city_name, population)
VALUES
('Toronto', 2731571),
('Montreal', 1704694),
('Vancouver', 631486),
('Calgary', 1237656),
('Ottawa', 934243),
('Edmonton', 972223),
('Quebec City', 542298),
('Winnipeg', 705244),
('Hamilton', 536917),
('Halifax', 403390);

    例 1: 内部 stage へのアンロード (unload)

    この例では、データを内部 stage にアンロードします。

    -- Create an internal stage
CREATE STAGE my_internal_stage;

-- Unload data from the table to the stage using the PARQUET file format
COPY INTO @my_internal_stage
    FROM canadian_city_population
    FILE_FORMAT = (TYPE = PARQUET);

┌────────────────────────────────────────────┐
│ rows_unloaded │ input_bytes │ output_bytes │
├───────────────┼─────────────┼──────────────┤
│            10 │         211 │          572 │
└────────────────────────────────────────────┘

LIST @my_internal_stage;

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                               name                              │  size  │        md5       │         last_modified         │      creator     │
├─────────────────────────────────────────────────────────────────┼────────┼──────────────────┼───────────────────────────────┼──────────────────┤
│ data_abe520a3-ee88-488c-9221-b07c562c9a30_0000_00000000.parquet │    572 │ NULL             │ 2024-01-18 16:20:48.979 +0000 │ NULL             │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

    例 2: 圧縮ファイルへのアンロード (unload)

    この例では、データを圧縮ファイルにアンロードします。

    -- Create an internal stage
CREATE STAGE my_internal_stage;

-- Unload data from the table to the stage using the CSV file format with gzip compression
COPY INTO @my_internal_stage
    FROM canadian_city_population
    FILE_FORMAT = (TYPE = CSV COMPRESSION = gzip);

┌────────────────────────────────────────────┐
│ rows_unloaded │ input_bytes │ output_bytes │
├───────────────┼─────────────┼──────────────┤
│            10 │         182 │          168 │
└────────────────────────────────────────────┘

LIST @my_internal_stage;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                              name                              │  size  │        md5       │         last_modified         │      creator     │
├────────────────────────────────────────────────────────────────┼────────┼──────────────────┼───────────────────────────────┼──────────────────┤
│ data_7970afa5-32e3-4e7d-b793-e42a2a82a8e6_0000_00000000.csv.gz │    168 │ NULL             │ 2024-01-18 16:27:01.663 +0000 │ NULL             │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

-- COPY INTO also works with custom file formats. See below:
-- Create a custom file format named my_csv_gzip with CSV format and gzip compression
CREATE FILE FORMAT my_csv_gzip TYPE = CSV COMPRESSION = gzip;

-- Unload data from the table to the stage using the custom file format my_csv_gzip
COPY INTO @my_internal_stage
    FROM canadian_city_population
    FILE_FORMAT = (FORMAT_NAME = 'my_csv_gzip');

┌────────────────────────────────────────────┐
│ rows_unloaded │ input_bytes │ output_bytes │
├───────────────┼─────────────┼──────────────┤
│            10 │         182 │          168 │
└────────────────────────────────────────────┘

LIST @my_internal_stage;

┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                              name                              │  size  │        md5       │         last_modified         │      creator     │
├────────────────────────────────────────────────────────────────┼────────┼──────────────────┼───────────────────────────────┼──────────────────┤
│ data_d006ba1c-0609-46d7-a67b-75c7078d86ff_0000_00000000.csv.gz │    168 │ NULL             │ 2024-01-18 16:29:29.721 +0000 │ NULL             │
│ data_7970afa5-32e3-4e7d-b793-e42a2a82a8e6_0000_00000000.csv.gz │    168 │ NULL             │ 2024-01-18 16:27:01.663 +0000 │ NULL             │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

    例 3: バケットへのアンロード (unload)

    この例では、データを MinIO 上のバケットにアンロードします。

    -- Unload data from the table to a bucket named 'lake' on MinIO using the PARQUET file format
COPY INTO 's3://lake'
    CONNECTION = (
    ENDPOINT_URL = 'http://localhost:9000/',
    ACCESS_KEY_ID = 'ROOTUSER',
    SECRET_ACCESS_KEY = 'CHANGEME123',
    region = 'us-west-2'
    )
    FROM canadian_city_population
    FILE_FORMAT = (TYPE = PARQUET);

┌────────────────────────────────────────────┐
│ rows_unloaded │ input_bytes │ output_bytes │
├───────────────┼─────────────┼──────────────┤
│            10 │         211 │          572 │
└────────────────────────────────────────────┘

    例 4: PARTITION BY を使用したアンロード (unload)

    この例では、導出式に基づいてデータをパーティション化されたフォルダにアンロードします。

    -- Create a sample table
CREATE TABLE sales_data (
    sale_date DATE,
    region VARCHAR,
    amount INT
);

INSERT INTO sales_data VALUES
    ('2025-01-15', 'east', 100),
    ('2025-01-20', 'west', 200),
    ('2025-02-10', 'east', 150),
    (NULL, 'west', 50);

-- Create an internal stage
CREATE STAGE partitioned_stage;

-- Unload data partitioned by year-month derived from sale_date
-- When sale_date is NULL, to_varchar() returns NULL, so the entire
-- concatenation evaluates to NULL and the row lands in the _NULL_ folder.
COPY INTO @partitioned_stage
    FROM sales_data
    PARTITION BY ('month=' || to_varchar(sale_date, 'YYYY-MM'))
    FILE_FORMAT = (TYPE = PARQUET);

-- Verify the partitioned folder layout
SELECT name FROM list_stage(location => '@partitioned_stage') ORDER BY name;

┌──────────────────────────────────────────────────────────────────┐
│                              name                                │
├──────────────────────────────────────────────────────────────────┤
│ _NULL_/data_<query_id>_0000_00000000.parquet                     │
│ month=2025-01/data_<query_id>_0000_00000000.parquet              │
│ month=2025-02/data_<query_id>_0000_00000000.parquet              │
└──────────────────────────────────────────────────────────────────┘

    パーティション式の評価結果が NULL の場合、データは _NULL_ フォルダに配置されます。各一意のパーティション値ごとに、それぞれ対応するデータファイルを含む独自のサブフォルダが作成されます。

    例 5: Lance データセットへのアンロード (unload)

    この例では、データを単独のファイルではなく、Lance データセットディレクトリとしてアンロードします。

    CREATE STAGE ml_stage;

COPY INTO @ml_stage/datasets/train
FROM (
    SELECT number, number + 1 AS label
    FROM numbers(10)
)
FILE_FORMAT = (TYPE = LANCE)
USE_RAW_PATH = TRUE
OVERWRITE = TRUE
DETAILED_OUTPUT = TRUE;

    出力パスには、次のようなエントリを含む Lance データセットのレイアウトが作成されます。

    datasets/train/_versions/...
datasets/train/data/... .lance
datasets/train/*.manifest

    Python の lance を使用した検証を含む、完全なエンドツーエンドの例については、Lance データセットのアンロード を参照してください。

    このページは役に立ちましたか？