11-19 更新 实时
首页/ 技术栈/ 正文

GraphQL API 弃用:时间表与迁移路径

技术栈 来源:Weaviate Blog 2026-10-26 08:00 0 阅读 机器翻译
GraphQL API 弃用:时间表与迁移路径

GraphQL 是 Weaviate 的第一个查询 API,自我们最早的版本发布以来,许多人都在它之上进行了构建。今天,我们将其弃用。今天不会有任何东西立刻中断。使用 GraphQL 的集群可以继续使用到 2027 年 5 月 1 日,这是 GraphQL 在 Weaviate Cloud 上的终止支持日期。我们可以帮助您完成迁移。无论您的部署形态如何,都可以通过支持门户或 support@weaviate.io 联系我们的支持团队。GraphQL 迁移指南会带您完成迁移,而本文则解释原因、各时间节点会发生什么,以及您有哪些选择。

长期以来,GraphQL 为 Weaviate 及其用户提供了良好的服务。它为您提供了一种可读的语言,覆盖所有类型的搜索,而您在 Weaviate 上构建的许多东西都经过它。我们为这项工作感到自豪。我们正在转向一个现代化的查询 API,以下是您将获得的好处:

速度:gRPC 通过 HTTP/2 发送二进制 Protocol Buffers,因此查询占用的带宽更少,返回速度也比基于 HTTP 的 JSON 更快。关于 gRPC 性能的文章中有实测数据。

清晰的契约:带类型的消息让每个客户端都能获得带类型的结果和生成好的请求对象,因此无需拼接查询字符串,也无需解析嵌套 JSON。错误以真实的状态码返回,而不是以 HTTP 200 加一个 errors 数组的形式返回。元数据是结果上的一个字段,而不是单独的 _additional 块。

契合细粒度访问控制的安全机制:GraphQL 的内省(introspection)需要对每个集合都有读取权限,这与按集合分配权限的基于角色的访问控制(RBAC)并不契合。gRPC 和 REST API 只检查您实际查询的那个集合的权限。

为当今查询的编写方式而构建:GraphQL 的优势在于它是一种你可以阅读并手写的查询语言。如今,大多数查询由客户端库、框架和智能体构建。紧凑的二进制协议和纯 JSON API 比手写的查询语言更适合它们。

可扩展到大量集合:一个包含大量集合的 Weaviate 实例,是我们越来越常遇到的使用场景。然而,如果你的集合数量很大(例如 1000+),每次新增或删除集合都可能耗费大量时间,因为这需要重建完整的 GraphQL schema。淘汰 GraphQL 可消除这一瓶颈。

单一 API 还意味着每个搜索功能只需构建、测试和编写文档一次,这让我们能更快地交付改进。

只有当你通过 GraphQL 向 Weaviate 发送查询时,这才会影响到你。以下说明如何判断你是否这样做。

你自己的代码发送 GraphQL:

客户端或工具替你发送:

本指南说明了如何查找你的 GraphQL 使用情况。

如果你通过 LangChain 或 LlamaIndex 等框架访问 Weaviate,请使用基于当前客户端构建的官方 Weaviate 集成。社区包可能仍会发送 GraphQL。

当前的 Python、TypeScript、Java 和 C# 客户端通过 gRPC 进行搜索,这是我们推荐的路径。如果你使用 Go,则应迁移到 v6 客户端,它使用 gRPC。参见指南中的客户端库章节。

对于无法建立原生 gRPC 连接的浏览器和边缘运行时,TypeScript Web 客户端(@weaviate/web)使用 gRPC-Web。它现已可用,API 与 Node 客户端相同。参见面向 Web 的 TypeScript 客户端。

对于完全无法运行客户端的技术栈,REST Search API 提供用于搜索和聚合的纯 JSON 端点(参见 REST API 参考文档)。它目前处于 Preview 阶段。它是 GraphQL 所提供功能的一个子集,因此在开始之前,请先查看那些尚无 REST 等价形式的查询。

目前有少数 GraphQL 专有功能尚无等价形式。指南将它们列在“尚无等价形式的 GraphQL 功能”之下。我们致力于覆盖客户所需的功能。如果你依赖的某项功能尚未覆盖,请联系支持团队,我们会着手添加。

迁移指南将 GraphQL 查询映射到其替代方案。从弃用到 Weaviate Cloud 上的生命周期结束之间有六个月时间,因此你可以围绕自身的发布节奏来规划迁移。而且你今天就可以在自己的实例上关闭 GraphQL,从而发现是否有任何功能会出错。

以下是在 Movie 集合上进行的一次近文本搜索,用四种方式编写:在 scifi 类别中找出 1980 年及以后上映的五部“space opera”电影,并返回 title、year 和 distance。

{ Get { Movie( nearText: { concepts: ["space opera"] } limit: 5 where: { operator: And operands: [ { path: ["year"], operator: GreaterThanEqual, valueInt: 1980 } { path: ["category"], operator: Equal, valueText: "scifi" } ] } ) { title year _additional { distance } } } } from weaviate.classes.query import Filter, MetadataQuery movies = client.collections.use("Movie") response = movies.query.near_text( query="space opera", limit=5, filters=( Filter.by_property("year").greater_or_equal(1980) & Filter.by_property("category").equal("scifi") ), return_properties=["title", "year"], return_metadata=MetadataQuery(distance=True), ) for o in response.objects: print(o.properties, o.metadata.distance) import weaviate, { Filters } from "@weaviate/web"; const client = await weaviate.connectToWeaviateCloud(WEAVIATE_URL, { authCredentials: new weaviate.ApiKey(WEAVIATE_API_KEY), }); const movies = client.collections.use("Movie"); const response = await movies.query.nearText("space opera", { limit: 5, filters: Filters.and( movies.filter.byProperty("year").greaterOrEqual(1980), movies.filter.byProperty("category").equal("scifi"), ), returnProperties: ["title", "year"], returnMetadata: ["distance"], }); for (const o of response.objects) { console.log(o.properties, o.metadata?.distance); } POST /v1/search/Movie/near-text

{ "query": ["space opera"], "limit": 5, "where": { "operator": "And", "operands": [ { "path": ["year"], "operator": "GreaterThanEqual", "valueInt": 1980 }, { "path": ["category"], "operator": "Equal", "valueText": "scifi" } ] }, "returnProperties": ["title", "year"], "returnMetadata": ["distance"] } 自托管 Weaviate 你现在就可以测试。将 DISABLE_GRAPHQL 环境变量设为 true 并重启 Weaviate,即可禁用 GraphQL。它也可以作为运行时配置键 disable_graphql 使用。

禁用 GraphQL 后,POST /v1/graphql 和 POST /v1/graphql/batch 会返回 HTTP 422:

{ "error": [{ "message": "graphql api is disabled" }] } 在 2027 年 5 月 1 日之前发布的所有 Weaviate 版本都会保留可用的 GraphQL API。该日期之后的第一个次要版本将默认禁用它,你可以在完成迁移的过程中把它重新打开。我们会在之后的某个版本中将其移除,但该日期尚未确定。

Weaviate Cloud 分两步关闭 GraphQL。2026 年 12 月 1 日,我们会在过去 30 天内未使用过 GraphQL 的集群上关闭它,因为这些集群上没有任何东西依赖它。2027 年 5 月 1 日,我们会在所有剩余集群上关闭它。2027 年 5 月 1 日是 Weaviate Cloud 上 GraphQL 的生命周期终止日期。新建集群时就已经不再启用 GraphQL。

如果你的集群被安排在 12 月 1 日关闭,而你认为它仍需要 GraphQL,请联系支持团队,我们会稍后再关闭。如果你想提前测试,支持团队可以在你指定的集群上将其关闭。

一旦 GraphQL 在你的集群上被关闭,GraphQL 请求的失败方式与设置了 DISABLE_GRAPHQL 时相同:返回 HTTP 422,并提示 graphql api is disabled。要在此期限之前了解你的应用会有何表现,可以针对自托管实例或新建集群(创建时就不带 GraphQL)进行测试。

需要协助规划此次迁移的 Weaviate Cloud 和企业版客户,可以通过支持门户或发送邮件至 support@weaviate.io 联系我们。

我们会帮您顺利完成这次迁移。无论您的部署方式如何,即便您并不清楚自己的 GraphQL 请求来自哪里,也请联系支持团队,我们会与您一起解决。如果您所依赖的某个查询或功能目前还没有对应实现,请告诉我们,我们会设法把缺失的部分补上。

欢迎查阅 Quickstart 教程,或注册一个免费的 Weaviate Cloud 账户。

译文由英文原文机器翻译,术语按行业惯例统一,可在文末展开原文核对。

查看英文原文(Deprecating the GraphQL API: timeline and migration paths)

GraphQL was Weaviate's first query API, and many of you have built on it since our earliest releases. Today we are deprecating it. Nothing breaks today. Clusters that use GraphQL keep it until May 1, 2027, the end-of-life date for GraphQL on Weaviate Cloud. We can help you through the migration. Contact our support team through the support portal or at support@weaviate.io, whatever your setup looks like. The GraphQL migration guide walks you through the move, and this post explains why, what happens when, and what your options are.

In short
  • The GraphQL API is deprecated as of October 26, 2026. Nothing breaks on that day.
  • Weaviate Cloud switches GraphQL off on all clusters on May 1, 2027. May 1, 2027 is the end-of-life date for GraphQL on Weaviate Cloud. If your cluster has not used GraphQL in the last 30 days, it is switched off on December 1, 2026. New Weaviate Cloud clusters are already created without GraphQL.
  • We are emailing all Weaviate Cloud customers so you know whether your clusters are affected.
  • If you are on Weaviate Cloud and need help, contact support through the support portal or at support@weaviate.io.
  • Every Weaviate version released before May 1, 2027 keeps a working GraphQL API. The first minor release after that date disables it by default, and you can switch it back on. It is removed in a later release.
  • If your application searches through a current Python, TypeScript, Java or C# client, you are most likely not affected. Everyone else should follow the migration guide.

Modernizing Weaviate's query API​

GraphQL served Weaviate and its users well for a long time. It gave you one readable language for every kind of search, and a lot of what you built on Weaviate went through it. We are proud of that work. We are moving to one modern query API, and here is what you gain:

  • Speed: gRPC sends binary Protocol Buffers over HTTP/2, so queries use less bandwidth and return faster than JSON over HTTP. The gRPC performance post has the measurements.

  • Clear contracts: Typed messages give every client typed results and generated request objects, so there is no query string to assemble and no nested JSON to parse. Errors arrive as real status codes, not as HTTP 200 with an errors array. Metadata is a field on the result, not a separate _additional block.

  • Security that fits fine-grained access: GraphQL introspection needs read permission on every collection. That does not fit role-based access control (RBAC) with per-collection permissions. The gRPC and REST APIs check exactly the collection you query.

  • Built for how queries are written today: GraphQL's strength was a query language you could read and type by hand. Today most queries are built by client libraries, frameworks and agents. A compact binary protocol and a plain JSON API serve them better than a hand-written query language.

  • Scales to many collections: A Weaviate instance with many collections is a use case we see more and more often. However, if you have a large number of collections (e.g. 1000+), each addition or removal of a collection may take a significant amount of time as it requires a rebuild of the full GraphQL schema. Retiring GraphQL eliminates this bottleneck.

One API also means every search feature is built, tested and documented once, which lets us ship improvements faster.

Timeline​

Timeline: September 30, 2026, new Weaviate Cloud clusters are created without GraphQL. October 26, 2026, GraphQL is deprecated and nothing changes in Weaviate Cloud or self-hosted Weaviate. December 1, 2026, GraphQL is switched off on Weaviate Cloud clusters that do not use it. May 1, 2027, GraphQL is switched off on all remaining Cloud clusters. The first minor release after May 1, 2027 disables GraphQL by default in self-hosted Weaviate, where you can switch it back on. A later release fully removes GraphQL from Weaviate.

Are you affected?​

This only affects you if you send queries to Weaviate over GraphQL. Here is how to tell whether you do.

Your own code sends GraphQL:

  • It sends HTTP requests to /v1/graphql directly.
  • It calls a raw GraphQL helper in a client, such as graphql_raw_query() in Python.
  • Browser code in your application posts GraphQL queries.

A client or tool sends it for you:

  • An older client: the Python v3 API (weaviate.Client), weaviate-ts-client v2, the Java client v5, or the Go client v5 and earlier send queries over GraphQL.
  • A no-code or BI tool that sends GraphQL to your cluster.

The guide explains how to find your GraphQL usage.

If you reach Weaviate through a framework such as LangChain or LlamaIndex, use the official Weaviate integration built on a current client. A community package may still send GraphQL.

What to use instead​

Client libraries (recommended)​

The current Python, TypeScript, Java and C# clients search over gRPC, and they are the path we recommend. If you use Go, the move is to the v6 client, which uses gRPC. See the client libraries section in the guide.

TypeScript web client​

For browsers and edge runtimes that cannot open a native gRPC connection, the TypeScript web client (@weaviate/web) uses gRPC-Web. It is available now, with the same API as the Node client. See the TypeScript client for web.

REST Search API​

For stacks that cannot run a client at all, the REST Search API offers plain JSON endpoints for search and aggregation (see the REST API reference). It is in Preview today. It is a subset of what GraphQL offers, so check the queries without a REST equivalent yet before you start.

A few GraphQL-only features have no equivalent today. The guide lists them under GraphQL features without an equivalent. We are committed to covering what our customers need. If anything you rely on is not covered, reach out to support and we will work on adding it.

How to migrate​

The migration guide maps GraphQL queries to their replacements. There are six months between the deprecation and the end of life on Weaviate Cloud, so you can plan the move around your own releases. And you can switch GraphQL off on your own instance today, so you find out if anything breaks.

  1. Find your GraphQL calls: Search your code, proxies and tools for /v1/graphql and raw GraphQL helpers. See find your GraphQL usage.
  2. Pick a path: Use a client library where you can, the TypeScript web client in the browser, and the REST Search API where neither fits. The guide has a decision table for this.
  3. Convert your queries: Use the Migration guide to map existing GraphQL queries to alternative methods.
  4. Verify with GraphQL disabled: Run your application against a Weaviate instance with GraphQL turned off. On Weaviate Cloud, contact support and we switch GraphQL off on a cluster of your choice so you can test. See test with GraphQL disabled.
One query, four ways

Here is one near-text search on a Movie collection, written four ways: five "space opera" movies from 1980 or later in the scifi category, with title, year and distance.

  • GraphQL (deprecated)
  • Python client
  • TypeScript web client
  • REST Search API
{
Get {
Movie(
nearText: { concepts: ["space opera"] }
limit: 5
where: {
operator: And
operands: [
{ path: ["year"], operator: GreaterThanEqual, valueInt: 1980 }
{ path: ["category"], operator: Equal, valueText: "scifi" }
]
}
) {
title
year
_additional {
distance
}
}
}
}

Self-hosted Weaviate​

You can test today. Set the DISABLE_GRAPHQL environment variable to true and restart Weaviate to disable GraphQL. It is also available as the runtime-config key disable_graphql.

With GraphQL disabled, POST /v1/graphql and POST /v1/graphql/batch return HTTP 422:

{ "error": [{ "message": "graphql api is disabled" }] }

Every Weaviate version released before May 1, 2027 keeps a working GraphQL API. The first minor release after that date disables it by default, and you can switch it back on while you finish migrating. We will remove it in a later release, and we have not set that date yet.

Weaviate Cloud​

Weaviate Cloud switches GraphQL off in two steps. On December 1, 2026, we switch it off on clusters that have not used GraphQL in the last 30 days, since nothing on them depends on it. On May 1, 2027, we switch it off on all remaining clusters. May 1, 2027 is the end-of-life date for GraphQL on Weaviate Cloud. New clusters are already created without GraphQL.

If your cluster is scheduled for December 1 and you believe it still needs GraphQL, contact support and we switch it off later. If you want to test earlier, support can switch it off on a cluster of your choice.

Once GraphQL is switched off on your cluster, GraphQL requests fail the same way they do with DISABLE_GRAPHQL set: HTTP 422 with graphql api is disabled. To see how your application behaves before then, test it against a self-hosted instance or a new cluster, which is created without GraphQL.

Weaviate Cloud and Enterprise customers who need help planning the move can contact us through the support portal or at support@weaviate.io.

Get help​

We will get you through this migration. Whatever your setup, and even if you do not know where your GraphQL requests come from, contact support and we work it out with you. If a query or feature you rely on has no equivalent yet, tell us and we will try to add what is missing.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

正文保留英文原文,标题与摘要由机器翻译。

本文由采集器自动同步

原文发布于 Weaviate Blog(Deprecating the GraphQL API: timeline and migration paths),标题、摘要与正文由机器翻译,术语按行业惯例统一,未经人工逐句校订。

阅读原文 ↗