Partition Key を使用する

Partition Key は、collection の namespace として機能することで論理的なデータ分離を可能にする検索最適化ソリューションです。特定の scalar フィールド（tenant ID やプロジェクト名など）を Partition Key として指定することで、単一の collection 内のデータを個別の namespace に効果的に分割できます。これにより、検索リクエストはフィルタリング条件を通じて特定の namespace に限定でき、検索範囲を大幅に狭めて全体的な効率を向上させることができます。この記事では、この namespace ベースの最適化を実装する方法と、Partition Key を使用する際の考慮事項を紹介します。

概要

Zilliz Cloud では、partition を使用してデータ分離を実装し、検索範囲を特定の partition に制限することで検索パフォーマンスを向上させることができます。partition を手動で管理する場合、1 つの collection に最大 1,024 個の partition を作成でき、特定のルールに基づいて entity をこれらの partition に挿入することで、検索を特定数の partition 内に制限して検索範囲を狭めることができます。

Zilliz Cloud は、1 つの collection に作成できる partition 数の制限を克服するために、データ分離において partition を再利用できるよう Partition Key を導入しています。collection の作成時に、scalar フィールドを Partition Key として使用できます。collection の準備ができると、Zilliz Cloud は collection 内に指定された数の partition を作成します。entity の挿入を受け取ると、Zilliz Cloud はその entity の Partition Key 値を使ってハッシュ値を計算し、そのハッシュ値と collection の partitions_num プロパティに基づいて剰余演算を行い、対象の partition ID を取得して、その entity を対象 partition に保存します。

IXXIwZdOYhRFXmbTMdwcaN6fnPe

次の図は、Partition Key 機能が有効な collection と無効な collection で、Zilliz Cloud が検索リクエストをどのように処理するかを示しています。

Partition Key が無効な場合、Zilliz Cloud は collection 内でクエリ vector に最も類似した entity を検索します。最も関連性の高い結果を含む partition がわかっている場合は、検索範囲を狭めることができます。
Partition Key が有効な場合、Zilliz Cloud は検索フィルタで指定された Partition Key 値に基づいて検索範囲を決定し、一致する partition 内の entity のみをスキャンします。

RTaqwdaWXhRWPTb4uJTc9Uknn5c

Partition Key を使用する

Partition Key を使用するには、以下が必要です。

Partition Key を設定する

scalar フィールドを Partition Key として指定するには、その scalar フィールドを追加するときに is_partition_key 属性を true に設定する必要があります。

📘注意

scalar フィールドを Partition Key として設定すると、そのフィールド値を空または null にすることはできません。

python
from pymilvus import (
    MilvusClient, DataType
)

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

schema = client.create_schema()

schema.add_field(field_name="id",
    datatype=DataType.INT64,
    is_primary=True)
    
schema.add_field(field_name="vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=5)

# Add the partition key
schema.add_field(
    field_name="my_varchar", 
    datatype=DataType.VARCHAR, 
    max_length=512,
    is_partition_key=True,
)

java
import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("YOUR_CLUSTER_ENDPOINT")
        .token("YOUR_CLUSTER_TOKEN")
        .build());

// Create schema
CreateCollectionReq.CollectionSchema schema = client.createSchema();

schema.addField(AddFieldReq.builder()
        .fieldName("id")
        .dataType(DataType.Int64)
        .isPrimaryKey(true)
        .build());

schema.addField(AddFieldReq.builder()
        .fieldName("vector")
        .dataType(DataType.FloatVector)
        .dimension(5)
        .build());
        
// Add the partition key
schema.addField(AddFieldReq.builder()
        .fieldName("my_varchar")
        .dataType(DataType.VarChar)
        .maxLength(512)
        .isPartitionKey(true)
        .build());

go
import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/column"
    "github.com/milvus-io/milvus/client/v2/entity"
    "github.com/milvus-io/milvus/client/v2/index"
    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

milvusAddr := "YOUR_CLUSTER_ENDPOINT"
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

schema := entity.NewSchema().WithDynamicFieldEnabled(false)
schema.WithField(entity.NewField().
    WithName("id").
    WithDataType(entity.FieldTypeInt64).
    WithIsPrimaryKey(true),
).WithField(entity.NewField().
    WithName("my_varchar").
    WithDataType(entity.FieldTypeVarChar).
    WithIsPartitionKey(true).
    WithMaxLength(512),
).WithField(entity.NewField().
    WithName("vector").
    WithDataType(entity.FieldTypeFloatVector).
    WithDim(5),
)

javascript
import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "YOUR_CLUSTER_ENDPOINT";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});

// 3. Create a collection in customized setup mode
// 3.1 Define fields
const fields = [
  {
    name: 'id',
    data_type: DataType.Int64,
    is_primary_key: true,
  },
  {
    name: 'vector',
    data_type: DataType.FloatVector,
    dim: 5,
  },
  {
    name: 'my_varchar',
    data_type: DataType.VarChar,
    max_length: 512,
    is_partition_key: true,
  },
];

bash
export schema='{
        "autoId": true,
        "enabledDynamicField": false,
        "fields": [
            {
                "fieldName": "id",
                "dataType": "Int64",
                "isPrimary": true
            },
            {
                "fieldName": "vector",
                "dataType": "FloatVector",
                "elementTypeParams": {
                    "dim": "5"
                }
            },
            {
                "fieldName": "my_varchar",
                "dataType": "VarChar",
                "isPartitionKey": true,
                "elementTypeParams": {
                    "max_length": 512
                }
            }
        ]
    }'

c++
#include "milvus/MilvusClientV2.h"

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"YOUR_CLUSTER_ENDPOINT", "YOUR_CLUSTER_TOKEN"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

milvus::CollectionSchemaPtr schema = std::make_shared<milvus::CollectionSchema>();
schema->AddField({"id", milvus::DataType::INT64, "", true, true});
schema->AddField(milvus::FieldSchema("vector", milvus::DataType::FLOAT_VECTOR).WithDimension(5));
schema->AddField(milvus::FieldSchema("my_varchar", milvus::DataType::VARCHAR).WithPartitionKey(true).WithMaxLength(512));

partition 数を設定する

collection 内の scalar フィールドを Partition Key として指定すると、Zilliz Cloud は collection 内に自動的に 16 個の partition を作成します。entity を受け取ると、Zilliz Cloud はその entity の Partition Key 値に基づいて partition を選択し、その partition に entity を保存します。その結果、一部またはすべての partition に、異なる Partition Key 値を持つ entity が格納されることになります。

また、collection とあわせて作成する partition 数を指定することもできます。これは、scalar フィールドが Partition Key として指定されている場合にのみ有効です。

python
client.create_collection(
    collection_name="my_collection",
    schema=schema,
    num_partitions=128
)

java
import io.milvus.v2.service.collection.request.CreateCollectionReq;

CreateCollectionReq createCollectionReq = CreateCollectionReq.builder()
                .collectionName("my_collection")
                .collectionSchema(schema)
                .numPartitions(128)
                .build();
        client.createCollection(createCollectionReq);

go
err = client.CreateCollection(ctx,
    milvusclient.NewCreateCollectionOption("my_collection", schema).
        WithNumPartitions(128))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

javascript
await client.create_collection({
    collection_name: "my_collection",
    schema: schema,
    num_partitions: 128
})

bash
export params='{
    "partitionsNum": 128
}'

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d "{
    \"collectionName\": \"my_collection\",
    \"schema\": $schema,
    \"params\": $params
}"

c++
auto status = client->CreateCollection(milvus::CreateCollectionRequest()
                                          .WithCollectionName("my_collection")
                                          .WithCollectionSchema(schema)
                                          .WithNumPartitions(128));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

フィルタリング条件を作成する

Partition Key 機能が有効な collection で ANN 検索を実行する場合、検索リクエストに Partition Key を含むフィルタリング式を含める必要があります。フィルタリング式では、Partition Key 値を特定の範囲に制限できるため、Zilliz Cloud は対応する partition 内に検索範囲を制限できます。

削除操作を実行する場合は、より効率的な削除を実現するために、単一の partition key を指定するフィルタ式を含めることを推奨します。この方法では削除操作を特定の partition に限定できるため、compaction 中の write amplification を低減し、compaction と indexing のためのリソースを節約できます。

次の例では、特定の Partition Key 値および複数の Partition Key 値の集合に基づく、Partition Key ベースのフィルタリングを示します。

python
# Filter based on a single partition key value, or
filter='partition_key == "x" && <other conditions>'

# Filter based on multiple partition key values
filter='partition_key in ["x", "y", "z"] && <other conditions>'

java
// Filter based on a single partition key value, or
String filter = "partition_key == 'x' && <other conditions>";

// Filter based on multiple partition key values
String filter = "partition_key in ['x', 'y', 'z'] && <other conditions>";

go
// Filter based on a single partition key value, or
filter = "partition_key == 'x' && <other conditions>"

// Filter based on multiple partition key values
filter = "partition_key in ['x', 'y', 'z'] && <other conditions>"

javascript
// Filter based on a single partition key value, or
const filter = 'partition_key == "x" && <other conditions>'

// Filter based on multiple partition key values
const filter = 'partition_key in ["x", "y", "z"] && <other conditions>'

bash
# Filter based on a single partition key value, or
export filter='partition_key == "x" && <other conditions>'

# Filter based on multiple partition key values
export filter='partition_key in ["x", "y", "z"] && <other conditions>'

c++

const auto filter = R"(partition_key == 'x' && <other conditions>)";
const auto filter = R"(partition_key in ['x', 'y', 'z'] && <other conditions>)";

📘注意

partition_key は、partition key として指定されたフィールド名に置き換える必要があります。

Partition Key Isolation を使用する

マルチテナンシーのシナリオでは、tenant ID に関連する scalar フィールドを partition key として指定し、この scalar フィールド内の特定の値に基づくフィルタを作成できます。類似したシナリオで検索パフォーマンスをさらに向上させるため、Zilliz Cloud は Partition Key Isolation 機能を導入しています。

BVotwv5BvhBWXXbvotUccowZnng

上図のとおり、Zilliz Cloud は Partition Key 値に基づいて entity をグループ化し、それぞれのグループごとに個別の index を作成します。検索リクエストを受け取ると、Zilliz Cloud はフィルタリング条件で指定された Partition Key 値に基づいて index を特定し、その index に含まれる entity 内に検索範囲を制限します。これにより、検索中に無関係な entity をスキャンすることを避け、検索パフォーマンスを大幅に向上させます。

Partition Key Isolation を有効にした後は、Partition-key-based filter に含めることができるのは 1 つの特定値のみです。これにより、Zilliz Cloud は一致する index に含まれる entity 内に検索範囲を制限できます。

Partition Key Isolation を有効にする

以下のコード例は、Partition Key Isolation を有効にする方法を示しています。

python
client.create_collection(
    collection_name="my_collection",
    schema=schema,
    properties={"partitionkey.isolation": True}
)

java
import io.milvus.v2.service.collection.request.CreateCollectionReq;

Map<String, String> properties = new HashMap<>();
properties.put("partitionkey.isolation", "true");

CreateCollectionReq createCollectionReq = CreateCollectionReq.builder()
        .collectionName("my_collection")
        .collectionSchema(schema)
        .properties(properties)
        .build();
client.createCollection(createCollectionReq);

go
err = client.CreateCollection(ctx,
    milvusclient.NewCreateCollectionOption("my_collection", schema).
        WithProperty("partitionkey.isolation", true))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

javascript
res = await client.alterCollection({
    collection_name: "my_collection",
    properties: {
        "partitionkey.isolation": true
    }
})

bash
export params='{
    "partitionKeyIsolation": true
}'

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d "{
    \"collectionName\": \"my_collection\",
    \"schema\": $schema,
    \"params\": $params
}"

c++
auto status = client->CreateCollection(milvus::CreateCollectionRequest()
                                          .WithCollectionName("my_collection")
                                          .WithCollectionSchema(schema)
                                          .AddProperty("partitionkey.isolation", "true"));
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Partition Key Isolation を有効にした後でも、パーティション数を設定するで説明されているように、Partition Key とパーティション数を設定できます。なお、Partition Key ベースのフィルターには、1 つの特定の Partition Key 値のみを含める必要があります。

概要​

Partition Key を使用する​

Partition Key を設定する​

partition 数を設定する​

フィルタリング条件を作成する​

Partition Key Isolation を使用する​

Partition Key Isolation を有効にする​

概要

Partition Key を使用する

Partition Key を設定する

partition 数を設定する

フィルタリング条件を作成する

Partition Key Isolation を使用する

Partition Key Isolation を有効にする