Deprecating the GraphQL API: timeline and migration paths

弃用 GraphQL API：时间线和迁移路径 | Weaviate

GraphQL 是 Weaviate 的首个查询 API，自我们最早的版本发布以来，许多用户已经基于它构建了应用。今天，我们宣布弃用该 API。今天不会有任何功能中断。使用 GraphQL 的集群将持续保留该 API 直到 2027 年 5 月 1 日（Weaviate Cloud 上 GraphQL 的生命周期结束日期）。我们可以协助您完成迁移。无论您的部署方式如何，都可以通过支持门户或发送邮件至 [email protected] 联系我们的支持团队。GraphQL 迁移指南将带您逐步完成迁移过程，本文则解释了弃用原因、具体影响以及您的迁移选项。

简而言之：

• 自 2026 年 10 月 26 日起，GraphQL API 正式进入弃用状态。当天不会有任何功能中断。

• Weaviate Cloud 将于 2027 年 5 月 1 日在所有集群中彻底关闭 GraphQL。2027 年 5 月 1 日是 Weaviate Cloud 上 GraphQL 的生命周期结束日期。如果您的集群在过去 30 天内未使用过 GraphQL，将在 2026 年 12 月 1 日被自动关闭。所有新创建的 Weaviate Cloud 集群将默认不包含 GraphQL。

• 我们正在通过邮件通知所有 Weaviate Cloud 客户，以便您确认是否受到影响。

• 如果您使用 Weaviate Cloud 并需要帮助，请通过支持门户或发送邮件至 [email protected] 联系支持团队。

• 在 2027 年 5 月 1 日之前发布的所有 Weaviate 版本均保留可用的 GraphQL API。该日期之后的第一个次要版本将默认禁用 GraphQL，但您可手动重新启用。后续版本将彻底移除该功能。

• 如果您的应用通过当前的 Python、TypeScript、Java 或 C# 客户端进行搜索，很可能不受影响。其他用户应遵循迁移指南进行操作。

现代化 Weaviate 的查询 API

GraphQL 在很长一段时间内为 Weaviate 及其用户提供了良好的服务。它为每种类型的搜索提供了一种可读的语言，许多基于 Weaviate 构建的功能都通过它实现。我们为此感到自豪。现在我们正在转向一个现代的查询 API，您将获得以下优势：

• 性能提升：gRPC 通过 HTTP/2 传输二进制 Protocol Buffers，相比 HTTP 上的 JSON，查询消耗的带宽更少且响应速度更快。gRPC 性能分析文章中包含具体数据。

• 清晰的接口定义：类型化消息为每个客户端提供类型化结果和生成的请求对象，无需手动拼接查询字符串或解析嵌套 JSON。错误以真实的状态码形式返回，而非 HTTP 200 响应中的错误数组。元数据作为结果字段存在，而非独立的 _additional 块。

• 更契合细粒度访问控制的安全性：GraphQL 的内省功能需要对每个集合拥有读取权限，这与基于集合的权限控制（RBAC）不兼容。gRPC 和 REST API 会精确检查您查询的集合权限。

• 适配现代查询编写方式：GraphQL 的优势曾是可手动编写和输入的查询语言。但如今大多数查询由客户端库、框架和代理自动生成。紧凑的二进制协议和简洁的 JSON API 比手动编写的查询语言更适合现代需求。

统一的 API 意味着每个搜索功能只需构建、测试和文档化一次，使我们能够更快地推出改进功能。

时间线

是否会影响您？

只有在通过 GraphQL 向 Weaviate 发送查询时，您才会受到影响。以下是判断方法：

您的代码直接发送 GraphQL：

• 直接向 /v1/graphql 发送 HTTP 请求。

• 在客户端中调用原始 GraphQL 辅助函数，例如 Python 中的 graphql_raw_query()。

• 应用中的浏览器代码发布 GraphQL 查询。

客户端或工具代您发送：

• 旧版客户端：Python v3 API（weaviate.Client）、weaviate-ts-client v2、Java 客户端 v5 或 Go 客户端 v5 及更早版本通过 GraphQL 发送查询。

• 无代码或 BI 工具通过 GraphQL 向您的集群发送请求。

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

如果通过 LangChain 或 LlamaIndex 等框架访问 Weaviate，请使用基于最新客户端的官方 Weaviate 集成。社区包可能仍然使用 GraphQL。

建议替代方案

客户端库（推荐）

当前 Python、TypeScript、Java 和 C# 客户端通过 gRPC 进行搜索，这是我们推荐的路径。如果您使用 Go，应迁移到使用 gRPC 的 v6 客户端。请参阅指南中的客户端库部分。

TypeScript Web 客户端

对于无法建立原生 gRPC 连接的浏览器和边缘运行时，TypeScript Web 客户端（@weaviate/web）使用 gRPC-Web。该客户端现已发布，API 与 Node 客户端相同。请参阅 Web 的 TypeScript 客户端。

REST 搜索 API

对于完全无法运行客户端的系统，REST 搜索 API 提供了用于搜索和聚合的纯 JSON 端点（参见 REST API 参考）。该 API 当前处于预览阶段。它仅提供 GraphQL 的一部分功能，因此在开始之前，请检查是否有尚未支持 REST 等效查询的功能。

目前一些 GraphQL 独有功能尚无等效替代方案。指南在“无等效替代的 GraphQL 功能”部分列出了这些功能。我们致力于满足客户的需求。如果您依赖的任何功能未被覆盖，请联系支持团队，我们将努力添加。

如何迁移

迁移指南将 GraphQL 查询映射到替代方案。在 Weaviate Cloud 上，从弃用到生命周期结束有六个月时间，您可以根据自己的发布计划安排迁移。您今天就可以在自己的实例上关闭 GraphQL，从而发现是否有任何功能被破坏。

• 查找 GraphQL 调用：在代码、代理和工具中搜索 /v1/graphql 和原始 GraphQL 辅助函数。参见 查找您的 GraphQL 使用情况。

• 选择路径：在可使用客户端库的地方使用客户端库，在浏览器中使用 TypeScript Web 客户端，在两者都不适用的地方使用 REST 搜索 API。指南为此提供了决策表。

• 转换查询：使用迁移指南将现有 GraphQL 查询映射到替代方法。

• 禁用 GraphQL 后验证：在关闭了 GraphQL 的 Weaviate 实例上运行您的应用。在 Weaviate Cloud 上，联系支持团队，我们可以为您选择的集群关闭 GraphQL，以便您进行测试。参见 禁用 GraphQL 后的测试。

一种查询，四种实现方式

以下是对电影集合的近文本搜索，用四种方式实现：查找科幻类别中 1980 年或之后的五部“太空歌剧”电影，包含标题、年份和距离。

• GraphQL（已弃用）

• Python 客户端

• TypeScript Web 客户端

• REST 搜索 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
}
}
}
}

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。该日期之后的第一个次要版本默认禁用 GraphQL，您可以在完成迁移时重新启用它。我们将在后续版本中移除它，但尚未确定具体日期。

Weaviate 云服务 ​

Weaviate 云服务将通过两个阶段关闭 GraphQL。2026 年 12 月 1 日，我们将关闭过去 30 天内未使用 GraphQL 的集群，因为这些集群上没有依赖 GraphQL 的内容。2027 年 5 月 1 日，我们将关闭所有剩余的集群。2027 年 5 月 1 日是 Weaviate 云服务上 GraphQL 的生命周期结束日期。新的集群在创建时已默认不包含 GraphQL。

如果您的集群计划在 12 月 1 日关闭，并且您认为仍然需要使用 GraphQL，请联系支持团队，我们可以延迟关闭。如果您希望提前测试，支持团队可以为您选择的集群关闭 GraphQL。

一旦您的集群关闭了 GraphQL，GraphQL 请求将像设置了 DISABLE_GRAPHQL 一样失败：返回 HTTP 422 并提示 graphql api is disabled。在关闭之前，您可以通过自托管实例或新集群（创建时不含 GraphQL）测试应用程序的表现。

需要帮助规划迁移的 Weaviate 云服务和企业客户，可以通过支持门户或发送邮件至 [email protected] 联系我们。

获取帮助 ​

我们将协助您完成此次迁移。无论您的使用场景如何，即使您不清楚 GraphQL 请求的来源，也请联系支持团队，我们将与您共同解决。如果您依赖的某个查询或功能目前尚无对应替代方案，请告知我们，我们将尽力补充缺失的部分。

- 支持服务（面向所有人）：通过支持门户或发送邮件至 [email protected] 联系我们的支持团队  
- 社区问题：在 Weaviate 论坛提问  

## 准备开始构建了吗？  

查看 [快速入门教程](#) ，或注册免费的 Weaviate Cloud 账户。