跳到主要内容
版本：Cloud 开发指南

主键与 AutoID

每个 Zilliz Cloud 的 Collection 都必须定义一个主键（Primary Field），用于唯一标识每个 Entity。

该字段确保每个 Entity 都能被明确地插入、更新、查询或删除，而不会产生歧义。

根据使用场景，你可以让 Zilliz Cloud 自动生成 ID（AutoID），也可以手动指定 Entity ID。

什么是主键？​

主键是 Collection 中每个 Entity 的唯一标识符，类似于传统数据库中的主键（Primary Key）。

Zilliz Cloud 通过主键在插入、更新（upsert）、删除和查询操作中管理 Entity。

主要要求：

  • 每个 Collection 必须且只能有一个主键。

  • 主键的值不能为空。

  • 数据类型必须在创建时指定，且创建后不可更改。

支持的数据类型​

主键必须使用支持唯一标识 Entity 的标量数据类型。Zilliz Cloud 当前支持以下两种类型，适用于不同场景：

数据类型

描述

INT64

64 位整型，常与 AutoID 一起使用，是大多数场景的推荐选项。

VARCHAR

可变长度字符串类型，适用于 Entity 标识来自外部系统（例如产品编码或用户 ID）的场景。需要通过 max_length 参数定义每个值的最大字节数。

选择 AutoID 或手动 ID 模式​

Zilliz Cloud 支持两种主键分配方式：

模式

描述

推荐场景

AutoID（默认）

系统在插入或导入数据时自动生成唯一标识符。

适用于不需要手动管理 ID 的大多数场景。

手动 ID

用户在插入或导入数据时自行提供唯一 ID。

适用于 ID 需要与外部系统或已有数据集保持一致的场景。

📘说明

如果不确定选择哪种模式，建议使用 AutoID，它能简化数据写入流程并自动确保全局唯一性。

快速开始：使用 AutoID​

你可以让 Zilliz Cloud 自动处理 ID 的生成。

步骤 1：创建启用 AutoID 的 Collection​

在主键定义中启用 auto_id=True，系统会自动生成 ID。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define primary field with AutoID enabled
# highlight-start
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
)
# highlight-end

# 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：插入数据​

重要提示： 插入数据时不要包含主键列，系统会自动生成 ID。

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]
📘说明

当需要更新已存在的 Entity 时，建议使用 upsert() 替代 insert()，以避免主键重复错误。

使用手动 ID​

如果你希望完全控制实体 ID，可禁用 AutoID 并手动提供 ID。

步骤 1：创建未启用 AutoID 的 Collection​

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema()

# Define the primary field without AutoID
# highlight-start
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
)
# highlight-end

# 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 的数据​

插入数据时必须包含主键。

# 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']

需确保：

  • 确保所有 Entity ID 全局唯一。

  • 每次插入或导入操作都必须包含主键。

  • 自行处理 ID 冲突或重复检测。