Merge remote-tracking branch 'origin/main' into querying-docs

Author: pquentin

docs/docset.yml

@@ -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/_configuration.md renamed to docs/reference/dsl_configuration.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/_examples.md renamed to docs/reference/dsl_examples.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/_how_to_guides.md renamed to docs/reference/dsl_how_to_guides.md

@@ -41,13 +41,13 @@ client = Elasticsearch(
 
 Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment:
 
-:::{image} ../images/es-endpoint.jpg
+:::{image} images/es-endpoint.jpg
 :alt: Finding Elasticsearch endpoint
 :::
 
 You can generate an API key on the **Management** page under Security.
 
-:::{image} ../images/create-api-key.png
+:::{image} images/create-api-key.png
 :alt: Create API key
 :::