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

默认值

Zilliz Cloud 支持为标量字段（不包括主字段）设置默认值。字段配置默认值后，如果插入数据时未提供该字段的值，Zilliz Cloud 会自动使用配置的默认值。

默认值可以保留其他数据库系统中的既有默认值设置，从而简化数据迁移到 Zilliz Cloud 的过程。对于插入时暂时无法确定取值的字段，您也可以使用默认值。

限制​

  • 只有标量字段支持默认值。主字段和向量字段不能配置默认值。

  • JSON 和 ARRAY 字段不支持默认值。

  • 默认值只能在创建 Collection 时配置，创建后不能修改。

设置默认值​

创建 Collection 时，在 add_field() 中使用 default_value 参数为字段定义默认值。

以下示例创建一个 Collection，其中两个标量字段配置了默认值：age 的默认值为 18，status 的默认值为 "active"。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri='https://{cluster-id}.{region}.vectordb.zilliz.com.cn:19530')

# Define collection schema
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_schema=True,
)

schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=5)
# highlight-start
schema.add_field(field_name="age", datatype=DataType.INT64, default_value=18)
schema.add_field(field_name="status", datatype=DataType.VARCHAR, default_value="active", max_length=10)
# highlight-end

# Set index params
index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX", metric_type="L2")

# Create collection
client.create_collection(collection_name="my_collection", schema=schema, index_params=index_params)

插入 Entity​

插入数据时，如果省略已配置默认值的字段，或显式将该字段设为 NULL，Zilliz Cloud 会自动使用配置的默认值。

data = [
    # All fields provided explicitly
    {"id": 1, "vector": [0.1, 0.2, 0.3, 0.4, 0.5], "age": 30, "status": "premium"},
    # age and status omitted → both use default values (18 and "active")
    {"id": 2, "vector": [0.2, 0.3, 0.4, 0.5, 0.6]},
    # status set to None → uses default value "active"
    {"id": 3, "vector": [0.3, 0.4, 0.5, 0.6, 0.7], "age": 25, "status": None},
    # age set to None → uses default value 18
    {"id": 4, "vector": [0.4, 0.5, 0.6, 0.7, 0.8], "age": None, "status": "inactive"}
]

client.insert(collection_name="my_collection", data=data)

使用默认值进行搜索和查询​

包含默认值的 Entity 在向量搜索和标量过滤中的行为与其他 Entity 相同。您可以在搜索和查询操作中按默认值进行过滤。

以下示例搜索 age 等于默认值 18 的 Entity：

res = client.search(
    collection_name="my_collection",
    data=[[0.1, 0.2, 0.4, 0.3, 0.5]],
    search_params={"params": {"nprobe": 16}},
    filter="age == 18",
    limit=10,
    output_fields=["id", "age", "status"]
)

print("Search results (age == 18):")
for hit in res[0]:
    print(f"  id: {hit['id']}, age: {hit['entity']['age']}, status: {hit['entity']['status']}")
预期输出
Output:
Search results (age == 18):
  id: 2, age: 18, status: active
  id: 4, age: 18, status: inactive

您也可以直接匹配默认值来查询 Entity：

# Query entities where age equals the default value (18)
default_age_results = client.query(
    collection_name="my_collection",
    filter="age == 18",
    output_fields=["id", "age", "status"]
)

print("\nQuery results (age == 18):")
for r in default_age_results:
    print(f"  id: {r['id']}, age: {r['age']}, status: {r['status']}")

# Query entities where status equals the default value ("active")
default_status_results = client.query(
    collection_name="my_collection",
    filter='status == "active"',
    output_fields=["id", "age", "status"]
)

print("\nQuery results (status == 'active'):")
for r in default_status_results:
    print(f"  id: {r['id']}, age: {r['age']}, status: {r['status']}")
预期输出
Query results (age == 18):
  id: 2, age: 18, status: active
  id: 4, age: 18, status: inactive

Query results (status == 'active'):
  id: 2, age: 18, status: active
  id: 3, age: 25, status: active

适用规则​

如果字段同时配置了 nullable 和 default_value，以下规则决定 Zilliz Cloud 在插入时如何处理 NULL 输入或缺失字段值。

Nullable

Default Value

用户输入

结果

✅

✅（非 NULL）

NULL 或省略

使用默认值

✅

❌

NULL 或省略

存储为 NULL

❌

✅（非 NULL）

NULL 或省略

使用默认值

❌

❌

NULL 或省略

抛出错误

❌

✅（NULL）

NULL 或省略

抛出错误

关键结论：

  • 当字段具有非 NULL 默认值时，无论是否启用 nullable，都会使用该默认值。

  • 当 nullable=True 但未设置默认值时，字段存储为 NULL。

  • 当 nullable=False 且未设置默认值时，插入失败并报错。

  • 在非可空字段上设置 NULL 默认值无效，并会导致错误。