跳到主要内容
版本：v2.6.x

向现有 Collection 添加字段 Compatible with Milvus 2.6.x

Milvus 允许你动态地添加新字段到现有的 Collection 中，使你可以很容易地随着应用需求的变化而发展你的数据 Schema。本指南通过实际例子向你展示如何在不同情况下添加字段。

注意事项​

在向 Collection 添加字段之前，请牢记以下要点：

  • 您可以添加标量字段（INT64,VARCHAR,FLOAT,DOUBLE 等）。向量字段不能添加到现有的 Collection 中。

  • 新字段必须是可归零的（nullable=True），以适应没有新字段值的现有实体。

  • 向已加载的 Collection 添加字段会增加内存使用量。

  • 每个 Collection 的字段总数有最大限制。详情请参阅Milvus 限制。

  • 在静态字段中，字段名必须是唯一的。

  • 对于最初未使用enable_dynamic_field=True 创建的 Collection，不能添加$meta 字段来启用动态字段功能。

前提条件​

本指南假定您拥有

  • 运行中的 Milvus 实例

  • 已安装 Milvus SDK

  • 现有的 Collection

说明

有关Collection的创建和基本操作，请参阅我们的创建 Collection。

基本用法​

from pymilvus import MilvusClient, DataType

# Connect to your Milvus server
client = MilvusClient(
    uri="http://localhost:19530"  # Replace with your Milvus server URI
)

场景 1：快速添加可空字段​

扩展 Collection 的最简单方法是添加可归零字段。当您需要快速为数据添加新属性时，这种方法再合适不过了。

# Add a nullable field to an existing collection
# This operation:
# - Returns almost immediately (non-blocking)
# - Makes the field available for use with minimal delay
# - Sets NULL for all existing entities
client.add_collection_field(
    collection_name="product_catalog",
    field_name="created_timestamp",  # Name of the new field to add
    data_type=DataType.INT64,        # Data type must be a scalar type
    nullable=True                    # Must be True for added fields
    # Allows NULL values for existing entities
)

预期行为：

  • 现有实体的新字段为 NULL

  • 新实体可以有 NULL 或实际值

  • 由于内部 Schema 同步，字段可用性几乎立即发生，延迟极小

  • 短暂同步后可立即查询

# Example query result
{
    'id': 1,
    'created_timestamp': None  # New field shows NULL for existing entities
}

方案 2：添加带默认值的字段​

当您希望现有实体有一个有意义的初始值而不是 NULL 时，可指定默认值。

# Add a field with default value
# This operation:
# - Sets the default value for all existing entities
# - Makes the field available with minimal delay
# - Maintains data consistency with the default value
client.add_collection_field(
    collection_name="product_catalog",
    field_name="priority_level",     # Name of the new field
    data_type=DataType.VARCHAR,      # String type field
    max_length=20,                   # Maximum string length
    nullable=True,                   # Required for added fields
    default_value="standard"         # Value assigned to existing entities
    # Also used for new entities if no value provided
)

预期行为：

  • 现有实体将拥有新添加字段的默认值 ("standard")

  • 新实体可以覆盖默认值，或者在没有提供默认值的情况下使用默认值

  • 字段几乎立即可用，延迟极小

  • 短暂同步后可立即查询

# Example query result
{
    'id': 1,
    'priority_level': 'standard'  # Shows default value for existing entities
}

常见问题​

是否可以通过添加$meta 字段来启用动态 Schema 功能？​

不能，您不能使用add_collection_field 添加$meta 字段来启用动态字段功能。例如，下面的代码将不起作用：

# ❌ This is NOT supported
client.add_collection_field(
    collection_name="existing_collection",
    field_name="$meta",
    data_type=DataType.JSON  # This operation will fail
)

启用动态 Schema 功能：

  • 新建 Collection：创建 Collection 时将enable_dynamic_field 设置为 True。有关详情，请参阅创建 Collection

  • 现有 Collection：将 Collection-level 属性dynamicfield.enabled 设置为 True。有关详情，请参阅修改 Collection。

添加与动态字段关键字同名的字段时会发生什么情况？​

当你的 Collection 启用了动态字段 ($meta exists) 时，你可以添加与现有动态字段键同名的静态字段。新的静态字段将屏蔽动态字段键，但会保留原始动态数据。

为避免字段名称可能出现的冲突，在实际添加前，请参考现有字段和动态字段键，考虑要添加的字段名称。

示例场景：

# Original collection with dynamic field enabled
# Insert data with dynamic field keys
data = [{
    "id": 1,
    "my_vector": [0.1, 0.2, ...],
    "extra_info": "this is a dynamic field key",  # Dynamic field key as string
    "score": 99.5                                 # Another dynamic field key
}]
client.insert(collection_name="product_catalog", data=data)

# Add static field with same name as existing dynamic field key
client.add_collection_field(
    collection_name="product_catalog",
    field_name="extra_info",         # Same name as dynamic field key
    data_type=DataType.INT64,        # Data type can differ from dynamic field key
    nullable=True                    # Must be True for added fields
)

# Insert new data after adding static field
new_data = [{
    "id": 2,
    "my_vector": [0.3, 0.4, ...],
    "extra_info": 100,               # Now must use INT64 type (static field)
    "score": 88.0                    # Still a dynamic field key
}]
client.insert(collection_name="product_catalog", data=new_data)

预期行为：

  • 现有实体将为新静态字段设置 NULLextra_info

  • 新实体必须使用静态字段的数据类型 (INT64)

  • 保留原始动态字段键值，并可通过$meta 语法访问

  • 在正常查询中，静态字段会屏蔽动态字段键值

同时访问静态值和动态值：

# 1. Query static field only (dynamic field key is masked)
results = client.query(
    collection_name="product_catalog",
    filter="id == 1",
    output_fields=["extra_info"]
)
# Returns: {"id": 1, "extra_info": None}  # NULL for existing entity

# 2. Query both static and original dynamic values
results = client.query(
    collection_name="product_catalog",
    filter="id == 1",
    output_fields=["extra_info", "$meta['extra_info']"]
)
# Returns: {
#     "id": 1,
#     "extra_info": None,                           # Static field value (NULL)
#     "$meta['extra_info']": "this is a dynamic field key"  # Original dynamic value
# }

# 3. Query new entity with static field value
results = client.query(
    collection_name="product_catalog",
    filter="id == 2",
    output_fields=["extra_info"]
)
# Returns: {"id": 2, "extra_info": 100}  # Static field value

新字段可用需要多长时间？​

添加的字段几乎立即可用，但由于整个 Milvus 集群的内部 Schema 变化广播，可能会有短暂的延迟。这种同步可确保在处理涉及新字段的查询之前，所有节点都知道 Schema 的更新。