メインコンテンツまでスキップ

External Collection の作成

External Collection は Zilliz Cloud のデータ collection の一種で、AWS S3 や Iceberg などの外部ストレージシステムやデータベーステーブルから、データを Zilliz Cloud にコピーせずにアクセスします。これは、Zilliz Cloud のクエリインターフェースとの互換性を維持しながら、データレイク上のクエリレイヤーとして機能します。

概要​

一般的な AI データパイプラインでは、ユーザーはすでに AWS S3 などのストレージシステム上に Parquet やその他の形式でデータを保存している場合があります。Zilliz Cloud がこの外部保存データを利用できるようにするには、通常、Extract-Transform-Load（ETL）パイプラインを使用して Zilliz Cloud 独自のストレージにインポートする必要があります。

この「データを Zilliz Cloud に持ち込む」ワークフローでは、同期が難しい冗長なデータが作成され、データ整合性を確保するためのエンジニアリング保守負担も増加します。

YQXWwPQ3vheYa4b8398cWoPNnyN

これらの問題を解決するために、Zilliz Cloud は External Collection を提供しています。これにより、データ同期や ETL パイプラインを気にすることなく、Zilliz Cloud から外部保存データにアクセスできます。

Q6F4wtcd2h3PnKbnMxncw3urn3f

作成後、External Collection はデータに直接アクセスし、保存場所をそのまま維持できます。バックグラウンドでは、Zilliz Cloud がマニフェストファイルを作成して、Zilliz Cloud のメタデータと外部データファイル内の行との対応関係を記録します。マニフェストファイルの準備が完了すると、他の管理対象 collection と同様に、External Collection 内に index を作成できます。

データが変更された場合は、手動でサブ秒の refresh をトリガーすることでメタデータが更新され、Zilliz Cloud を常に最新の状態に保てます。

External Collection は、オンデマンドコンピューティング用 database で利用できます。

ステップ 1: schema の作成​

管理対象 collection を作成する場合と同様に、External Collection を作成する前にも schema を作成する必要があります。ただし、この schema は管理対象 collection のものとは少し異なります。

準備​

  • オンデマンドコンピューティング用 database に External Collection を作成するのに十分な権限を持つ API key を取得していること。

    詳細は API Keys を参照してください。

  • オブジェクトストレージ bucket を Zilliz Cloud と統合していること。

    詳細は AWS、GCP、Azure のドキュメントを参照してください。

  • bucket 統合から external volume を作成済みであること。volume に対象のデータファイルが含まれていることを確認してください。

    詳細は External Volumes を参照してください。

サポートされるデータソース​

Zilliz Cloud は以下のデータソースをサポートしており、選択した形式に応じて対応する external source を指定する必要があります。

  • parquet

    external_source を、対象の Parquet ファイルを含むフォルダに設定します。

  • vortex,

    external_source を、バージョン 0.56 の Vortex columnar ファイルを含むフォルダに設定します。

  • lance-table

    external_source を、_transactions、_versions、data などのサブフォルダを含むフォルダパスに設定します。

  • iceberg-table

    external_source を Iceberg table の metadata.json ファイルに設定し、以下のように snapshot ID を渡します。

    python
    external_spec={
        "format": "iceberg-table",
        "snapshot_id": "473984310232959286"
    }

  • milvus-table

    external_source を具体的な Milvus snapshot metadata JSON ファイルに設定します。詳細は Use Snapshot as Data Source を参照してください。

schema の設定​

対象のデータファイルを含む external volume を用意したら、collection の列を Parquet ファイル（parquet）、lance table（lance-table）、Iceberg table（iceberg-table）、または 0.56.0 形式の Vortex ファイル（vortex）にマッピングする schema を作成します。

📘注意

external source は、これがフォルダであることを示すために末尾をスラッシュ（/）で終える必要があります。

python
from pymilvus import MilvusClient, DataType

schema = MilvusClient.create_schema(
    external_source='volume://my_volume/path/to/a/folder/',
    external_spec='{"format": "parquet"}'
)

ステップ 2: フィールドの追加​

schema の準備ができたら、以下のようにフィールドを追加できます。

python
schema.add_field(
    field_name="product_id",
    datatype=DataType.INT64,
    # highlight-next
    external_field="id" # field name in the external data file
)
schema.add_field(
    field_name="product_name",
    datatype=DataType.VARCHAR,
    max_length=512,
    # highlight-next
    external_field="name"
)
schema.add_field(
    field_name="embedding",
    datatype=DataType.FLOAT_VECTOR,
    dim=768,
    # highlight-next
    external_field="vector"
)

ステップ 3: collection の作成​

schema にすべてのフィールドを追加したら、External Collection を作成できます。

📘注意

External Collection は、通常オンデマンド cluster に関連付けられている、プロジェクトレベルの database に作成できます。

python
# connect the database
client = MilvusClient(
    uri="https://{project-id}.{region}.vectordb.zillizcloud.com",
    token="YOUR_API_KEY"
)

client.use_database(
    db_name="my_database"
)
# create the collection
client.create_collection(
    collection_name="test_collection",
    schema=schema
)

ステップ 4: index の作成​

管理対象 collection の場合と同様に、External Collection の列に対しても index を作成できます。

python
index_params = client.prepare_index_params()
# Add indexes
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",
    metric_type="COSINE"
)
index_params.add_index(
    field_name="product_name",
    index_type="AUTOINDEX"
)
client.create_index(
    db_name="my_database",
    collection_name="test_collection",
    index_params=index_params
)

ステップ 5: データの refresh​

collection の準備ができたら、refresh を実行して、データのメタデータと index を作成します。

python
job_id = client.refresh_external_collection(
    db_name="my_database",
    collection_name="test_collection"
)
while True:
    progress = client.get_refresh_external_collection_progress(job_id=job_id)
    print(f"  {progress.state}: {progress.progress}%")
    if progress.state == "RefreshCompleted":
        elapsed = progress.end_time - progress.start_time
        print(f"  Completed in {elapsed}ms")
        break
    elif progress.state == "RefreshFailed":
        print(f"  Failed: {progress.reason}")
        break
    time.sleep(2)

refresh 操作は非同期であるため、その進行状況を監視するための反復処理を設定する必要があります。

📘注意

  • refresh 操作では、データファイルのメタデータをスキャンし、それに応じてマニフェストファイルを生成します。通常は 150～250 ms かかります。

  • マニフェストファイルには、Milvus 内のメタデータと外部ファイル内の行とのマッピングが記録されます。

  • ソースデータに更新があった場合、Zilliz Cloud を最新状態に保つために、再度手動で refresh を呼び出す必要があります。

  • 挿入を伴わず、アクティブなメタデータをすべて削除する必要がある refresh は拒否されます。

  • オンデマンドコンピューティング用 database 内の External Collection については、手動で load や release を行う必要はありません。

Follow-ups​

外部 collection を更新すると、オンデマンドコンピューティング用データベース内の collection は検索およびクエリのためにオンデマンド cluster にアタッチする必要がある点を除き、他の任意のマネージド collection と同様に、外部 collection で類似検索やクエリを実行できます。詳細については、Create On-Demand Cluster およびその関連ページを参照してください。

search、query、get、hybrid search などの DQL 操作を実行する前に、オンデマンド cluster のコンピュートリソースをアタッチするための session を作成する必要があります。詳細については、On-Demand DQL Operations を参照してください。

ソースとしての Snapshot

Milvus snapshot から external collection を作成するには、snapshot metadata JSON path を `externalsource` として使用し、`externalspec.format` を `"milvus-table"` に設定します。 | Cloud

Ctrl I