Deprecate graphql_raw_query

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:

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]]: ...

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}
 

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(