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

プライマリフィールドと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 を手動管理する必要がないほとんどのシナリオ。
Manual IDデータの挿入またはインポート時に、自分で一意の ID を指定します。ID を外部システムや既存のデータセットと一致させる必要がある場合。
📘メモ

  • どちらのモードを選ぶべきかわからない場合は、より簡単なデータ取り込みと一意性の保証のために、AutoID から始めてください。

  • 手動でプライマリキーを設定することに利点がある場合を除き、すべてのケースで autoId に依存することを推奨します。

クイックスタート: AutoID を使う​

ID 生成は Zilliz Cloud に自動で任せることができます。

ステップ 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]
📘メモ

既存のエンティティを扱う場合は、重複 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