From e1728bdbc4932bb0776ec1b8455a1b2a6d731d86 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 1/2] Deprecate graphql_raw_query

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

diff --git a/docs/changelog.rst b/docs/changelog.rst
index b93e07a3c..8cc311a47 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -1,6 +1,11 @@
 Changelog
 =========
 
+Version 4.24.1
+--------------
+This patch version includes:
+    - Deprecate ``client.graphql_raw_query()`` (Dep031), 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.24.0
 --------------
 This minor version includes:
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(

From 4cda91e23771222e5d1ee31235e4b1201056182f Mon Sep 17 00:00:00 2001
From: Dirk Kulawiak <dirk@semi.technology>
Date: Fri, 23 Oct 2026 10:28:51 +0200
Subject: [PATCH 2/2] Mark graphql_raw_query deprecated in client stubs

---
 weaviate/client.pyi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/weaviate/client.pyi b/weaviate/client.pyi
index d7b99eba6..8d83e27c4 100644
--- a/weaviate/client.pyi
+++ b/weaviate/client.pyi
@@ -4,6 +4,8 @@ Client class definition.
 
 from typing import Any, Dict, Optional, Tuple, Union
 
+from typing_extensions import deprecated
+
 from weaviate.aliases.async_ import _AliasAsync
 from weaviate.aliases.sync import _Alias
 from weaviate.client_executor import _WeaviateClientExecutor
@@ -46,6 +48,9 @@ class WeaviateAsyncClient(_WeaviateClientExecutor[ConnectionAsync]):
     def is_connected(self) -> bool: ...
     async def is_live(self) -> bool: ...
     async def is_ready(self) -> bool: ...
+    @deprecated(
+        "Dep031: graphql_raw_query() is deprecated and 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."
+    )
     async def graphql_raw_query(self, gql_query: str) -> _RawGQLReturn: ...
     async def get_meta(self) -> dict: ...
     async def get_open_id_configuration(self) -> Optional[Dict[str, Any]]: ...
@@ -71,6 +76,9 @@ class WeaviateClient(_WeaviateClientExecutor[ConnectionSync]):
     def is_connected(self) -> bool: ...
     def is_live(self) -> bool: ...
     def is_ready(self) -> bool: ...
+    @deprecated(
+        "Dep031: graphql_raw_query() is deprecated and 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."
+    )
     def graphql_raw_query(self, gql_query: str) -> _RawGQLReturn: ...
     def get_meta(self) -> dict: ...
     def get_open_id_configuration(self) -> Optional[Dict[str, Any]]: ...