跳转到主要内容
get 和 query 中的 where 参数用于根据元数据过滤记录。例如，在此 query 操作中，Chroma 将仅查询元数据字段 page 值为 10 的记录 
collection.query(
    query_texts=["first query", "second query"],
    where={"page": 10}
)
为了基于元数据进行过滤，您必须向查询提供一个 where 过滤字典。该字典必须具有以下结构 
{
    "metadata_field": {
        <Operator>: <Value>
    }
}
使用 $eq 运算符等同于直接在 where 过滤器中使用元数据字段。 
{
    "metadata_field": "search_string"
}

# is equivalent to

{
    "metadata_field": {
        "$eq": "search_string"
    }
}
例如，这里我们查询元数据字段 page 大于 10 的所有记录 
collection.query(
    query_texts=["first query", "second query"],
    where={"page": { "$gt": 10 }}
)

​
使用逻辑运算符

您还可以使用逻辑运算符 $and 和 $or 来组合多个过滤器。 $and 运算符将返回符合列表中所有过滤条件的查询结果。
{
    "$and": [
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        },
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        }
    ]
}
例如，这里我们查询元数据字段 page 在 5 到 10 之间的所有记录 
collection.query(
    query_texts=["first query", "second query"],
    where={
        "$and": [
            {"page": {"$gte": 5 }},
            {"page": {"$lte": 10 }},
        ]
    }
)
$or 运算符将返回符合列表中任一过滤条件的查询结果。 
{
    "$or": [
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        },
        {
            "metadata_field": {
                <Operator>: <Value>
            }
        }
    ]
}
例如，这里我们获取元数据字段 color 为 red 或 blue 的所有记录 
collection.get(
    where={
        "or": [
            {"color": "red"},
            {"color": "blue"},
        ]
    }
)

​
使用包含运算符

支持以下包含运算符
  • $in - 值在预定义的列表中（字符串、整数、浮点数、布尔值）
  • $nin - 值不在预定义的列表中（字符串、整数、浮点数、布尔值）
$in 运算符将返回元数据属性属于所提供列表的结果 
{
  "metadata_field": {
    "$in": ["value1", "value2", "value3"]
  }
}
$nin 运算符将返回元数据属性不属于所提供列表（或该属性的键不存在）的结果 
{
  "metadata_field": {
    "$nin": ["value1", "value2", "value3"]
  }
}
例如，这里我们获取元数据字段 author 在候选值列表中的所有记录 
collection.get(
    where={
       "author": {"$in": ["Rowling", "Fitzgerald", "Herbert"]}
    }
)

​
使用数组元数据

Chroma 支持在元数据字段中存储值数组。您可以使用 $contains 和 $not_contains 运算符根据数组字段是否包含特定值来过滤记录。

​
添加数组元数据

元数据数组可以包含字符串、整数、浮点数或布尔值。数组中的所有元素必须是相同类型。 
collection.add(
    ids=["m1", "m2", "m3"],
    embeddings=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
    metadatas=[
        {"genres": ["action", "comedy"], "year": 2020},
        {"genres": ["drama"], "year": 2021},
        {"genres": ["action", "thriller"], "year": 2022},
    ],
)

​
使用 $contains 和 $not_contains 过滤

使用 $contains 检查元数据数组是否包含特定的标量值，使用 $not_contains 检查它是否不包含该值。 
# Get all records where genres contains "action"
collection.get(
    where={"genres": {"$contains": "action"}}
)

# Get all records where genres does NOT contain "action"
collection.get(
    where={"genres": {"$not_contains": "action"}}
)

# Works with integer arrays too
collection.get(
    where={"scores": {"$contains": 20}}
)

# Combine with other filters
collection.get(
    where={
        "$and": [
            {"genres": {"$contains": "action"}},
            {"year": {"$gte": 2021}},
        ]
    }
)

​
支持的数组类型

类型PythonTypeScriptRust
字符串["a", "b"]["a", "b"]MetadataValue::StringArray(...)
整数[1, 2, 3][1, 2, 3]MetadataValue::IntArray(...)
浮点数[1.5, 2.5][1.5, 2.5]MetadataValue::FloatArray(...)
布尔值[true, false][true, false]MetadataValue::BoolArray(...)
约束条件
  • 数组中的所有元素必须是相同类型。
  • 不允许空数组。
  • 不支持嵌套数组（数组的数组）。
  • $contains 的值必须是与数组元素类型相匹配的标量。
.get 和 .query 可以处理结合了文档搜索的元数据过滤 
collection.query(
    query_texts=["doc10", "thus spake zarathustra", ...],
    n_results=10,
    where={"metadata_field": "is_equal_to_this"},
    where_document={"$contains":"search_string"}
)