Weaviate GraphQL 实战指南5 个查询跑通向量搜索、过滤与聚合【免费下载链接】weaviateWeaviate is an open-source vector database that stores both objects and vectors, allowing for the combination of vector search with structured filtering with the fault tolerance and scalability of a cloud-native database.项目地址: https://gitcode.com/GitHub_Trending/we/weaviateWeaviate 是一个同时存储对象和向量的开源向量数据库GraphQL 查询是它最核心的读取入口一次请求里既能指定取哪些字段、按什么结构化条件过滤又能指定语义相似度搜索的目标只把你要的结果带回来。这篇教程带你走完从发出第一条查询、写出向量搜索、到用 GraphiQL 排错的完整路径。 第一条 Weaviate GraphQL 查询端点、控制台与最小查询服务默认监听 8080 端口/v1/graphql是它的统一路径按 HTTP 方法分两个入口POST /v1/graphqlJSON 请求体里放查询文本执行查询GET /v1/graphql直接打开内置的 GraphiQL 网页控制台调试时最省事。查询文本结构很小根字段Get类名作为子字段字段内只列你要的属性{ Get { Article(limit: 3) { title category } } }响应固定是dataerrors两块errors非空就视为失败。实现层面adapters/handlers/graphql/schema.go 里的Resolve(query, operationName, variables)是统一入口GraphQL schema 由数据库里的类动态生成——你建了什么类Get下就有什么字段。小提示不写limit时查询可能返回全量匹配对象手测阶段请习惯性带上。 第一次向量相似度搜索nearText、nearVector 与 distance 元数据这是 Weaviate 和普通数据库拉开差距的地方把语义当查询条件。两种方式——nearText传自然语言由类的向量化模块先转成向量再检索nearVector则直接传你自己算好的向量。配合_additional { distance }可以拿到每条结果的相似度距离值在 0 到 1 之间越小越接近{ Get { Photo( nearText: {concepts: [sunset, beach, sea], distance: 0.9} limit: 3 ) { url _additional { distance } } } }distance: 0.9表示只返回距离不超过 0.9 的结果换nearVector时把参数写成nearVector: {vector: [0.1, -0.4, ...], distance: 0.9}即可。常见坑类没配置向量化模块时nearText无法完成文本转向量会直接报错。where 过滤的三段式结构where是路径 操作符 值的三段组合值字段名必须匹配数据类型文本用valueString数值用valueNumber或valueInt。查某个分类下的全部对象{ Get { Article( where: {path: [category], operator: Equal, valueString: Tech} ) { title category } } }文本模糊匹配用Like支持%通配符数值比较用GreaterThan、LessThan等。坑点操作符和值类型要配对数值字段上写valueString会在参数校验阶段直接失败。只取要什么字段选择、分页与排序字段选择是 GraphQL 查询的第一道减负措施——只写真正用到的属性。配合limit、offset、sortBy就能完整控制结果集{ Get { Article( limit: 5 offset: 10 sortBy: [{path: [published], order: desc}] ) { title published } } }小提示sortBy的path支持嵌套路径如[author, name]order取asc或desc一次可以传多个排序键。 嵌套关联对象查询一次拿全引用数据类与类之间的引用属性比如文章里的author可以直接在查询里展开。引用字段本质是列表且类型是接口所以要用... on 类名声明要展开的类型{ Get { Article(limit: 2) { title author { ... on Author { name email } } } } }这样文章 → 作者就在一轮往返里取完再往作者身上挂articles还能继续钻取。小提示每展开一层引用都是一次额外查询引用字段上记得加limit。 用 Aggregate 做聚合统计从查对象到出报表Aggregate与Get是并列的根字段语法风格一致。统计某类对象总数、并按分类分组计数{ Aggregate { Article(groupBy: category) { category { value count } meta { count } } } }meta.count是该类总数category下的value/count是各分组结果。小提示groupBy只接受普通属性不能直接对引用属性分组。定位查询报错的三板斧GraphiQL、错误字段、服务端日志查询不听话时按顺序排查打开 GraphiQL 控制台GET /v1/graphql。字段自动补全、变量面板、错误高亮都齐备nearText这类长参数建议抽到变量里避免反复手敲。读响应里的errors字段。报错文案通常直接指向出错的参数——操作符拼错、值类型不匹配、属性不存在多数情况到这一步就能定位。查服务端日志。schema 里根本没有这个字段多半是类或属性没建好可以搜索graphql_rebuild关键字schema 每次随数据库结构重建时都会打这条日志来源就是 adapters/handlers/graphql/schema.go 里的构建入口。真正落库执行查询的接口定义在 adapters/handlers/graphql/local/resolver.go需要深挖实现时从这里进。⚡ 让查询变快的 5 条实操建议向量搜索把limit压小10~20 足够——近似搜索只需返回 top-kk 越小检索越快。给向量搜索叠加where条件——先缩小候选集再做相似度计算比较次数直接下降。不要用offset深翻页——深分页要逐条跳过前面的记录页码越深越慢尽量用字段条件如时间、ID 范围做游标式翻页。把多层嵌套引用拍平——每多展开一层就多一次查询结构上能预合并就预合并。_additional只取需要的元数据——距离、分数都要额外计算全量请求是白白开销。下一步想看更多可运行的查询用例参考 test/acceptance/graphql_resolvers/解析层实现在 usecases/traverser/。GraphQL 负责读取写入和管理类结构走 REST 接口实现位于 adapters/handlers/rest/。版本提示本文示例基于当前主干的 GraphQL 语法v1.x 系列使用nearText前请确认目标类已配置向量化模块。【免费下载链接】weaviateWeaviate is an open-source vector database that stores both objects and vectors, allowing for the combination of vector search with structured filtering with the fault tolerance and scalability of a cloud-native database.项目地址: https://gitcode.com/GitHub_Trending/we/weaviate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
