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

プライマリフィールドと AutoID

Zilliz Cloud のすべてのコレクションには、各エンティティを一意に識別するためのプライマリフィールドが必要です。このフィールドにより、すべてのエンティティを曖昧さなく挿入、更新、クエリ、削除できます。

ユースケースに応じて、Zilliz Cloud に ID を自動生成させる（AutoID）ことも、独自の ID を手動で割り当てることもできます。

プライマリフィールドとは何ですか？​

プライマリフィールドは、従来のデータベースにおける主キーと同様に、コレクション内の各エンティティの一意キーとして機能します。Zilliz Cloud は、挿入、upsert、削除、クエリの各操作でエンティティを管理するためにプライマリフィールドを使用します。

主な要件:

  • 各コレクションには、プライマリフィールドを ちょうど 1 つ 持つ必要があります。

  • プライマリフィールドの値は null にできません。

  • データ型は作成時に指定する必要があり、後から変更することはできません。

サポートされるデータ型​

プライマリフィールドには、エンティティを一意に識別できる、サポート対象のスカラーデータ型を使用する必要があります。

データ型説明
INT6464 ビット整数型で、AutoID と組み合わせてよく使用されます。ほとんどのユースケースで推奨されるオプションです。
VARCHAR可変長文字列型です。エンティティ識別子が外部システムに由来する場合（たとえば、製品コードやユーザー ID）に使用します。値ごとに許可される最大バイト数を定義するために max_length プロパティが必要です。

AutoID と手動 ID の選択​

Zilliz Cloud は、プライマリキーの値を割り当てるための 2 つのモードをサポートしています。

モード説明推奨される用途
AutoIDZilliz Cloud が、挿入またはインポートされたエンティティに対して一意の識別子を自動生成します。ID を手動で管理する必要がないほとんどのシナリオ。
手動 IDデータを挿入またはインポートする際に、一意の ID を自分で指定します。ID を外部システムや既存のデータセットに合わせる必要がある場合。
Notes

  • どちらのモードを選択すべきかわからない場合は、よりシンプルな取り込みと一意性の保証のために、AutoID から始めてください。

  • プライマリキーを手動で設定することが有益な場合を除き、どのようなケースでも autoId を利用することを推奨します。

クイックスタート: AutoID を使用する​

Zilliz Cloud に ID の生成を自動的に処理させることができます。

ステップ 1: AutoID を有効にしたコレクションを作成する​

プライマリフィールドの定義で auto_id=True を有効にします。Zilliz Cloud が ID の生成を自動的に処理します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define primary field with AutoID enabled
schema.add_field(
    field_name="id", # Primary field name
    is_primary=True,
    auto_id=True,  # Milvus generates IDs automatically; Defaults to False
    datatype=DataType.INT64
)

# Define the other fields
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # Vector field
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # Scalar field of the VARCHAR type

# Create the collection
if client.has_collection("demo_autoid"):
    client.drop_collection("demo_autoid")
client.create_collection(collection_name="demo_autoid", schema=schema)

ステップ 2: データを挿入する​

重要: データにプライマリフィールドの列を含めないでください。Zilliz Cloud が ID を自動的に生成します。

python
data = [
    {"embedding": [0.1, 0.2, 0.3, 0.4], "category": "book"},
    {"embedding": [0.2, 0.3, 0.4, 0.5], "category": "toy"},
]

res = client.insert(collection_name="demo_autoid", data=data)
print("Generated IDs:", res.get("ids"))

# Output example:
# Generated IDs: [461526052788333649, 461526052788333650]
Notes

既存のエンティティを扱う場合は、重複 ID エラーを回避するために insert() ではなく upsert() を使用してください。

手動 ID を使用する​

ID を手動で制御する必要がある場合は、AutoID を無効にして独自の値を指定します。

ステップ 1: AutoID を使用せずにコレクションを作成する​

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define the primary field without AutoID
schema.add_field(
    field_name="product_id",
    is_primary=True,
    auto_id=False,  # You'll provide IDs manually at data ingestion
    datatype=DataType.VARCHAR,
    max_length=100 # Required when datatype is VARCHAR
)

# Define the other fields
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=4) # Vector field
schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=1000) # Scalar field of the VARCHAR type

# Create the collection
if client.has_collection("demo_manual_ids"):
    client.drop_collection("demo_manual_ids")
client.create_collection(collection_name="demo_manual_ids", schema=schema)

ステップ 2: 独自の ID でデータを挿入する​

すべての挿入操作でプライマリフィールドの列を含める必要があります。

python
# Each entity must contain the primary field `product_id`
data = [
    {"product_id": "PROD-001", "embedding": [0.1, 0.2, 0.3, 0.4], "category": "book"},
    {"product_id": "PROD-002", "embedding": [0.2, 0.3, 0.4, 0.5], "category": "toy"},
]

res = client.insert(collection_name="demo_manual_ids", data=data)
print("Generated IDs:", res.get("ids"))

# Output example:
# Generated IDs: ['PROD-001', 'PROD-002']

お客様の責務:

  • すべてのエンティティ間で ID が一意であることを保証する。

  • すべての insert/import 操作にプライマリフィールドを含める。

  • ID の競合と重複の検出を自分で処理する。

Ctrl I