Lance データセットのアンロード

Lance エクスポートは、機械学習やベクトルワークフローのような、データセット指向の利用者を対象としています。CSV、TSV、NDJSON、Parquet のアンロードとは異なり、TiDB Cloud Lake は .lance データファイルに加えて、_versions/ などのメタデータを含む Lance のデータセットディレクトリを書き出します。

構文:

COPY INTO { internalStage | externalStage | externalLocation }
FROM { [<database_name>.]<table_name> | ( <query> ) }
FILE_FORMAT = (TYPE = LANCE)
[MAX_FILE_SIZE = <num>]
[USE_RAW_PATH = true | false]
[OVERWRITE = true | false]
[DETAILED_OUTPUT = true | false]

• Lance は COPY INTO <location> でのみサポートされます。
• SINGLE と PARTITION BY は Lance ではサポートされません。
• USE_RAW_PATH = false（デフォルト）の場合、TiDB Cloud Lake はターゲットパスにクエリ ID を付加するため、各エクスポートはそれぞれ専用のデータセットのルートを持ちます。
• Python の lance など、後続のリーダー向けに安定したデータセット URI が必要な場合は、USE_RAW_PATH = true を設定します。
• 構文の詳細は COPY INTO location を参照してください。
• Lance の動作に関する詳細な注意事項は 入出力ファイル形式 に記載されています。

チュートリアル

この例では、小規模な文書分類データセットを作成します。生のテキストファイルは stage に保存され、READ_FILE によってクエリ実行時に BINARY 値へ変換され、TiDB Cloud Lake が最終的なデータセットを Python 利用者向けに Lance 形式でエクスポートします。

前提条件

TiDB Cloud Lake と Python 環境の両方からアクセス可能な、S3 互換のバケットを用意します。

ステップ 1. 外部 stage を作成する

CREATE OR REPLACE STAGE ml_assets
URL = 's3://your-bucket/lance-demo/'
CONNECTION = (
    ENDPOINT_URL = '<your-endpoint-url>',
    ACCESS_KEY_ID = '<your-access-key-id>',
    SECRET_ACCESS_KEY = '<your-secret-access-key>',
    REGION = '<your-region>'
);

ステップ 2. サンプルソースファイルを作成する

stage に 3 つの生テキストファイルを作成します。

COPY INTO @ml_assets/raw/ticket_001.txt
FROM (SELECT 'customer asked for a refund after the package arrived damaged')
FILE_FORMAT = (TYPE = CSV FIELD_DELIMITER = '|' RECORD_DELIMITER = '\n')
SINGLE = TRUE
USE_RAW_PATH = TRUE
OVERWRITE = TRUE;

COPY INTO @ml_assets/raw/ticket_002.txt
FROM (SELECT 'customer praised the fast response and confirmed the issue was resolved')
FILE_FORMAT = (TYPE = CSV FIELD_DELIMITER = '|' RECORD_DELIMITER = '\n')
SINGLE = TRUE
USE_RAW_PATH = TRUE
OVERWRITE = TRUE;

COPY INTO @ml_assets/raw/ticket_003.txt
FROM (SELECT 'customer requested escalation because the replacement order was delayed')
FILE_FORMAT = (TYPE = CSV FIELD_DELIMITER = '|' RECORD_DELIMITER = '\n')
SINGLE = TRUE
USE_RAW_PATH = TRUE
OVERWRITE = TRUE;

ステップ 3. マニフェストテーブルを作成する

CREATE OR REPLACE TABLE support_ticket_manifest (
    ticket_id INT,
    label STRING,
    file_path STRING
);

INSERT INTO support_ticket_manifest VALUES
    (1, 'refund', 'raw/ticket_001.txt'),
    (2, 'resolved', 'raw/ticket_002.txt'),
    (3, 'escalation', 'raw/ticket_003.txt');

ステップ 4. データセットを Lance にエクスポートする

READ_FILE は stage 上のテキストファイルを生バイト列として読み取ります。その後、COPY INTO がそれらの行を Lance データセットに書き込みます。

COPY INTO @ml_assets/datasets/support-ticket-train
FROM (
    SELECT
        ticket_id,
        label,
        file_path,
        READ_FILE('@ml_assets', file_path) AS content
    FROM support_ticket_manifest
    ORDER BY ticket_id
)
FILE_FORMAT = (TYPE = LANCE)
USE_RAW_PATH = TRUE
OVERWRITE = TRUE
DETAILED_OUTPUT = TRUE;

結果:

┌───────────────────────────────────────────────────────────────┐
│ file_name                          │ file_size │ row_count   │
├────────────────────────────────────┼───────────┼─────────────┤
│ datasets/support-ticket-train      │ ...       │ 3           │
└───────────────────────────────────────────────────────────────┘

ステップ 5. エクスポートされたデータセットのレイアウトを確認する

LIST @ml_assets/datasets/support-ticket-train;

次のようなパスを含むデータセットディレクトリが表示されます。

datasets/support-ticket-train/_versions/...
datasets/support-ticket-train/data/... .lance
datasets/support-ticket-train/*.manifest

ステップ 6. Python lance で検証する

Python パッケージをインストールします。

pip install pylance

同じオブジェクトストレージの場所から、エクスポートされたデータセットを読み取ります。

import os
import lance

storage_options = {
    "aws_access_key_id": os.environ["AWS_ACCESS_KEY_ID"],
    "aws_secret_access_key": os.environ["AWS_SECRET_ACCESS_KEY"],
    "region": os.environ.get("AWS_REGION", "us-east-1"),
}

if endpoint := os.environ.get("AWS_ENDPOINT_URL"):
    storage_options["aws_endpoint"] = endpoint
    storage_options["aws_allow_http"] = "true" if endpoint.startswith("http://") else "false"

dataset = lance.dataset(
    "s3://your-bucket/lance-demo/datasets/support-ticket-train",
    storage_options=storage_options,
)

table = dataset.to_table()
print(table.num_rows)
print(table["label"].to_pylist())
print(table["content"].to_pylist()[0].decode("utf-8").strip())

想定される出力:

3
['refund', 'resolved', 'escalation']
customer asked for a refund after the package arrived damaged

これで、ラベル、元のパス、生ファイルのバイト列をまとめて保持する完全な Lance データセットが作成され、後続の ML 処理で利用できるようになります。