跳到主要内容

VarChar 类型

在 Zilliz Cloud 中，文本标量数据可以存储在 VARCHAR 和 TEXT 字段中。本页介绍 VARCHAR 字段，它适用于存储长度较短且有上限的字符串元数据，例如名称、标签、分类和外部 ID。

如果需要保存更长的源文本，如文档片段、文章正文、工单内容或日志，并在查询实体时一并返回，则应使用 TEXT 字段。详情可参阅 Text 类型。

在定义一个 VARCHAR 类型的字段时，需要完成如下设置：

  • 设置 datatype 为 DataType.VARCHAR。

  • 设置 max_length，用于指定当前 VARCHAR 字段可容纳的最大字节数。该参数的取值范围为 1 到 65,535。

说明

Zilliz Cloud 支持为 VARCHAR 字段设置 Null 值和默认值。如需开启这些设置，需要在创建字段时，将 nullable 设置为 True 以及将 default_value 设置为一个字符串。关于 Null 值和默认值的详细情况，可以参考 Nullable 和默认值。

添加 VARCHAR 字段​

要在 Zilliz Cloud 中使用字符串类型，需要在创建 Collection 时定义用于存储字符串的 VARCHAR 字段。如下示例演示了如何在创建 Collection Schema 时定义两个 VARCHAR 字段。其中，

  • varchar_field1 用于存放最多 100 字节的字符串，允许为 Null，默认值为 "Unknow"。

  • varchar_field2 用于存放最多 200 字节的字符串，允许为 Null，没有默认值。

说明

如果在创建 Schema 时设置了 enable_dynamic_fields=True，Zilliz Cloud 允许您插入的数据中包含 Schema 中未定义的字段。但是这可能会使查询复杂度和管理难度增加，进而影响查询性能。关于动态字段的相关内容，可以参考Dynamic Field。

python
# Import necessary libraries
from pymilvus import MilvusClient, DataType

# Define server address
SERVER_ADDR = "YOUR_CLUSTER_ENDPOINT"

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

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

# Add `varchar_field1` that supports null values with default value "Unknown"
schema.add_field(field_name="varchar_field1", datatype=DataType.VARCHAR, max_length=100, nullable=True, default_value="Unknown")
# Add `varchar_field2` that supports null values without default value
schema.add_field(field_name="varchar_field2", datatype=DataType.VARCHAR, max_length=200, 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)

设置索引参数​

为 VARCHAR 字段设置索引参数是一个可选操作，可以显著提高查询效率。在 Zilliz Cloud 中，索引为向量字段的必选配置；对于标量字段而言为可选配置。

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

python
# Set index params

index_params = client.prepare_index_params()

# Index `varchar_field1` with AUTOINDEX
index_params.add_index(
    field_name="varchar_field1",
    index_type="AUTOINDEX",
    index_name="varchar_index"
)

# Index `embedding` with AUTOINDEX and specify 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。

python
# Create Collection
client.createCollection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params
)

插入数据​

Collection 创建完成后，可以插入包含字符串字段的数据。

python
# Sample data
data = [
    {"varchar_field1": "Product A", "varchar_field2": "High quality product", "pk": 1, "embedding": [0.1, 0.2, 0.3]},
    {"varchar_field1": "Product B", "pk": 2, "embedding": [0.4, 0.5, 0.6]}, # varchar_field2 field is missing, which should be NULL
    {"varchar_field1": None, "varchar_field2": None, "pk": 3, "embedding": [0.2, 0.3, 0.1]},  # `varchar_field1` should default to `Unknown`, `varchar_field2` is NULL
    {"varchar_field1": "Product C", "varchar_field2": None, "pk": 4, "embedding": [0.5, 0.7, 0.2]},  # `varchar_field2` is NULL
    {"varchar_field1": None, "varchar_field2": "Exclusive deal", "pk": 5, "embedding": [0.6, 0.4, 0.8]},  # `varchar_field1` should default to `Unknown`
    {"varchar_field1": "Unknown", "varchar_field2": None, "pk": 6, "embedding": [0.8, 0.5, 0.3]},  # `varchar_field2` is NULL
    {"varchar_field1": "", "varchar_field2": "Best seller", "pk": 7, "embedding": [0.8, 0.5, 0.3]}, # Empty string is not treated as NULL
]

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

使用过滤表达式查询​

添加字符串字段后，您可以在 query 请求中利用这些字段进行过滤。例如，您可以查询 varchar_field1 为 Product A 的所有数据：

python
# Filter `varchar_field1` with value "Product A"
filter = 'varchar_field1 == "Product A"'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Product A', 'varchar_field2': 'High quality product', 'pk': 1}"
# ]

您也可以参考如下代码查找所有 varchar_field2 字段为 null 的所有 Entity。

python
# Filter entities where `varchar_field2` is null
filter = 'varchar_field2 is null'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Product B', 'varchar_field2': None, 'pk': 2}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 3}",
#     "{'varchar_field1': 'Product C', 'varchar_field2': None, 'pk': 4}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 6}"
# ]

如果需要获取 varchar_field1 字段值为 "Unknown" 的所有 Entity，可以参考如下代码进行查询。值得注意的是，因为 varchar_field1 字段的默认值也为 "Unknown"，查询的结果会包括该字段显式设置为 "Unknown" 的以及值为空的所有 Entity。

python
# Filter entities with `varchar_field1` with value `Unknown`
filter = 'varchar_field1 == "Unknown"'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 3}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': 'Exclusive deal', 'pk': 5}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 6}"
# ]

向量搜索与字符串过滤结合​

除了基本的标量字段过滤，您还可以将向量相似度搜索与标量字段过滤结合使用。例如，以下代码展示了如何在向量搜索中添加标量字段的过滤条件：

python
# Search with string filtering

# Filter `varchar_field2` with value "Best seller"
filter = 'varchar_field2 == "Best seller"'

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

print(res)

# Example output:
# data: [
#     "[{'id': 7, 'distance': -0.04468163847923279, 'entity': {'varchar_field1': '', 'varchar_field2': 'Best seller'}}]"
# ]
Ctrl I