バージョン: User Guides (Cloud)

[説明] このページは機械翻訳された日本語版です。内容に誤りがございましたら、報告していただけると助かります。

データのマージ
Private Preview

既存のZilliz Cloudコレクションのデータと、ローカルファイルまたは外部オブジェクトストレージバケットのデータをマージして、両方のソースのデータを組み合わせたコレクションを作成できます。これはデータマージ操作と呼ばれ、既存のコレクションにデータを持つフィールドを追加する回避策として使用できます。

📘Notes

この機能は現在、プライベートプレビュー段階です。この機能にご興味があり、お試しになりたい場合は、お気軽にZilliz Cloudサポートまでお問い合わせください。

概要

データマージ操作は、リレーショナルデータベースのLEFT JOIN操作に似ており、コレクションのデータと指定されたデータソースからのすべての一致するレコードを結合し、マージされたデータを新しいコレクションに保存します。

データソースは、Zilliz Cloudボリュームまたはオブジェクトストレージバケットに保存されているPARQUETファイルのセットである必要があります。

次の図に示すように、idフィールドを主キーとする3つのフィールドを含むコレクションがあります。さらに、idとdateという2つのフィールドを持つPARQUETファイルがあります。idフィールドはマージキーとして機能し、その値はソースコレクションの値と一致する必要があります。dateフィールドは追加されるフィールドです。

Gfduwu9hGh8CGkbcJ1JccREunRf

PARQUETファイルをZilliz Cloudボリュームまたはオブジェクトストレージバケットにアップロードすると、Merge データ APIを使用して、両方のソースのデータを保存するターゲットコレクションを作成できます。

データソースはオプションです。データソースを指定せずにMerge データ APIを使用して、既存のコレクションにフィールドを追加する回避策として使用することもできます。

このガイドでは、Merge データ APIを使用して、データの有無にかかわらずフィールドを追加する方法を説明します。

データを持つフィールドの追加

データを持つフィールドを追加するには、ソースコレクション、データソース、およびターゲットコレクションに追加する新しいフィールドを指定する必要があります。

データソースは、Zilliz CloudボリュームまたはAWS S3バケットのいずれかにあるPARQUETファイルのセットである必要があります。

ボリュームの使用

ボリュームを使用してデータマージ操作を実行するには、まずボリュームを作成し、ローカルファイルシステムからデータをアップロードします。それが完了したら、データマージ操作を実行して、既存のコレクションとボリュームの両方からデータを結合した新しいコレクションを作成できます。

次のコードスニペットは、ボリュームを使用してデータマージ操作を実行する方法を示しています。ボリュームの作成方法とデータのアップロード方法の詳細については、ステージの管理を参照してください。

export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/etl/merge" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "clusterId": "in00-xxxxxxxxxxxxxxx",
    "dbName": "my_database",
    "collectionName": "my_collection",
    "destDbName": "my_database",
    "destCollectionName": "my_merged_collection",
    "dataSource": {
        "type": "volume",
        "volumeName": "my_volume",
        "dataPath": "path/to/your/parquet.parquet"
    },
    "mergeField": "id",
    "newFields": [
        {
            "fieldName": "date",
            "dataType": "VARCHAR",
            "params": {
                "maxLength": 10
            }
        }
    ]
}'

上記のコマンドを実行する前に、注意すべきフィールドがいくつかあります。

dbName と collectionName

これらの2つのパラメータは、データマージ操作のソースコレクションを決定します。
destDbName と destCollectionName

これらの2つのパラメータは、データマージ操作後に生成されるターゲットコレクションを決定します。ターゲットコレクションは、ソースコレクションと同じクラスター内にある必要があります。
dataSource

このパラメータはオプションで、データソースタイプや、列指向データを含むParquetファイルへのパスなど、データソース設定が含まれます。これらのデータは、ソースコレクションのデータとマージされ、ターゲットコレクションに保存されます。

ボリュームを中間ストレージとして使用する場合、type を volume に設定した後、volumeName と dataPath を設定する必要があります。
📘Notes
- dataPath パラメータの値は、ボリュームのルートからのファイルの絶対パス、または複数のParquetファイルを含むボリューム内のフォルダのいずれかです。値がフォルダを指す場合、フォルダ内のParquetファイルが同じデータ構造であることを確認してください。
例えば、値は path/to/your/file.parquet (ファイル) または path/to/your/folder/ (フォルダ) のようになります。
- データなしでフィールドを追加したいだけであれば、このパラメータを指定しないことも可能です。
mergeField

データマージ操作は、リレーショナルデータベースシステムのLEFT JOIN操作に似ており、マージフィールドはソースコレクションと列指向データを含むParquetファイル間の共有キーとして機能します。
newFields

これは、データマージ操作後にターゲットコレクションに追加するフィールドのスキーマのリストです。サポートされているデータ型は、VARCHAR、INT8、INT16、INT32、INT64、FLOAT、DOUBLE、およびBOOLです。

上記のコマンドは、データマージジョブを作成し、そのIDを返します。

{
    "code": 0,
    "data": {
        "jobId": "job-xxxxxxxxxxxxxxxxxxxxx"
    }
}

オブジェクトストレージを使用する

オブジェクトストレージバケットを使用してデータマージ操作を実行するには、まずオブジェクトストレージバケットを作成し、そこにデータをアップロードします。それが完了したら、データマージ操作を実行して、既存のコレクションとバケットの両方からのデータを組み合わせた新しいコレクションを作成できます。

次のコードスニペットは、オブジェクトストレージバケットを使用してデータマージ操作を実行する方法を示しています。バケットを作成し、そこにデータをアップロードする方法については、ブロックストレージサービスプロバイダーのドキュメントを参照してください。

export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/etl/merge" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "clusterId": "in00-xxxxxxxxxxxxxxx",
    "dbName": "my_database",
    "collectionName": "my_collection",
    "destDbName": "my_database",
    "destCollectionName": "my_merged_collection",
    "dataSource": {
        "type": "s3",
        "dataPath": "s3://my_bucket/path/to/your/parquet.parquet",
        "credential": {
            "accessKey": "xxxx",
            "secretKey": "xxxx"
        }
    },
    "mergeField": "id",
    "newFields": [
        {
            "fieldName": "date",
            "dataType": "VARCHAR",
            "params": {
                "maxLength": 10
            }
        }
    ]
}'

上記のコマンドを実行する前に、注意すべきフィールドがいくつかあります。

dbName および collectionName

これら2つのパラメータは、データマージ操作のソースコレクションを決定します。
destDbName および destCollectionName

これら2つのパラメータは、データマージ操作後に生成されるターゲットコレクションを決定します。ターゲットコレクションは、ソースコレクションと同じクラスター内にある必要があります。
dataSource

このパラメータはオプションで、データソースタイプや、列指向データを含むParquetファイルへのパスなど、データソース設定が含まれます。このデータはソースコレクションのデータとマージされ、ターゲットコレクションに保存されます。

S3互換のオブジェクトストレージバケットを中間ストレージとして使用する場合、typeをs3に設定した後、dataPathとcredentialを設定する必要があります。
📘Notes
- dataPathパラメータの値は、バケットのルートからのファイルの絶対パス、または複数のParquetファイルを含むバケット内のフォルダのいずれかです。値がフォルダを指す場合、フォルダ内のParquetファイルが同じデータ構造であることを確認してください。
例えば、値はs3://path/to/your/file.parquet（ファイル）またはs3://path/to/your/folder/（フォルダ）のようになります。
- データなしでフィールドを追加したい場合は、このパラメータを未指定のままにすることができます。
mergeField

データマージ操作は、リレーショナルデータベースシステムのLEFT JOIN操作に似ており、マージフィールドはソースコレクションと列指向データを含むParquetファイル間の共有キーとして機能します。
newFields

これは、データマージ操作後にターゲットコレクションに追加するフィールドのスキーマのリストです。サポートされるデータ型は、VARCHAR、INT8、INT16、INT32、INT64、FLOAT、DOUBLE、およびBOOLです。

上記のコマンドは、データマージジョブを作成し、そのIDを返します。

{
    "code": 0,
    "data": {
        "jobId": "job-xxxxxxxxxxxxxxxxxxxxx"
    }
}

データなしでフィールドを追加する

既存のコレクションにフィールドを追加する回避策として、Merge データ API を使用することもできます。この場合、データソースを設定する必要はありません。

export BASE_URL="https://api.cloud.zilliz.com"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/etl/merge" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "clusterId": "in00-xxxxxxxxxxxxxxx",
    "dbName": "my_database",
    "collectionName": "my_collection",
    "destDbName": "my_database",
    "destCollectionName": "my_merged_collection",
    "mergeField": "id",
    "newFields": [
        {
            "fieldName": "date",
            "dataType": "VARCHAR",
            "params": {
                "maxLength": 10
            }
        }
    ]
}'

上記のコマンドはデータマージジョブを作成し、そのIDを返します。

{
    "code": 0,
    "data": {
        "jobId": "job-xxxxxxxxxxxxxxxxxxxxx"
    }
}

結果の検証

データマージジョブのIDを取得した後、ジョブの記述またはプロジェクトジョブの管理に記載されている手順を使用して、そのステータスを詳細に確認できます。

データマージジョブが完了したら、ターゲットコレクションのスキーマとターゲットコレクション内のエンティティ数が期待どおりであるかを確認できます。

トラブルシューティング

Parquetファイルの行に、ソースコレクション内のどのエンティティとも一致しないマージキーがある場合、どのように処理すればよいですか？

リレーショナルデータベースシステムの左結合操作と同様に、データマージ操作は、ソースコレクションのすべての行と、指定されたParquetファイルの一致する行を結合します。これにより、ソースのすべてのフィールド、newFieldsで定義されたフィールド、および結合されたデータを含む新しい宛先コレクションが作成されます。

ソースコレクション内のマージキーと一致するParquetファイルの行のみがマージされます。マージキーがソースコレクション内のどのエンティティとも一致しない行はスキップされます。Parquetファイルのどの行もどのエンティティとも一致しない場合、newFieldsで指定されたフィールドのみが、設定されていればnull値で作成されます。

概要​

データを持つフィールドの追加​

ボリュームの使用​

オブジェクトストレージを使用する​

データなしでフィールドを追加する​

結果の検証​

トラブルシューティング​

概要