Deprecate graphql_raw_query

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
 --------------

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(