跳至主要内容
前往文档
⌘U
Weaviate 数据库

使用 Weaviate 的 APIs 和工具开发 AI 应用

部署

部署、配置和维护 Weaviate 数据库

Weaviate Agents

使用 Weaviate 构建和部署智能代理

Weaviate Cloud

在云端管理和扩展 Weaviate

更多资源

集成
贡献者指南
活动 & 工作坊
Weaviate Academy

需要帮助？

Weaviate Logo询问 AI 助手⌘K
社区论坛

条件过滤器

条件过滤器可以添加到诸如 对象级别 和 聚合 查询以及 批量删除 等查询中。用于过滤的运算符也称为 where 过滤器。

过滤器可以包含一个或多个条件，这些条件使用 And 或 Or 运算符组合。每个条件由属性路径、运算符和值组成。

单个操作数（条件）​

每个代数条件集称为“操作数”。对于每个操作数，所需的属性是

  • 运算符类型，
  • 属性路径，以及
  • 值以及值类型。

例如，此过滤器仅允许来自 Article 类且 wordCount 大于 1000 的对象。

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

collection = client.collections.use("Article")
response = collection.query.fetch_objects(
    filters=Filter.by_property("wordCount").greater_than(1000),
    limit=5
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
client.close()
预期响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "Anywhere but Washington: an eye-opening journey in a deeply divided nation"
        },
        {
          "title": "The world is still struggling to implement meaningful climate policy"
        },
        ...
      ]
    }
  }
}

过滤器结构​

where 过滤器是一个 代数对象，它接受以下参数

  • Operator（它采用以下值之一）
    • And
    • Or
    • Not
    • Equal
    • NotEqual
    • GreaterThan
    • GreaterThanEqual
    • LessThan
    • LessThanEqual
    • Like
    • WithinGeoRange
    • IsNull
    • ContainsAny (*仅适用于数组和文本属性)
    • ContainsAll (*仅适用于数组和文本属性)
    • ContainsNone (*仅适用于数组和文本属性)
  • Path：是 XPath 风格的字符串列表，指示集合的属性名称。
    • 如果属性是交叉引用，则应将路径作为字符串列表进行跟踪。对于引用 Publication 集合的 inPublication 引用属性，name 的路径选择器将是 ["inPublication", "Publication", "name"]。
  • valueType
    • valueInt：用于 int 数据类型。
    • valueBoolean：用于 boolean 数据类型。
    • valueString：用于 string 数据类型（注意：string 已被弃用）。
    • valueText：用于 text、uuid、geoCoordinates、phoneNumber 数据类型。
    • valueNumber：用于 number 数据类型。
    • valueDate：用于 date（ISO 8601 时间戳，格式为 RFC3339）数据类型。

如果运算符是 And 或 Or，则操作数是 where 过滤器的列表。

示例过滤器结构（GraphQL）
{
  Get {
    <Class>(where: {
        operator: <operator>,
        operands: [{
          path: [path],
          operator: <operator>
          <valueType>: <value>
        }, {
          path: [<matchPath>],
          operator: <operator>,
          <valueType>: <value>
        }]
      }) {
      <propertyWithBeacon> {
        <property>
        ... on <ClassOfWhereBeaconGoesTo> {
          <propertyOfClass>
        }
      }
    }
  }
}
示例响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "Opinion | John Lennon Told Them ‘Girls Don't Play Guitar.' He Was So Wrong."
        }
      ]
    }
  },
  "errors": null
}

过滤器行为​

Equal 过滤器中的多词查询​

where 过滤器中多词文本属性上 Equal 运算符的行为取决于属性的 tokenization。

有关可用分词类型之间的差异，请参阅 模式属性分词部分。

text 过滤器中的停用词​

从 v1.12.0 开始，您可以配置自己的 倒排索引的停用词列表。

多个操作数​

您可以设置多个操作数或 嵌套条件。

提示

您可以以类似于数字的方式过滤日期时间，将 valueDate 作为 RFC3339 格式的 string 提供。

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

collection = client.collections.use("Article")
response = collection.query.fetch_objects(
    filters=(
        Filter.by_property("wordCount").greater_than(1000)
        & Filter.by_property("title").like("*economy*")
    ),
    limit=5,
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
client.close()
预期响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "China\u2019s long-distance lorry drivers are unsung heroes of its economy"
        },
        {
          "title": "\u2018It\u2019s as if there\u2019s no Covid\u2019: Nepal defies pandemic amid a broken economy"
        },
        {
          "title": "A tax hike threatens the health of Japan\u2019s economy"
        }
      ]
    }
  }
}

过滤器运算符​

Like​

Like 运算符根据部分匹配过滤 text 数据。它可以使用以下通配符

  • ? -> 恰好一个未知字符
    • car? 匹配 cart、care，但不匹配 car
  • * -> 零个、一个或多个未知字符
    • car* 匹配 car、care、carpet 等
    • *car* 匹配 car、healthcare 等。
py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

collection = client.collections.use("Article")
response = collection.query.fetch_objects(
    filters=Filter.by_property("title").like("New *"),
    limit=5
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
client.close()
预期响应
{
  "data": {
    "Get": {
      "Publication": [
        {
          "name": "The New York Times Company"
        },
        {
          "name": "International New York Times"
        },
        {
          "name": "New York Times"
        },
        {
          "name": "New Yorker"
        }
      ]
    }
  }
}

Like 的性能​

每个 Like 过滤器都会遍历该属性的整个倒排索引。搜索时间将随数据集大小线性增加，并且对于大型数据集可能会变慢。

使用 Like 进行通配符字面量匹配​

目前，Like 过滤器无法将通配符（? 和 *）作为字面量字符进行匹配。例如，目前无法仅匹配字符串 car*，而不匹配 car、care 或 carpet。这是一个已知限制，未来版本的 Weaviate 可能会解决。

ContainsAny / ContainsAll / ContainsNone​

ContainsAny、ContainsAll 和 ContainsNone 运算符使用数组中的值作为标准过滤对象。

这两个运算符都期望一个值数组，并根据输入值返回匹配的对象。

ContainsAny/ContainsAll/ContainsNone 注意事项
  • ContainsAny、ContainsAll 和 ContainsNone 运算符将文本视为数组。文本根据所选的分词方案拆分为标记数组，并在该数组上执行搜索。
  • 在使用 REST api 进行 批量删除 时，文本数组必须使用 valueTextArray 参数指定。这与搜索中的用法不同，在搜索中可以使用 valueText 参数。

ContainsAny​

ContainsAny 返回对象，其中输入数组中的至少一个值存在。

考虑一个 Person 的数据集，其中每个对象代表一个具有 text 数据类型的 languages_spoken 属性的人。

在 ["languages_spoken"] 路径上使用 ["Chinese", "French", "English"] 值的 ContainsAny 查询将返回 languages_spoken 数组中存在这些语言中的至少一种的对象。

ContainsAll​

ContainsAll 返回对象，其中输入数组中的所有值都存在。

使用与上述相同的 Person 对象数据集，在 ["languages_spoken"] 路径上使用 ["Chinese", "French", "English"] 值的 ContainsAll 查询将返回 languages_spoken 数组中存在所有这三种语言的对象。

ContainsNone​

ContainsNone 返回对象，其中输入数组中的任何值都不存在。

使用与上述相同的 Person 对象数据集，在 ["languages_spoken"] 路径上使用 ["Chinese", "French", "English"] 值的 ContainsNone 查询将返回 languages_spoken 数组中不存在这些语言的对象。例如，只会返回只会说西班牙语的人，而会排除会说英语的人。

过滤器性能​

在某些边缘情况下，由于过滤器架构与数据结构不匹配，过滤器性能可能会变慢。例如，如果某个属性具有非常大的基数（即，大量唯一值），则其基于范围的过滤器性能可能会变慢。

如果您遇到缓慢的过滤器性能，您有几种选择

  • 通过向 where 操作符添加更多条件来进一步限制您的查询
  • 向您的查询添加 limit 参数
  • 为需要基于范围过滤的属性配置 indexRangeFilters。您可以在创建集合时 设置倒排索引参数。了解更多关于 配置倒排索引 以优化特定用例的过滤器性能。

特殊情况​

按 ID​

您可以按其唯一 ID 或 UUID 过滤对象，将 id 作为 valueText 提供。

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

collection = client.collections.use("Article")
response = collection.query.fetch_objects(
    filters=Filter.by_id().equal("00037775-1432-35e5-bc59-443baaef7d80")
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
client.close()
预期响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "Backs on the rack - Vast sums are wasted on treatments for back pain that make it worse"
        }
      ]
    }
  }
}

按时间戳​

也可以使用内部时间戳进行过滤，例如 creationTimeUnix 和 lastUpdateTimeUnix。这些值可以表示为 Unix epoch 毫秒，也可以表示为 RFC3339 格式的日期时间。请注意，epoch 毫秒应作为 valueText 传递，而 RFC3339 日期时间应为 valueDate。

信息

按时间戳过滤需要配置目标类以索引时间戳。有关详细信息，请参阅 此处。

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os
from datetime import datetime

client = weaviate.connect_to_local()

collection = client.collections.use("Article")
year2k = datetime.strptime("2000-01-01T00:00:00Z", "%Y-%m-%dT%H:%M:%SZ")

response = collection.query.fetch_objects(
    filters=Filter.by_creation_time().greater_or_equal(year2k),
    return_metadata=MetadataQuery(creation_time=True),
    limit=2
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
    print(o.metadata)  # Inspect returned creation time
client.close()
预期响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "Army builds new body armor 14-times stronger in the face of enemy fire"
        },
        ...
      ]
    }
  }
}

按属性长度​

可以使用属性的长度进行过滤。

根据类型，属性的长度计算方式不同

  • 数组类型：使用数组中的条目数，其中 null（属性不存在）和空数组都具有长度 0。
  • 字符串和文本：字符数（例如，世等 Unicode 字符算作一个字符）。
  • 数字、布尔值、地理坐标、电话号码和数据块不受支持。
{
  Get {
    <Class>(
      where: {
        operator: <Operator>,
        valueInt: <value>,
        path: ["len(<property>)"]
      }
    )
  }
}

支持的运算符是 (not) equal 和 greater/less than (equal)，并且值需要大于或等于 0。

请注意，path 值是一个字符串，其中属性名称包含在 len() 中。例如，要根据 title 属性的长度过滤对象，您将使用 path: ["len(title)"]。

要过滤 Article 类对象，使其 title 长度大于 10，您将使用

{
  Get {
    Article(
      where: {
        operator: GreaterThan,
        valueInt: 10,
        path: ["len(title)"]
      }
    )
  }
}
注意

按属性长度过滤需要配置目标类以 配置索引长度。

按交叉引用​

您还可以搜索交叉引用的属性值，也称为 beacons。

例如，这些过滤器基于 Article 类选择，但 inPublication 设置为 New Yorker。

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

collection = client.collections.use("Article")

response = collection.query.fetch_objects(
    filters=Filter.by_ref(link_on="inPublication").by_property("name").like("*New*"),
    return_references=QueryReference(link_on="inPublication", return_properties=["name"]),
    limit=2
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
    for ref_o in o.references["inPublication"].objects:
        print(ref_o.properties)
client.close()
预期响应
{
  "data": {
    "Get": {
      "Article": [
        {
          "inPublication": [
            {
              "name": "New Yorker"
            }
          ],
          "title": "The Hidden Costs of Automated Thinking"
        },
        {
          "inPublication": [
            {
              "name": "New Yorker"
            }
          ],
          "title": "The Real Deal Behind the U.S.\u2013Iran Prisoner Swap"
        },
        ...
      ]
    }
  }
}

按引用计数​

上面的示例展示了如何通过引用过滤来解决像“查找所有由 New Yorker 出版的文章”这样直接的问题。但是，像“查找所有由撰写过至少两篇文章的作者撰写的文章”这样的问题，无法通过上述查询结构来回答。但是，可以通过引用计数进行过滤。为此，只需提供现有的比较运算符之一（Equal、LessThan、LessThanEqual、GreaterThan、GreaterThanEqual），并直接将其应用于引用元素。例如

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

response = collection.query.fetch_objects(
    filters=Filter.by_ref_count(link_on="inPublication").greater_than(2),
    return_references=QueryReference(link_on="inPublication", return_properties=["name"]),
    limit=2
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
    for ref_o in o.references["inPublication"].objects:
        print(ref_o.properties)
client.close()
预期响应
{
  "data": {
    "Get": {
      "Author": [
        {
          "name": "Agam Shah",
          "writesFor": [
            {
              "name": "Wall Street Journal"
            },
            {
              "name": "Wall Street Journal"
            }
          ]
        },
        {
          "name": "Costas Paris",
          "writesFor": [
            {
              "name": "Wall Street Journal"
            },
            {
              "name": "Wall Street Journal"
            }
          ]
        },
        ...
      ]
    }
  }
}

按地理坐标​

Where 过滤器的一个特殊情况是使用 geoCoordinates。此过滤器仅受 Get{} 函数支持。如果您设置了 geoCoordinates 属性类型，则可以基于公里数在某个区域内搜索。

例如，这个好奇的查询返回了围绕特定地理位置半径 2 公里内的所有内容

py docs  API 文档
更多信息文档中的代码片段反映了最新的客户端库和 Weaviate 数据库版本。请查看 发行说明 以获取特定版本。

如果某个片段无法工作或您有任何反馈，请打开一个 GitHub issue。
import weaviate
from weaviate.classes.query import Filter, GeoCoordinate, MetadataQuery, QueryReference  # Import classes as needed
import os

client = weaviate.connect_to_local()

response = publications.query.fetch_objects(
    filters=(
        Filter
        .by_property("headquartersGeoLocation")
        .within_geo_range(
            coordinate=GeoCoordinate(
                latitude=33.7579,
                longitude=84.3948
            ),
            distance=10000  # In meters
        )
    ),
)

for o in response.objects:
    print(o.properties)  # Inspect returned objects
client.close()
预期响应
{
  "data": {
    "Get": {
      "Publication": [
        {
          "headquartersGeoLocation": {
            "latitude": 51.512737,
            "longitude": -0.0962234
          },
          "name": "Financial Times"
        },
        {
          "headquartersGeoLocation": {
            "latitude": 51.512737,
            "longitude": -0.0962234
          },
          "name": "International New York Times"
        }
      ]
    }
  }
}

请注意，geoCoordinates 在底层使用向量索引。

限制

当前，地理坐标过滤仅限于从源位置的最近 800 个结果，这些结果将进一步减少任何其他过滤器条件和搜索参数。

如果您计划使用密集数据集，请考虑使用另一种策略，例如将地理哈希转换为 text 数据类型，并进一步过滤，例如使用 ContainsAny 过滤器。

按空状态​

使用 IsNull 运算符允许您过滤给定属性为 null 或 not null 的对象。请注意，零长度数组和空字符串等同于 null 值。

{
  Get {
    <Class>(where: {
        operator: IsNull,
        valueBoolean: <true/false>
        path: [<property>]
  }
}
注意

按空状态过滤需要配置目标类以索引此状态。有关详细信息，请参阅 此处。

问题和反馈​

如果您有任何问题或反馈，请在 用户论坛 中告诉我们。

技术问题

如果您有任何问题，请在我们的 社区论坛 上发帖。

文档反馈

通过打开 GitHub issue 提供反馈。

此页面是否有帮助？