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

数组字段

ARRAY 字段存储同一数据类型元素的有序 Collection。下面举例说明 ARRAY 字段如何存储数据：

{
  "tags": ["pop", "rock", "classic"],
  "ratings": [5, 4, 3]
}

限制​

  • 默认值：ARRAY 字段不支持默认值。但是，可以将nullable 属性设置为True ，以允许空值。有关详情，请参阅Nullable & Default。

  • **数据类型：**ARRAY 字段中的所有元素必须共享相同的数据类型，该类型由element_type 参数定义。当element_type 设置为VARCHAR 时，还必须为数组元素指定max_length 。element_type 接受 Milvus 支持的任何标量数据类型，但JSON 除外。

  • 数组容量：ARRAY 字段中的元素数必须小于或等于创建数组时定义的最大容量，具体由max_capacity 指定。该值应为1至4096 范围内的整数。

  • 字符串处理：数组字段中的字符串值按原样存储，不进行语义转义或转换。例如，'a"b' 、"a'b" 、'a\'b' 和"a\"b" 按输入值存储，而'a'b' 和"a"b" 则被视为无效值。

添加 ARRAY 字段​

要使用 ARRAY 字段，Milvus 需要在创建 Collection Schema 时定义相关字段类型。这一过程包括

  1. 将datatype 设置为支持的数组数据类型ARRAY 。

  2. 使用element_type 参数指定数组中元素的数据类型。同一数组中的所有元素必须具有相同的数据类型。

  3. 使用max_capacity 参数定义数组的最大容量，即数组可包含的最大元素数。

下面介绍如何定义包含 ARRAY 字段的 Collection Schema：

说明

如果在定义模式时设置enable_dynamic_fields=True ，Milvus 允许你插入事先未定义的标量字段。不过，这可能会增加查询和管理的复杂性，并可能影响性能。有关详细信息，请参阅动态字段。

# Import necessary libraries
from pymilvus import MilvusClient, DataType

# Define server address
SERVER_ADDR = "http://localhost:19530"

# Create a MilvusClient instance
client = MilvusClient(uri=SERVER_ADDR)

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

#  Add `tags` and `ratings` ARRAY fields with nullable=True
schema.add_field(field_name="tags", datatype=DataType.ARRAY, element_type=DataType.VARCHAR, max_capacity=10, max_length=65535, nullable=True)
schema.add_field(field_name="ratings", datatype=DataType.ARRAY, element_type=DataType.INT64, max_capacity=5, nullable=True)
schema.add_field(field_name="pk", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=3)

设置索引参数​

索引有助于提高搜索和查询性能。在 Milvus 中，向量字段必须建立索引，标量字段则可选。

下面的示例使用AUTOINDEX 索引类型为向量字段embedding 和 ARRAY 字段tags 创建了索引。使用这种类型，Milvus 会根据数据类型自动选择最合适的索引。您还可以自定义每个字段的索引类型和参数。有关详情，请参阅索引说明。

# Set index params

index_params = client.prepare_index_params()

# Index `age` with AUTOINDEX
index_params.add_index(
    field_name="tags",
    index_type="AUTOINDEX",
    index_name="tags_index"
)

# Index `embedding` with AUTOINDEX and specify similarity metric type
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",  # Use automatic indexing to simplify complex index settings
    metric_type="COSINE"  # Specify similarity metric type, options include L2, COSINE, or IP
)

创建 Collection​

定义好 Schema 和索引后，创建一个包含 ARRAY 字段的 Collection。

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

插入数据​

创建 Collection 后，就可以插入包含 ARRAY 字段的数据。

# Sample data
data = [
  {
      "tags": ["pop", "rock", "classic"],
      "ratings": [5, 4, 3],
      "pk": 1,
      "embedding": [0.12, 0.34, 0.56]
  },
  {
      "tags": None,  # Entire ARRAY is null
      "ratings": [4, 5],
      "pk": 2,
      "embedding": [0.78, 0.91, 0.23]
  },
  {  # The tags field is completely missing
      "ratings": [9, 5],
      "pk": 3,
      "embedding": [0.18, 0.11, 0.23]
  }
]

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

使用过滤表达式查询​

插入实体后，使用query 方法检索与指定过滤表达式匹配的实体。

检索tags 不为空的实体：

# Query to exclude entities where `tags` is not null

filter = 'tags IS NOT NULL'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["tags", "ratings", "pk"]
)

print(res)

# Example output:
# data: [
#     "{'tags': ['pop', 'rock', 'classic'], 'ratings': [5, 4, 3], 'pk': 1}"
# ]

检索ratings 第一个元素的值大于 4 的实体：

filter = 'ratings[0] > 4'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["tags", "ratings", "embedding"]
)

print(res)

# Example output:
# data: [
#     "{'tags': ['pop', 'rock', 'classic'], 'ratings': [5, 4, 3], 'embedding': [0.12, 0.34, 0.56], 'pk': 1}",
#     "{'tags': None, 'ratings': [9, 5], 'embedding': [0.18, 0.11, 0.23], 'pk': 3}"
# ]

使用过滤表达式进行向量搜索​

除了基本的标量字段筛选外，您还可以将向量相似性搜索与标量字段筛选结合起来。例如，下面的代码展示了如何在向量搜索中添加标量字段过滤器：

filter = 'tags[0] == "pop"'

res = client.search(
    collection_name="my_collection",
    data=[[0.3, -0.6, 0.1]],
    limit=5,
    search_params={"params": {"nprobe": 10}},
    output_fields=["tags", "ratings", "embedding"],
    filter=filter
)

print(res)

# Example output:
# data: [
#     "[{'id': 1, 'distance': -0.2479381263256073, 'entity': {'tags': ['pop', 'rock', 'classic'], 'ratings': [5, 4, 3], 'embedding': [0.11999999731779099, 0.3400000035762787, 0.5600000023841858]}}]"
# ]

此外，Milvus 还支持高级数组过滤操作符，如ARRAY_CONTAINS,ARRAY_CONTAINS_ALL,ARRAY_CONTAINS_ANY 和ARRAY_LENGTH ，以进一步增强查询功能。更多详情，请参阅ÂRAY 操作符。