預設值

Milvus 允許您為標量欄位（不包括主欄位）設置預設值。當一個欄位設定了預設值，如果在插入時沒有提供資料，Milvus 會自動套用這個值。

通過保留現有的預設值設置，預設值簡化了從其他數據庫系統到 Milvus 的數據遷移。您也可以使用預設值來處理在插入時值可能不確定的欄位。

限制

• 只有標量欄位支援預設值。主要欄位和向量欄位不能有預設值。

• JSON 和ARRAY 欄位不支援預設值。

• 預設值只能在建立集合時設定，之後就無法修改。

設定預設值

建立集合時，請使用add_field() 中的default_value 參數，定義欄位的預設值。

以下範例建立一個集合，其中有兩個標量欄位具有預設值：age 預設為18 ，status 預設為"active" 。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri='http://localhost: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)
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)

# 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)

// java

// js

// go

# restful

插入實體

當插入資料時，如果您省略有預設值的欄位或明確地將其設定為 NULL，Milvus 會自動使用設定的預設值。

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)

// java

// js

// go

# restful

使用預設值搜尋和查詢

在向量搜尋和標量篩選時，包含預設值的實體與其他實體的行為相同。您可以在search 和query 操作中使用預設值進行篩選。

以下範例會搜尋age 等於預設值18 的實體：

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']}")

// java

// js

// go

# restful

Output:
Search results (age == 18):
  id: 2, age: 18, status: active
  id: 4, age: 18, status: inactive

您也可以透過直接匹配預設值來查詢實體：

# 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']}")

// java

// js

// go

# restful

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 都設定為欄位時，下列規則決定 Milvus 在插入時如何處理 NULL 輸入或遺漏的欄位值。

主要啟示：

• 當欄位有非 NULL 預設值時，不論是否啟用nullable ，都會使用該值。

• 當nullable=True 但未設定預設值時，欄位會儲存 NULL。

• 當nullable=False 但未設定預設值時，插入會出錯失敗。

• 在非空欄位上設定 NULL 預設值是無效的，並會造成錯誤。