跳到主要内容

Array 类型

Array 类型的字段用于存放相同数据类型的一组元素。如下示例展示了如何使用 Array 类型的字段存放数据。

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

相关限制​

  • 默认值与空值：Array 字段不支持设置默认值。但是您可以将 nullable 设置为 True 来允许元素为空值。具体可参考Nullable 和默认值。

  • 数据类型：Array 字段内所有元素的数据类型必须相同。您可以通过设置 element_type 参数来指定元素的数据类型。如果您将 element_type 设置为 VARCHAR，您还需要为元素设置 max_length 参数来指定元素的最大长度。

  • Array 容量：Array 字段中元素的数量需要小于或等于创建该字段时通过 max_capacity 定义的最大容量。该值的取值范围为 1 至 4096。

  • 字符串处理：当 Array 字段中的元素为字符串时，Milvus 会在搜索和查询时保持原样，不会进行转义操作。例如，'a"b', "a'b", 'a\'b', and "a\"b" 会原样存取，而 'a'b' and "a"b" 则会被当作非法字符串处理。

添加 Array 字段​

要在 Zilliz Cloud clusters 中使用 Array 字段，需要在定义 Collection Schema 时定义相关字段类型。这个过程包括：

  1. 设置 datatype 为支持的 Array 数据类型，即 ARRAY。

  2. 通过 element_type 参数，指定数组中元素的数据类型。该值可以是 Zilliz Cloud clusters 支持的任意标量数据类型，例如 VARCHAR、INT64 等。同一个 Array 中的所有元素必须是相同的数据类型。

  3. 通过 max_capacity 参数，设置数组的最大容量，即数组中可以包含的最大元素数量。

以下是如何定义包含 Array 字段的 Collection Schema：

📘说明

如果您在定义 Schema 时将 enabled_dynamic_fields 设置为 True，您还可以在该 Collection 中插入 Schema 中未定义的字段。此操作可能会增加查询和管理的复杂性，并影响查询性能。更多详情，请参考 Dynamic Field。

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_fields=True,
)

schema.add_field(field_name="tags", datatype=DataType.ARRAY, element_type=DataType.VARCHAR, max_capacity=10, max_length=100)
schema.add_field(field_name="ratings", datatype=DataType.ARRAY, element_type=DataType.INT64, max_capacity=5)
schema.add_field(field_name="pk", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=3)

设置索引参数​

为 Array 字段设置索引参数是一个可选操作，可以显著提高查询效率。在 Zilliz Cloud clusters 中，为向量字段创建索引为必选操作。对于包括布尔和数值类型的标量字段而言，该操作为可选。

以下示例中，我们为 向量字段 embedding 和标量字段 tags 创建了 AUTOINDEX 索引类型，表示 Zilliz Cloud clusters 会自动根据数据类型创建合适的标量索引。有关更多信息，请参考 AUTOINDEX。

# 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 和索引参数来创建 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 方法获取符合指定条件的所有 Entity。

如下示例演示了获取 tags 字段不为 null 的所有 Entity。

# 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 的所有 Entity。

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

另外，Zilliz Cloud 还支持使用高级 Array 过滤操作符，包括 ARRAY_CONTAINS, ARRAY_CONTAINS_ALL, ARRAY_CONTAINS_ANY 和 ARRAY_LENGTH，可以进一步加强过滤能力。更多详情，可以参考 ARRAY 操作符。