From 52e604bff8e573156003b7e05b0e73b0e495a091 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 20 Oct 2026 17:08:12 +0200
Subject: [PATCH] Deprecate graphql_raw_query

---
 docs/changelog.rst          |  1 +
 weaviate/client_executor.py |  4 ++++
 weaviate/warnings.py        | 10 ++++++++++
 3 files changed, 15 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 007e75ab7..dc9f0cb2e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -13,6 +13,7 @@ This minor version includes:
     - Backwards compatibility:
         - Every ``_``-prefixed spelling is still importable from the module that defines it, and is the same object as its public counterpart, so ``isinstance`` checks and existing imports of it are unaffected
         - A private spelling that was only ever reachable through a module that happened to import it — the executor modules, and a few of the ``config_*`` modules — is no longer reachable there. Import configuration types from ``weaviate.classes.config``, or from ``weaviate.collections.classes.config``
+    - Deprecate ``client.graphql_raw_query()``, which will be removed in a release after May 1, 2027, when Weaviate retires the GraphQL API. Use the collection query methods or the REST Search API instead
 
 Version 4.23.1
 --------------
diff --git a/weaviate/client_executor.py b/weaviate/client_executor.py
index 3125fd9cd..94742f17d 100644
--- a/weaviate/client_executor.py
+++ b/weaviate/client_executor.py
@@ -29,6 +29,7 @@
 from .types import NUMBER
 from .util import _decode_json_response_dict
 from .validator import _validate_input, _ValidateArgument
+from .warnings import _Warnings
 
 TIMEOUT_TYPE = Union[Tuple[NUMBER, NUMBER], NUMBER]
 
@@ -227,6 +228,8 @@ def exc(e: Exception) -> bool:
     def graphql_raw_query(self, gql_query: str) -> executor.Result[_RawGQLReturn]:
         """Allows to send graphQL string queries, this should only be used for weaviate-features that are not yet supported.
 
+        Deprecated: use the collection query methods or the REST Search API instead. This method will be removed in a release after May 1, 2027 when we retire GraphQL support.
+
         Be cautious of injection risks when generating query strings.
 
         Args:
@@ -240,6 +243,7 @@ def graphql_raw_query(self, gql_query: str) -> executor.Result[_RawGQLReturn]:
             weaviate.exceptions.WeaviateConnectionError: If the network connection to weaviate fails.
             weaviate.exceptions.UnexpectedStatusCodeError: If weaviate reports a none OK status.
         """
+        _Warnings.graphql_raw_query_deprecated()
         _validate_input(_ValidateArgument([str], "gql_query", gql_query))
         json_query = {"query": gql_query}
 
diff --git a/weaviate/warnings.py b/weaviate/warnings.py
index 8985aa1dc..b3de774aa 100644
--- a/weaviate/warnings.py
+++ b/weaviate/warnings.py
@@ -273,6 +273,16 @@ def async_enabled_field_removed_server_side() -> None:
             stacklevel=1,
         )
 
+    @staticmethod
+    def graphql_raw_query_deprecated() -> None:
+        warnings.warn(
+            message="""Dep031: graphql_raw_query() is deprecated and will be removed from the client in a release after May 1, 2027, when Weaviate retires the GraphQL API.
+            Use the collection query methods or the REST Search API instead.
+            See https://docs.weaviate.io/weaviate/api/graphql/migration for how to migrate.""",
+            category=DeprecationWarning,
+            stacklevel=1,
+        )
+
     @staticmethod
     def datetime_insertion_with_no_specified_timezone(date: datetime) -> None:
         warnings.warn(