一条请求搞定向量搜索与聚合报表：Weaviate GraphQL 实战指南

一条请求搞定向量搜索与聚合报表Weaviate GraphQL 实战指南【免费下载链接】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一个真实场景前端页面要同时展示文章列表、作者信息、相似度评分。用 REST你得发三个请求再自己拼数据。换成 Weaviate开源向量数据库把文本、图片转成数字坐标做相似度检索一条 GraphQL 查询就能全拿回来。这条指南带你走完整链路发出第一条查询加 where 过滤跑 nearText 向量搜索跨类关联做 groupBy 聚合再进 GraphiQL 调试和调优。五分钟跑通第一条查询先看一条最小查询。假设库里有个Article类{ Get { Article(limit: 5) { title publicationDate // ... 其他字段按需添加不选就不返回 } } }把这段 POST 到/v1/graphql返回类似{ data: { Get: { Article: [ { publicationDate: 2025-04-01T00:00:00Z, title: GraphQL 入门 }, // ... 共 5 条未选的字段不会出现 ] } } }看到结果了再拆原理。GraphQL 服务在adapters/handlers/graphql/schema.go#L42的Resolve方法里执行查询。它拿到请求后交给解析层真正取数的入口是GetClass// adapters/handlers/graphql/local/get/resolver.go#L23 GetClass(ctx context.Context, principal *models.Principal, info dto.GetParams) ([]interface{}, error)你的查询参数limit、where、nearText 等都会打包进dto.GetParams最终变成一次数据读取。查询语法拆解where 过滤、nearText 向量搜索、字段裁剪用 where 子句做结构化过滤where 子句按结构化字段过滤语法是 path operator 值。{ Get { Article(limit: 5, where: { path: [category] operator: Equal valueString: AI }) { title } } }常用操作符Equal、GreaterThan、Like值里用%通配。文本字段用valueString数字字段用valueNumber。用 nearText 做向量搜索nearText 把一段文字现场向量化然后找最近的向量。两个关键参数{ Get { Article(limit: 5, nearText: { concepts: [机器学习趋势] // 要检索的文本向量化后搜索 distance: 0.8 // 最大距离越小相似度越高 }) { title _additional { distance // 每条结果的相似度距离 } } } }concepts是搜索内容distance是阈值超过这个距离的结果直接丢弃。用 _additional 取元数据并裁剪字段字段裁剪是 GraphQL 的本能选什么返回什么。除了distance_additional还有id、uuid等字段。不写的字段一行都不会传输。跨类关联与聚合统计引用字段上的嵌套查询Weaviate 的类之间可以互相引用比如Article.author指向Author。在引用字段上用... on片段就能展开另一类的数据{ Get { Article(where: { path: [title] operator: Like valueString: %GraphQL% }) { title author { ... on Author { name articles { title } // 作者的其他文章 } } } } }一次请求文章、作者、作者的其他作品全拉齐不需要客户端拼三张表。用 groupBy 聚合做报表Aggregate根字段做统计。加groupBy分组每组的值配meta { count }计数{ Aggregate { Article(groupBy: [category]) { category { value count } meta { count } // 总数 } } }分类计数、内容分布、监控看板一条聚合搞定不用把原始数据搬到应用层。访问 GraphiQL 与日志排查GraphiQL内置的查询调试台Weaviate 内置 GraphiQL。浏览器打开http://localhost:8080/v1/graphql开了认证时对话框输入 API key即可进入交互式编辑器左侧写查询自动补全右侧实时看 JSON 结果自带 Schema 浏览器可逐层翻每个类的字段变量框支持variables传参方便反复试同一个查询路由逻辑在adapters/handlers/graphql/graphiql/graphiql.go#L38。日志字段追踪 schema 重建Weaviate 在重建 GraphQL 模式时打日志。你查不到类、字段报不存在时先看这两个字段action: graphql_rebuildschema 或类结构变化、触发重建schema当时的模式内容位置在adapters/handlers/graphql/schema.go#L55类构建器在adapters/handlers/graphql/local/get/class_builder.go#L131也会打同类日志。日志里找不到 rebuild 记录大概率是 schema 根本没变去查你的类定义。性能调优清单只选必要字段GraphQL 按选择集返回不选的字段零传输。用 limit 和 offset 分页控制结果集省内存省带宽。给过滤字段配索引where 高频字段建索引查询更快。缓存重复查询相同查询结构走缓存少打数据库。盯 metrics 的 P95关注查询延迟和超时异常早发现。到这里过滤、向量搜索、关联、聚合四件套一条 GraphQL 请求全齐了。【免费下载链接】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），仅供参考