Use class-based queries and type-hinted documents in DSL documentation examples (#2857) (#2862)

* Use class-based queries and type-hinted documents in DSL documentation examples

* DSL migrating section

(cherry picked from commit d492524)

Co-authored-by: Miguel Grinberg <[email protected]>

Author: github-actions[bot]

docs/reference/dsl_how_to_guides.md

@@ -0,0 +1,35 @@
+# Migrating from the `elasticsearch-dsl` package  [_migrating_from_elasticsearch_dsl_package]
+
+In the past the Elasticsearch Python DSL module was distributed as a standalone package called `elasticsearch-dsl`. This package is now deprecated, since all its functionality has been integrated into the main Python client. We recommend all developers to migrate their applications and eliminate their dependency on the `elasticsearch-dsl` package.
+
+To migrate your application, all references to `elasticsearch_dsl` as a top-level package must be changed to `elasticsearch.dsl`. In other words, the underscore from the package name should be replaced by a period.
+
+Here are a few examples:
+
+```python
+# from:
+from elasticsearch_dsl import Date, Document, InnerDoc, Text, connections
+# to:
+from elasticsearch.dsl import Date, Document, InnerDoc, Text, connections
+
+# from:
+from elasticsearch_dsl.query import MultiMatch
+# to:
+from elasticsearch.dsl.query import MultiMatch
+
+# from:
+import elasticsearch_dsl as dsl
+# to:
+from elasticsearch import dsl
+
+# from:
+import elasticsearch_dsl
+# to:
+from elasticsearch import dsl as elasticsearch_dsl
+
+# from:
+import elasticsearch_dsl
+# to:
+from elasticsearch import dsl
+# and replace all references to "elasticsearch_dsl" in the code with "dsl"
+```

docs/reference/dsl_migrating.md

@@ -47,17 +47,17 @@ Let’s rewrite the example using the DSL module:
 
 ```python
 from elasticsearch import Elasticsearch
-from elasticsearch.dsl import Search
+from elasticsearch.dsl import Search, query, aggs
 
 client = Elasticsearch("https://localhost:9200")
 
 s = Search(using=client, index="my-index") \
-    .filter("term", category="search") \
-    .query("match", title="python")   \
-    .exclude("match", description="beta")
+    .query(query.Match("title", "python"))   \
+    .filter(query.Term("category", "search")) \
+    .exclude(query.Match("description", "beta"))
 
-s.aggs.bucket('per_tag', 'terms', field='tags') \
-    .metric('max_lines', 'max', field='lines')
+s.aggs.bucket('per_tag', aggs.Terms(field="tags")) \
+    .metric('max_lines', aggs.Max(field='lines'))
 
 response = s.execute()
 
@@ -68,9 +68,9 @@ for tag in response.aggregations.per_tag.buckets:
     print(tag.key, tag.max_lines.value)
 ```
 
-As you see, the library took care of:
+As you see, the DSL module took care of:
 
-* creating appropriate `Query` objects by name (eq. "match")
+* creating appropriate `Query` objects from classes
 * composing queries into a compound `bool` query
 * putting the `term` query in a filter context of the `bool` query
 * providing a convenient access to response data
@@ -89,19 +89,19 @@ from elasticsearch.dsl import Document, Date, Integer, Keyword, Text, connection
 connections.create_connection(hosts="https://localhost:9200")
 
 class Article(Document):
-    title = Text(analyzer='snowball', fields={'raw': Keyword()})
-    body = Text(analyzer='snowball')
-    tags = Keyword()
-    published_from = Date()
-    lines = Integer()
+    title: str = mapped_field(Text(analyzer='snowball', fields={'raw': Keyword()}))
+    body: str = mapped_field(Text(analyzer='snowball'))
+    tags: str = mapped_field(Keyword())
+    published_from: datetime
+    lines: int
 
     class Index:
         name = 'blog'
         settings = {
           "number_of_shards": 2,
         }
 
-    def save(self, ** kwargs):
+    def save(self, **kwargs):
         self.lines = len(self.body.split())
         return super(Article, self).save(** kwargs)
 
@@ -127,7 +127,7 @@ print(connections.get_connection().cluster.health())
 In this example you can see:
 
 * providing a default connection
-* defining fields with mapping configuration
+* defining fields with Python type hints and additional mapping configuration when necessary
 * setting index name
 * defining custom methods
 * overriding the built-in `.save()` method to hook into the persistence life cycle
@@ -141,12 +141,6 @@ You can see more in the `persistence` chapter.
 
 If you have your `Document`s defined you can very easily create a faceted search class to simplify searching and filtering.
 
-::::{note}
-This feature is experimental and may be subject to change.
-
-::::
-
-
 ```python
 from elasticsearch.dsl import FacetedSearch, TermsFacet, DateHistogramFacet
 
@@ -208,11 +202,12 @@ Using the DSL, we can now express this query as such:
 ```python
 from elasticsearch import Elasticsearch
 from elasticsearch.dsl import Search, UpdateByQuery
+from elasticsearch.dsl.query import Match
 
 client = Elasticsearch()
 ubq = UpdateByQuery(using=client, index="my-index") \
-      .query("match", title="python")   \
-      .exclude("match", description="beta") \
+      .query(Match("title", "python"))   \
+      .exclude(Match("description", "beta")) \
       .script(source="ctx._source.likes++", lang="painless")
 
 response = ubq.execute()
@@ -232,7 +227,7 @@ body = {...} # insert complicated query here
 s = Search.from_dict(body)
 
 # Add some filters, aggregations, queries, ...
-s.filter("term", tags="python")
+s.filter(query.Term("tags", "python"))
 
 # Convert back to dict to plug back into existing code
 body = s.to_dict()

docs/reference/dsl_tutorials.md

@@ -9,11 +9,12 @@ Elasticsearch DSL is a module of the official Python client that aims to help wi
 
 ```python
 from elasticsearch.dsl import Search
+from elasticsearch.dsl.query import Match, Term
 
 s = Search(index="my-index") \
-    .filter("term", category="search") \
-    .query("match", title="python")   \
-    .exclude("match", description="beta")
+    .query(Match("title", "python")) \
+    .filter(Term("category", "search")) \
+    .exclude(Match("description", "beta"))
 for hit in s:
     print(hit.title)
 ```
@@ -22,12 +23,13 @@ Or with asynchronous Python:
 
 ```python
 from elasticsearch.dsl import AsyncSearch
+from elasticsearch.dsl.query import Match, Term
 
 async def run_query():
     s = AsyncSearch(index="my-index") \
-        .filter("term", category="search") \
-        .query("match", title="python")   \
-        .exclude("match", description="beta")
+        .query(Match("title", "python")) \
+        .filter(Term("category", "search")) \
+        .exclude(Match("description", "beta"))
     async for hit in s:
         print(hit.title)
 ```

docs/reference/elasticsearch-dsl.md

@@ -16,4 +16,5 @@ toc:
       - file: dsl_tutorials.md
       - file: dsl_how_to_guides.md
       - file: dsl_examples.md
+      - file: dsl_migrating.md
   - file: client-helpers.md

docs/reference/toc.yml

@@ -72,6 +72,9 @@ def __nonzero__(self) -> bool:
     __bool__ = __nonzero__
 
     def __call__(self, *args: Any, **kwargs: Any) -> _S:
+        """
+        Add a query.
+        """
         s = self._search._clone()
 
         # we cannot use self._proxied since we just cloned self._search and
@@ -354,18 +357,22 @@ class SearchBase(Request[_R]):
     post_filter = ProxyDescriptor[Self]("post_filter")
     _response: Response[_R]
 
-    def __init__(self, **kwargs: Any):
+    def __init__(
+        self,
+        using: AnyUsingType = "default",
+        index: Optional[Union[str, List[str]]] = None,
+        **kwargs: Any,
+    ):
         """
         Search request to elasticsearch.
 
         :arg using: `Elasticsearch` instance to use
         :arg index: limit the search to index
-        :arg doc_type: only query this type.
 
         All the parameters supplied (or omitted) at creation type can be later
         overridden by methods (`using`, `index` and `doc_type` respectively).
         """
-        super().__init__(**kwargs)
+        super().__init__(using=using, index=index, **kwargs)
 
         self.aggs = AggsProxy[_R](self)
         self._sort: List[Union[str, Dict[str, Dict[str, str]]]] = []
@@ -383,9 +390,15 @@ def __init__(self, **kwargs: Any):
         self._post_filter_proxy = QueryProxy(self, "post_filter")
 
     def filter(self, *args: Any, **kwargs: Any) -> Self:
+        """
+        Add a query in filter context.
+        """
         return self.query(Bool(filter=[Q(*args, **kwargs)]))
 
     def exclude(self, *args: Any, **kwargs: Any) -> Self:
+        """
+        Add a negative query in filter context.
+        """
         return self.query(Bool(filter=[~Q(*args, **kwargs)]))
 
     def __getitem__(self, n: Union[int, slice]) -> Self: