diff --git a/_includes/graphql-deprecation.mdx b/_includes/graphql-deprecation.mdx new file mode 100644 index 000000000..849c831e7 --- /dev/null +++ b/_includes/graphql-deprecation.mdx @@ -0,0 +1,7 @@ +:::warning The GraphQL API is deprecated + +Weaviate Cloud switches off the GraphQL API on **April 1, 2027**. Clusters that do not use GraphQL have it switched off from November 1, 2026. New Weaviate Cloud clusters are already created with GraphQL disabled. Self-hosted Weaviate keeps GraphQL until at least April 1, 2027. 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. + +Use a [client library](/weaviate/client-libraries), the [web client](/weaviate/client-libraries/typescript/web-client) or the REST Search API instead. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). + +::: diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx index 3a207a379..32f46aaaf 100644 --- a/docs/cloud/faq.mdx +++ b/docs/cloud/faq.mdx @@ -111,7 +111,11 @@ Each user can have one (1) free cluster, and by default each organization can ha
Answer -New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). To query your data, use one of these alternatives: +New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). The GraphQL API is deprecated, and Weaviate Cloud switches it off on existing clusters on **April 1, 2027**. Clusters that do not use GraphQL have it switched off from November 1, 2026. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). + +{/* TODO(ivan): Q7. Confirm whether existing clusters can turn GraphQL off early, and whether extensions exist. */} + +To query your data, use one of these alternatives: - A [client library](/weaviate/client-libraries) for your programming language. - The [REST Search endpoints](/weaviate/api/rest). diff --git a/docs/cloud/manage-clusters/default-settings.mdx b/docs/cloud/manage-clusters/default-settings.mdx index 6d222e9ce..12e1e0ddd 100644 --- a/docs/cloud/manage-clusters/default-settings.mdx +++ b/docs/cloud/manage-clusters/default-settings.mdx @@ -29,6 +29,10 @@ import AdvancedOptions from "/docs/cloud/img/weaviate-cloud-cluster-advanced-set | `CORS_ALLOW_ORIGIN` | Yes | https://console.weaviate.cloud | Yes (to allow any) | | [`REPLICATION_MINIMUM_FACTOR`](/deploy/configuration/env-vars/index.md#REPLICATION_MINIMUM_FACTOR) | Yes | 3 (for HA clusters) | No | +The GraphQL API is deprecated. Weaviate Cloud switches it off on existing clusters on April 1, 2027. Clusters that do not use GraphQL have it switched off from November 1, 2026. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). + +{/* TODO(ivan): Q7. Confirm Weaviate Cloud sets DISABLE_GRAPHQL to true on existing clusters at the switch-off, or uses another mechanism. */} + The user configurable settings appear as toggles in the `Advanced configuration` section of the cluster `Dashboard`: `Enable MCP Read-Only`, `Enable auto schema generation`, and `Allow all CORS origins`.
diff --git a/docs/deploy/configuration/env-vars/index.md b/docs/deploy/configuration/env-vars/index.md index 7e656dfe4..2e0f6949a 100644 --- a/docs/deploy/configuration/env-vars/index.md +++ b/docs/deploy/configuration/env-vars/index.md @@ -41,7 +41,7 @@ import APITable from '@site/src/components/APITable'; | `DEFAULT_VECTOR_INDEX` | Default vector index type for new collections (and named vectors), used when the collection definition does not specify one. An explicit `vectorIndexType` in the collection definition still takes precedence. Available values: `hnsw`, `flat`, `dynamic`, and `hfresh`. Runtime-configurable. Default: `hnsw`
Added in `v1.37.3` | `string` | `flat` | | `DEFAULT_VECTORIZER_MODULE` | Default vectorizer module - can be overridden by the vectorizer in the collection definition. | `string` | `text2vec-contextionary` | | `API_BASED_MODULES_DISABLED` | Weaviate automatically enables the usage of all [API-based modules](../../../weaviate/model-providers/index.md#api-based). Set this variable to `true` in order to limit access and only allow specific modules through the [`ENABLE_MODULES`](#ENABLE_MODULES) variable. Default: `false`
Added in `v1.33` | `boolean` | `true` | -| `DISABLE_GRAPHQL` | Disable the GraphQL API (default: `false`). When `true`, the `/v1/graphql` endpoint is not served. New [Weaviate Cloud](/cloud/manage-clusters/default-settings) clusters are created with this set to `true`. See [Can I use GraphQL with Weaviate Cloud?](/cloud/faq#graphql) for the alternatives. | `boolean` | `true` | +| `DISABLE_GRAPHQL` | Disable the GraphQL API (default: `false`). **The GraphQL API is deprecated.** The default will change to `true` in the first minor release after April 1, 2027. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). When `true`, the `/v1/graphql` endpoint is not served. New [Weaviate Cloud](/cloud/manage-clusters/default-settings) clusters are created with this set to `true`. See [Can I use GraphQL with Weaviate Cloud?](/cloud/faq#graphql) for the alternatives. | `boolean` | `true` | | `DISABLE_LAZY_LOAD_SHARDS` | When `false`, enable lazy shard loading to improve mean time to recovery in multi-tenant deployments. **Deprecated in `v1.36.6`.** Use `LAZY_LOAD_SHARD_COUNT_THRESHOLD` and `LAZY_LOAD_SHARD_SIZE_THRESHOLD_GB` instead. Weaviate now auto-detects when lazy loading is needed per collection. | `string` | `false` | | `DISABLE_STARTUP_BANNER` | Disable the banner Weaviate logs shortly after startup (`action=banner`, with the version, the link to [Improve your cluster](/improve-your-cluster), and this node's `/v1/meta` URL), and its repeat every `BANNER_INTERVAL`. The banner runs only while telemetry is enabled, because it fetches its art from weaviate.io, so a cluster with `DISABLE_TELEMETRY=true` never logs one. It is an `info` entry, so `LOG_LEVEL=warning` or stricter hides it as well. Default: `false`
Added in `v1.39.4` | `boolean` | `true` | | `DISABLE_TELEMETRY` | Disable [telemetry](/deploy/configuration/telemetry.md) data collection | boolean | `false` | diff --git a/docs/weaviate/api/graphql/additional-operators.md b/docs/weaviate/api/graphql/additional-operators.md index 8c84043c4..537d7f0ac 100644 --- a/docs/weaviate/api/graphql/additional-operators.md +++ b/docs/weaviate/api/graphql/additional-operators.md @@ -5,6 +5,11 @@ description: "Syntax reference for additional operators that extend query functi image: og/docs/api.jpg # tags: ['graphql', 'additional operators'] --- + +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import TryEduDemo from '/_includes/try-on-edu-demo.mdx'; diff --git a/docs/weaviate/api/graphql/additional-properties.md b/docs/weaviate/api/graphql/additional-properties.md index 36625f4d0..ba2235c63 100644 --- a/docs/weaviate/api/graphql/additional-properties.md +++ b/docs/weaviate/api/graphql/additional-properties.md @@ -5,6 +5,10 @@ description: "GraphQL API guide for accessing metadata and additional properties image: og/docs/api.jpg --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + import SkipLink from '/src/components/SkipValidationLink' import TryEduDemo from '/_includes/try-on-edu-demo.mdx'; diff --git a/docs/weaviate/api/graphql/aggregate.md b/docs/weaviate/api/graphql/aggregate.md index 2c50d9a0f..c332f6010 100644 --- a/docs/weaviate/api/graphql/aggregate.md +++ b/docs/weaviate/api/graphql/aggregate.md @@ -6,6 +6,10 @@ image: og/docs/api.jpg # tags: ['graphql', 'aggregate', 'aggregate{}', 'meta'] --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock'; import TryEduDemo from '/_includes/try-on-edu-demo.mdx'; diff --git a/docs/weaviate/api/graphql/explore.md b/docs/weaviate/api/graphql/explore.md index d7acc7272..d6bd306aa 100644 --- a/docs/weaviate/api/graphql/explore.md +++ b/docs/weaviate/api/graphql/explore.md @@ -6,6 +6,10 @@ image: og/docs/api.jpg # tags: ['graphql', 'explore{}'] --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + :::note Vector spaces and Explore The `Explore` function is disabled where multiple inference (e.g. `text2vec-xxx`) modules are enabled. diff --git a/docs/weaviate/api/graphql/filters.md b/docs/weaviate/api/graphql/filters.md index cc274b75b..73e5bf743 100644 --- a/docs/weaviate/api/graphql/filters.md +++ b/docs/weaviate/api/graphql/filters.md @@ -6,6 +6,9 @@ image: og/docs/api.jpg # tags: ['graphql', 'filters'] --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + import TryEduDemo from '/_includes/try-on-edu-demo.mdx'; diff --git a/docs/weaviate/api/graphql/get.md b/docs/weaviate/api/graphql/get.md index 0616c021a..5864ade23 100644 --- a/docs/weaviate/api/graphql/get.md +++ b/docs/weaviate/api/graphql/get.md @@ -6,6 +6,10 @@ image: og/docs/api.jpg # tags: ['graphql', 'get{}'] --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock'; import TryEduDemo from '/_includes/try-on-edu-demo.mdx'; diff --git a/docs/weaviate/api/graphql/index.md b/docs/weaviate/api/graphql/index.md index 4954ad937..a2a40ac7e 100644 --- a/docs/weaviate/api/graphql/index.md +++ b/docs/weaviate/api/graphql/index.md @@ -1,23 +1,20 @@ --- -title: Search (GraphQL | gRPC) +title: GraphQL API (deprecated) sidebar_position: 0 -description: "GraphQL and gRPC API documentation for flexible querying and data retrieval in Weaviate." +description: "Reference for Weaviate's deprecated GraphQL query API, and where to find its replacements." image: og/docs/api.jpg # tags: ['GraphQL references'] --- -:::note GraphQL on Weaviate Cloud -New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). To query your data on Weaviate Cloud, use a [client library](../../client-libraries/index.mdx) or the [REST Search endpoints](/weaviate/api/rest). -::: - -## API +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; -Weaviate offers [GraphQL](https://graphql.org/) and gRPC APIs for queries. + -We recommend using a Weaviate [client library](../../client-libraries/index.mdx), which abstracts away the underlying API calls and makes it easier to integrate Weaviate into your application. +## API -However, you can query Weaviate directly using GraphQL with a POST request to the `/graphql` endpoint, or write your own `gRPC` calls based on the [gRPC](../grpc.md) protobuf specification. +This section is the reference for Weaviate's [GraphQL](https://graphql.org/) query API. To search your data, use a Weaviate [client library](../../client-libraries/index.mdx). The current Python, TypeScript, Java and C# clients query over the [gRPC API](../grpc.md). +To move existing GraphQL queries to a client library, the web client or the REST Search API, see [Migrating from the GraphQL API](./migration.mdx). ## All references @@ -34,10 +31,6 @@ All references have their individual subpages. Click on one of the references be ## GraphQL API -### Why GraphQL? - -GraphQL is a query language built on using graph data structures. It is an efficient method of data retrieval and mutation, since it mitigates the common over-fetching and under-fetching problems of other query languages. - :::tip GraphQL is case-sensitive GraphQL is case-sensitive ([reference](https://spec.graphql.org/June2018/#sec-Names)), so make sure to use the correct casing when writing your queries. ::: diff --git a/docs/weaviate/api/graphql/migration.mdx b/docs/weaviate/api/graphql/migration.mdx index 246c23382..19d0756f2 100644 --- a/docs/weaviate/api/graphql/migration.mdx +++ b/docs/weaviate/api/graphql/migration.mdx @@ -1,16 +1,26 @@ --- title: Migrating from the GraphQL API -description: "How to express your existing GraphQL Get and Aggregate queries with the Weaviate client libraries, the browser client, or the REST Search API." +description: "The GraphQL API is deprecated. How to find your GraphQL usage and move Get and Aggregate queries to the Weaviate client libraries, the browser client, or the REST Search API." image: og/docs/api.jpg -unlisted: true --- import SkipLink from '/src/components/SkipValidationLink' +## What is changing and when + +The GraphQL API is deprecated as of October 12, 2026. **Nothing changes on that day, and existing clusters keep working.** Weaviate Cloud switches GraphQL off on November 1, 2026 for clusters that do not use it, and on April 1, 2027 for all remaining clusters. Self-hosted Weaviate keeps GraphQL working until at least April 1, 2027. 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, with no date set yet. + +| Stage | Weaviate Cloud | Self-hosted | +| --- | --- | --- | +| **Deprecated**, October 12, 2026 | Existing clusters keep working. New clusters are created with GraphQL disabled, as they already were before. | Nothing changes. GraphQL keeps working until at least April 1, 2027. | +| **Disabled by default** | Already the case for new clusters. | In the first minor release after April 1, 2027. You can switch GraphQL back on. | +| **Switched off or removed** | Switched off on November 1, 2026 for clusters that do not use GraphQL. Switched off on all remaining clusters on April 1, 2027. | Removed in a later release. No date is set yet. | + ## Who this guide is for -This guide is for developers who have working GraphQL `Get` and `Aggregate` queries and want to express the same searches through one of Weaviate's other query APIs. Typical reasons to be here: +This guide is for developers who have working GraphQL `Get` and `Aggregate` queries and need to express the same searches through one of Weaviate's other query APIs. Typical reasons to be here: +- The GraphQL API is **deprecated**. Code that still sends GraphQL queries stops working once GraphQL is disabled, so it needs to move before [the dates above](#what-is-changing-and-when). - You are moving an application to a **new Weaviate Cloud cluster**, which is created with **GraphQL disabled**. - You are building in the **browser** or on an edge runtime, where a plain gRPC client cannot run. - You maintain an **HTTP-only stack**, such as a no-code or BI tool, or a language without an official Weaviate client such as PHP or Ruby. @@ -27,12 +37,65 @@ Start at the top of this table and take the first row that describes your stack. The three paths are at three different maturity levels. Check the **Status** column before you commit to one. ::: +{/* TODO(ivan): Q5. Confirm the Preview, Alpha and beta labels below are still right on October 12, 2026. */} + | Path | Status | Availability | | --- | --- | --- | -| **Official client libraries** | Generally available | Python, JavaScript/TypeScript, Java, and C# are generally available while the Go client v6 is currently in [beta release](https://github.com/weaviate/weaviate-go-client/releases/tag/v6.0.0-beta.3). Earlier versions of the Go client rely on GraphQL. | +| **Official client libraries** | Generally available | Python, JavaScript/TypeScript, Java, and C# are generally available while the Go client v6 is currently a [release candidate](https://github.com/weaviate/weaviate-go-client/releases/tag/v6.0.0-rc.0). The current stable Go client, `v5`, relies on GraphQL. | | **`@weaviate/web`** (browser and edge) | **Alpha** | `3.15.0-alpha.6`. Requires Weaviate `v1.38.3` or later. See the [web client page](../../client-libraries/typescript/web-client.mdx). | | **REST Search API** | **Preview** | Enabled by default from `v1.39.7`. In `v1.39.0` through `v1.39.6` it needs [`EXPERIMENTAL_REST_SEARCH_ENABLED`](/deploy/configuration/env-vars/index.md#EXPERIMENTAL_REST_SEARCH_ENABLED) set to `true`. See [REST Search API](#rest-search-api). | +## Do you need to migrate + +You need to migrate if any part of your application sends GraphQL to Weaviate. The two checks below tell you whether it does, and let you prove it before GraphQL is switched off. + +### Find your GraphQL usage + +GraphQL can reach Weaviate in three ways, and an older client can send it without you writing a single query. + +
+ Where GraphQL hides, and which client versions use it + +Your code sends GraphQL queries if it does any of the following: + +- **Calls the endpoint directly.** It sends HTTP requests to `/v1/graphql` or `/v1/graphql/batch`, for example with `curl` or a generic HTTP library. +- **Uses a raw GraphQL helper.** Some clients can pass a GraphQL query string straight to the server. These helpers always use GraphQL, whatever the client generation. +- **Uses an older client generation.** Older clients build their queries as GraphQL under the hood. The Go client does this in its current stable generation too. + +Check each client your code uses against this table: + +| Client | Queries over gRPC from | Still uses GraphQL when | +| --- | --- | --- | +| Python `weaviate-client` | Search: `v4.4.0`. Aggregate: `v4.11.0`, against Weaviate `v1.29.0` or later | Aggregate and `len(collection)` fall back to GraphQL on Weaviate older than `v1.29.0`. `client.graphql_raw_query()` always uses GraphQL. | +| TypeScript `weaviate-client` | Search: `v3.0.0`. Aggregate: `v3.4.0`, against Weaviate `v1.29.0` or later | Aggregate falls back to GraphQL on Weaviate older than `v1.29.0`. | +| Java `io.weaviate:client6` | `6.0.0` | Never. | +| C# | `1.0.0` | Never. | +| Go `weaviate-go-client/v5` (current stable) | Never | Always. `client.GraphQL().Get()`, `.Aggregate()`, `.Explore()` and `.Raw()` are its search API. | +| Go v6 (release candidate) | `v6.0.0-rc.0`. Aggregate covers over-all, near-vector, near-text, near-object, hybrid and near-media | Never. No generative search yet at this tag. | + +
+ +### Test with GraphQL disabled + +A test instance with GraphQL switched off proves that your application no longer depends on it. + +
+ How to switch GraphQL off, and what a disabled endpoint returns + +Run your application against an instance with GraphQL switched off before you rely on it. On a non-production self-hosted instance, set the [`DISABLE_GRAPHQL`](/deploy/configuration/env-vars/index.md#DISABLE_GRAPHQL) environment variable to `true`. It is also available as the `disable_graphql` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) key. + +With GraphQL disabled, `POST /v1/graphql` and `POST /v1/graphql/batch` return HTTP `422` with this body: + +```json +{"error":[{"message":"graphql api is disabled"}]} +``` + +Authorization runs first, so a caller without read permission gets `403` instead. The Python client and the current Go client return an error that carries the same status code and message. + +A new Weaviate Cloud cluster is already in this state, so you can also test against one. + +
+ ## Client libraries (recommended) The client libraries cover every `Get` and `Aggregate` construct shown on this page, so each one has a direct equivalent. They query over gRPC, and give you typed results and generated request objects. @@ -221,9 +284,24 @@ One more request limit worth knowing: in `v1.39`, `limit`, `offset`, and their s
+## GraphQL features without an equivalent + +These GraphQL features have no equivalent in the gRPC API, the client libraries or the REST Search API today: + +- `Explore` +- `ask`, from the `qna` modules +- Summarization, from the `sum-transformers` module +- Named entity recognition, from the `ner-transformers` module +- `spellCheck` +- The `_additional` properties `featureProjection`, `semanticPath`, `interpretation` and `classification` + +If one of these is essential to your application, tell us through the channels under [Questions and feedback](#questions-and-feedback). Within reason, we will add what is missing. + +{/* TODO(ivan): Q3. State what happens to these features once Dirk confirms. Until then, keep "no equivalent today". */} + ## Further resources -- [Search (GraphQL | gRPC)](./index.md) - the GraphQL and gRPC search API reference +- [GraphQL API (deprecated)](./index.md) - the GraphQL API reference - [gRPC-Web](../grpc.md#grpc-web) - the browser-reachable gRPC interface - [Client libraries](../../client-libraries/index.mdx) - installation and connection for each language - [Web client](../../client-libraries/typescript/web-client.mdx) - install steps and browser notes for `@weaviate/web` @@ -234,6 +312,10 @@ One more request limit worth knowing: in `v1.39`, `limit`, `offset`, and their s All three paths are actively being developed, and feedback on this guide, especially a query you could not convert, directly shapes what gets built next. +We are helping with the migration through office hours, webinars and support tickets. If a query has no equivalent in the paths above, say so. Within reason we will add what is missing, for example additional parameters on the REST Search API. + +{/* TODO(ivan): Add dates or links for the office hours and webinars once scheduled. */} + import DocsFeedback from '/\_includes/docs-feedback.mdx'; diff --git a/docs/weaviate/api/graphql/search-operators.md b/docs/weaviate/api/graphql/search-operators.md index bfaafe29a..9d6f685d9 100644 --- a/docs/weaviate/api/graphql/search-operators.md +++ b/docs/weaviate/api/graphql/search-operators.md @@ -6,6 +6,10 @@ image: og/docs/api.jpg # tags: ['graphql', 'search operators'] --- +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + import SearchOperators from '/_includes/feature-notes/search-operators.mdx'; diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md index f0ea87e96..923179209 100644 --- a/docs/weaviate/api/grpc.md +++ b/docs/weaviate/api/grpc.md @@ -1,13 +1,13 @@ --- title: gRPC -description: "gRPC API integration guide for high-performance, efficient communication with Weaviate database instances." +description: "The gRPC API is Weaviate's search API, used by the client libraries for high-performance queries." image: og/docs/api.jpg # tags: ['schema'] --- -Starting with Weaviate `v1.19.0`, a gRPC interface has been progressively added to Weaviate. gRPC is a high-performance, open-source universal RPC framework that is contract-based and can be used in any environment. It is based on HTTP/2 and Protocol Buffers, and is therefore very fast and efficient. +The gRPC API is Weaviate's search API. The client libraries use it to run searches and aggregations. gRPC is a high-performance, open-source universal RPC framework that is contract-based and can be used in any environment. It is based on HTTP/2 and Protocol Buffers, and is therefore very fast and efficient. -As of Weaviate `v1.23.7`, the gRPC interface is considered stable. The [Python](../client-libraries/python/index.mdx), [TypeScript](../client-libraries/typescript/index.mdx), [Java](../client-libraries/java/index.mdx), and [C#](../client-libraries/csharp.mdx) client libraries use gRPC. The [Go](../client-libraries/go.md) client uses gRPC for batch imports, and offers gRPC search through its experimental API. +The gRPC interface was introduced in Weaviate `v1.19.0` and is considered stable as of `v1.23.7`. The current [Python](../client-libraries/python/index.mdx), [TypeScript](../client-libraries/typescript/index.mdx), [Java](../client-libraries/java/index.mdx), and [C#](../client-libraries/csharp.mdx) client libraries query over gRPC. The current stable [Go](../client-libraries/go.md) client still queries over the [deprecated GraphQL API](./graphql/index.md). The Go client v6, currently a release candidate, queries over gRPC. ## Protocol Buffer (Protobuf) definitions @@ -46,7 +46,7 @@ services: ### Client-side -You can use the gRPC interface through the [Python](../client-libraries/python/index.mdx), [TypeScript](../client-libraries/typescript/index.mdx), [Java](../client-libraries/java/index.mdx), and [C#](../client-libraries/csharp.mdx) client libraries. The [Go](../client-libraries/go.md) client sends batch imports over gRPC. Its gRPC search API is still experimental, and is reached through `Experimental().Search()` rather than the regular query builder. +You can use the gRPC interface through the [Python](../client-libraries/python/index.mdx), [TypeScript](../client-libraries/typescript/index.mdx), [Java](../client-libraries/java/index.mdx), and [C#](../client-libraries/csharp.mdx) client libraries. The current stable [Go](../client-libraries/go.md) client sends batch imports over gRPC, but queries over GraphQL. The Go client v6, currently a release candidate, queries over gRPC. See [Migrating from the GraphQL API](./graphql/migration.mdx#find-your-graphql-usage). Alternatively, you can use other tools, such as the `grpcurl` command-line tool, to interact with the gRPC API. Some options include: diff --git a/docs/weaviate/api/index.mdx b/docs/weaviate/api/index.mdx index 6d75e86a4..202ac58ab 100644 --- a/docs/weaviate/api/index.mdx +++ b/docs/weaviate/api/index.mdx @@ -1,6 +1,6 @@ --- title: APIs -description: "API documentation covering REST, GraphQL, and gRPC interfaces for Weaviate database operations." +description: "API documentation covering the REST, REST Search, and gRPC interfaces for Weaviate, and the deprecated GraphQL API." image: og/docs/api.jpg # tags: ['schema'] --- @@ -11,16 +11,16 @@ Weaviate provides multiple Application Programming Interfaces (APIs) to interact - Includes operations for managing collections (creating, reading, updating, deleting collections and their definitions), performing basic CRUD (Create, Read, Update, Delete) operations on individual data objects, checking node status, backups, and managing cluster health. - The machine-readable specification behind this reference is published at `https://docs.weaviate.io/openapi.json`. See [Machine-readable API specification](#machine-readable-api-specification) below. - - The reference also lists an experimental REST Search API (the `/v1/search/{collection}/...` and `/v1/aggregate/{collection}` endpoints), which is enabled by default from `v1.39.7`. In `v1.39.0` through `v1.39.6` it is disabled unless [`EXPERIMENTAL_REST_SEARCH_ENABLED`](/deploy/configuration/env-vars/index.md#EXPERIMENTAL_REST_SEARCH_ENABLED) is set to `true`, and rejects requests with a `422` status. + - The reference also lists the **REST Search API** (the `/v1/search/{collection}/...` and `/v1/aggregate/{collection}` endpoints), a **preview** feature for stacks that cannot run a client library. It is enabled by default from `v1.39.7`. In `v1.39.0` through `v1.39.6` it is disabled unless [`EXPERIMENTAL_REST_SEARCH_ENABLED`](/deploy/configuration/env-vars/index.md#EXPERIMENTAL_REST_SEARCH_ENABLED) is set to `true`, and rejects requests with a `422` status. -- **[Search API - GraphQL](./graphql/index.md)**: Designed specifically for data querying and exploration. +- **[gRPC API](./grpc.md)**: The search API, used by the client libraries. - - Enables complex search operations, including semantic (vector) search (`nearText`, `nearVector`, etc.), keyword search (`bm25`), hybrid search, filtering, retrieving specific data properties, aggregations, and exploring connections between data objects (cross-references). - - Not available on new Weaviate Cloud clusters. They are created with GraphQL disabled. Use a [client library](../client-libraries/index.mdx) or the [REST Search endpoints](/weaviate/api/rest) instead. + - Covers search, filtering, aggregation, and batch data imports. It leverages Protocol Buffers for faster serialization, lower latency, and efficient data streaming compared to traditional REST/JSON communication. -- **[Search API - gRPC](./grpc.md)**: A high-performance alternative for GraphQL when it comes to demanding data operations. +- **[GraphQL API (deprecated)](./graphql/index.md)**: A query API for search and aggregation. - - gRPC is progressively being implemented for various Weaviate operations, particularly focusing on search/query functionalities and batch data imports. It leverages Protocol Buffers for faster serialization, lower latency, and efficient data streaming compared to traditional REST/JSON communication. + - Deprecated. Weaviate Cloud switches it off on April 1, 2027. New Weaviate Cloud clusters are already created with GraphQL disabled. + - To move existing queries, see [Migrating from the GraphQL API](./graphql/migration.mdx). ## Machine-readable API specification @@ -47,12 +47,13 @@ Weaviate offers official client libraries for these programming languages: - **[TypeScript/JavaScript](../client-libraries/typescript/index.mdx)** - **[Go](../client-libraries/go.md)** - **[Java](../client-libraries/java/index.mdx)** +- **[C#](../client-libraries/csharp.mdx)** :::tip **TIP:** Using the official client libraries for interacting with Weaviate -The client libraries abstract away the complexities of making direct REST, GraphQL, or gRPC calls. You interact with Weaviate using idiomatic methods and objects in your preferred language. +The client libraries abstract away the complexities of making direct REST or gRPC calls. You interact with Weaviate using idiomatic methods and objects in your preferred language. -Modern versions of the client libraries are designed to **automatically utilize the more performant gRPC interface** for search and query operations whenever possible and supported by the Weaviate instance you are connected to. They handle the negotiation and use the optimal protocol under the hood, typically requiring only the standard connection details (like the REST endpoint URL and authentication keys) for setup. +The current Python, TypeScript, Java, and C# clients send search and query operations over **gRPC**. The current stable Go client still queries over GraphQL. Its v6 successor, currently a release candidate, uses gRPC. See [Find your GraphQL usage](./graphql/migration.mdx#find-your-graphql-usage). ::: diff --git a/docs/weaviate/client-libraries/go.md b/docs/weaviate/client-libraries/go.md index f7d553846..8ca33d320 100644 --- a/docs/weaviate/client-libraries/go.md +++ b/docs/weaviate/client-libraries/go.md @@ -24,6 +24,14 @@ The latest Go client is version `v||site.go_client_version||`. ::: +:::warning The Go client and the deprecated GraphQL API + +The current Go client sends its queries over the [GraphQL API](/weaviate/api/graphql), which is deprecated. Those calls fail once GraphQL is disabled. The Go client v6 queries over gRPC instead. It is currently a [release candidate](https://github.com/weaviate/weaviate-go-client/releases/tag/v6.0.0-rc.0). See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). + +::: + +{/* TODO(ivan): Q5. Confirm the Go client v6 is still a pre-release on October 12, 2026. */} + For the minimum supported Go version, see the [`go` directive in `go.mod`](https://github.com/weaviate/weaviate-go-client/blob/v||site.go_client_version||/go.mod) for client `v||site.go_client_version||`. ## Installation diff --git a/docs/weaviate/concepts/interface.md b/docs/weaviate/concepts/interface.md index 19e682187..363885617 100644 --- a/docs/weaviate/concepts/interface.md +++ b/docs/weaviate/concepts/interface.md @@ -32,6 +32,10 @@ Weaviate has both a RESTful API and a GraphQL API. Currently, there is no featur ## GraphQL +import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx'; + + + ### Why GraphQL? We have chosen to use a GraphQL API, for multiple reasons: diff --git a/docusaurus.config.js b/docusaurus.config.js index abd4fd49b..66f58cdcf 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -201,8 +201,8 @@ const config = { ({ image: "og/default.jpg", announcementBar: { - id: "announcement-bar-engram-2026", - content: `Introducing Engram — managed memory for AI agents, built on Weaviate`, + id: "announcement-bar-graphql-deprecation-2026", + content: `The GraphQL API is deprecated and will be switched off on Weaviate Cloud on April 1, 2027. See the migration guide`, backgroundColor: "#1C1468", textColor: "#F5F5F5", isCloseable: true, diff --git a/sidebars.js b/sidebars.js index bbc9a8262..fb6e81a32 100644 --- a/sidebars.js +++ b/sidebars.js @@ -874,15 +874,22 @@ const sidebars = { label: "RESTful API", className: "sidebar-item", }, + { + type: "doc", + id: "weaviate/api/grpc", + label: "gRPC", + className: "sidebar-item", + }, { type: "category", - label: "Search API - GraphQL/gRPC", + label: "GraphQL (deprecated)", className: "sidebar-item", link: { type: "doc", id: "weaviate/api/graphql/index", }, items: [ + "weaviate/api/graphql/migration", "weaviate/api/graphql/get", "weaviate/api/graphql/aggregate", "weaviate/api/graphql/search-operators", @@ -892,12 +899,6 @@ const sidebars = { "weaviate/api/graphql/explore", ], }, - { - type: "doc", - id: "weaviate/api/grpc", - label: "gRPC", - className: "sidebar-item", - }, ], }, ], diff --git a/src/theme/ContentVisibility/Unlisted/index.js b/src/theme/ContentVisibility/Unlisted/index.js deleted file mode 100644 index bcf2c99a1..000000000 --- a/src/theme/ContentVisibility/Unlisted/index.js +++ /dev/null @@ -1,21 +0,0 @@ -import React from "react"; -import { UnlistedMetadata } from "@docusaurus/theme-common"; - -/** - * Swizzled from @docusaurus/theme-classic. - * - * The upstream component renders two things for an `unlisted: true` page: - * (the `noindex, nofollow` robots meta) and a caution - * banner reading "This page is unlisted." - * - * We keep the metadata and drop the banner. Unlisted pages in this repo are - * finished, hand-distributed pages rather than drafts, so the banner would tell - * a reader who was given the link that the page is provisional. The metadata is - * load-bearing and must stay: besides the robots meta itself, the sitemap - * plugin decides what to exclude by reading the emitted `noindex` meta - * (@docusaurus/plugin-sitemap `isNoIndexMetaRoute`), so removing it would put - * unlisted pages back into sitemap.xml. - */ -export default function Unlisted() { - return ; -}