From aa5cb946a9f65175a453f4f376e146105581b2f3 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Wed, 6 Sep 2023 23:00:57 +0400 Subject: [PATCH] Update docs before 8.9.0 release --- README | 51 +++++++++++++++------------------ docs/index.rst | 78 ++++++++++++++++++++++++-------------------------- 2 files changed, 61 insertions(+), 68 deletions(-) diff --git a/README b/README index 3c4eb9d8f..234a3a83c 100644 --- a/README +++ b/README @@ -37,6 +37,9 @@ Compatibility The library is compatible with all Elasticsearch versions since ``2.x`` but you **have to use a matching major version**: +For **Elasticsearch 8.0** and later, use the major version 8 (``8.x.y``) of the +library. + For **Elasticsearch 7.0** and later, use the major version 7 (``7.x.y``) of the library. @@ -49,10 +52,12 @@ library. For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the library. - The recommended way to set your requirements in your `setup.py` or `requirements.txt` is:: + # Elasticsearch 8.x + elasticsearch-dsl>=8.0.0,<9.0.0 + # Elasticsearch 7.x elasticsearch-dsl>=7.0.0,<8.0.0 @@ -66,7 +71,7 @@ The recommended way to set your requirements in your `setup.py` or elasticsearch-dsl>=2.0.0,<3.0.0 -The development is happening on ``master``, older branches only get bugfix releases +The development is happening on ``main``, older branches only get bugfix releases Search Example -------------- @@ -76,7 +81,7 @@ Let's have a typical search request written directly as a ``dict``: .. code:: python from elasticsearch import Elasticsearch - client = Elasticsearch() + client = Elasticsearch("https://localhost:9200") response = client.search( index="my-index", @@ -118,7 +123,7 @@ Let's rewrite the example using the Python DSL: from elasticsearch import Elasticsearch from elasticsearch_dsl import Search - client = Elasticsearch() + client = Elasticsearch("https://localhost:9200") s = Search(using=client, index="my-index") \ .filter("term", category="search") \ @@ -138,15 +143,11 @@ Let's rewrite the example using the Python DSL: As you see, the library took care of: - * creating appropriate ``Query`` objects by name (eq. "match") - - * 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 - - * no curly or square brackets everywhere +- creating appropriate ``Query`` objects by name (eq. "match") +- 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 +- no curly or square brackets everywhere Persistence Example @@ -160,7 +161,7 @@ Let's have a simple Python class representing an article in a blogging system: from elasticsearch_dsl import Document, Date, Integer, Keyword, Text, connections # Define a default Elasticsearch client - connections.create_connection(hosts=['localhost']) + connections.create_connection(hosts="https://localhost:9200") class Article(Document): title = Text(analyzer='snowball', fields={'raw': Keyword()}) @@ -200,20 +201,14 @@ Let's have a simple Python class representing an article in a blogging system: In this example you can see: - * providing a default connection - - * defining fields with mapping configuration - - * setting index name - - * defining custom methods - - * overriding the built-in ``.save()`` method to hook into the persistence - life cycle - - * retrieving and saving the object into Elasticsearch - - * accessing the underlying client for other APIs +- providing a default connection +- defining fields with mapping configuration +- setting index name +- defining custom methods +- overriding the built-in ``.save()`` method to hook into the persistence + life cycle +- retrieving and saving the object into Elasticsearch +- accessing the underlying client for other APIs You can see more in the persistence chapter of the documentation. diff --git a/docs/index.rst b/docs/index.rst index c2c5f814c..76f77a56a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ Elasticsearch DSL Elasticsearch DSL is a high-level library whose aim is to help with writing and running queries against Elasticsearch. It is built on top of the official -low-level client (``elasticsearch-py``). +low-level client (`elasticsearch-py `_). It provides a more convenient and idiomatic way to write and manipulate queries. It stays close to the Elasticsearch JSON DSL, mirroring its @@ -17,6 +17,13 @@ document data in user-defined classes. To use the other Elasticsearch APIs (eg. cluster health) just use the underlying client. +Installation +------------ + +:: + + pip install elasticsearch-dsl + Examples -------- @@ -30,6 +37,9 @@ Compatibility The library is compatible with all Elasticsearch versions since ``2.x`` but you **have to use a matching major version**: +For **Elasticsearch 8.0** and later, use the major version 8 (``8.x.y``) of the +library. + For **Elasticsearch 7.0** and later, use the major version 7 (``7.x.y``) of the library. @@ -45,6 +55,9 @@ library. The recommended way to set your requirements in your `setup.py` or `requirements.txt` is:: + # Elasticsearch 8.x + elasticsearch-dsl>=8.0.0,<9.0.0 + # Elasticsearch 7.x elasticsearch-dsl>=7.0.0,<8.0.0 @@ -58,7 +71,7 @@ The recommended way to set your requirements in your `setup.py` or elasticsearch-dsl>=2.0.0,<3.0.0 -The development is happening on ``master``, older branches only get bugfix releases +The development is happening on ``main``, older branches only get bugfix releases Search Example -------------- @@ -68,20 +81,16 @@ Let's have a typical search request written directly as a ``dict``: .. code:: python from elasticsearch import Elasticsearch - client = Elasticsearch() + client = Elasticsearch("https://localhost:9200") response = client.search( index="my-index", body={ "query": { - "filtered": { - "query": { - "bool": { - "must": [{"match": {"title": "python"}}], - "must_not": [{"match": {"description": "beta"}}] - } - }, - "filter": {"term": {"category": "search"}} + "bool": { + "must": [{"match": {"title": "python"}}], + "must_not": [{"match": {"description": "beta"}}], + "filter": [{"term": {"category": "search"}}] } }, "aggs" : { @@ -114,7 +123,7 @@ Let's rewrite the example using the Python DSL: from elasticsearch import Elasticsearch from elasticsearch_dsl import Search - client = Elasticsearch() + client = Elasticsearch("https://localhost:9200") s = Search(using=client, index="my-index") \ .filter("term", category="search") \ @@ -134,15 +143,11 @@ Let's rewrite the example using the Python DSL: As you see, the library took care of: - * creating appropriate ``Query`` objects by name (eq. "match") - - * composing queries into a compound ``bool`` query - - * creating a ``filtered`` query since ``.filter()`` was used - - * providing a convenient access to response data - - * no curly or square brackets everywhere +- creating appropriate ``Query`` objects by name (eq. "match") +- 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 +- no curly or square brackets everywhere Persistence Example @@ -153,11 +158,10 @@ Let's have a simple Python class representing an article in a blogging system: .. code:: python from datetime import datetime - from elasticsearch_dsl import Document, Date, Integer, Keyword, Text - from elasticsearch_dsl.connections import connections + from elasticsearch_dsl import Document, Date, Integer, Keyword, Text, connections # Define a default Elasticsearch client - connections.create_connection(hosts=['localhost']) + connections.create_connection(hosts="https://localhost:9200") class Article(Document): title = Text(analyzer='snowball', fields={'raw': Keyword()}) @@ -177,7 +181,7 @@ Let's have a simple Python class representing an article in a blogging system: return super(Article, self).save(** kwargs) def is_published(self): - return datetime.now() >= self.published_from + return datetime.now() > self.published_from # create the mappings in elasticsearch Article.init() @@ -197,20 +201,14 @@ Let's have a simple Python class representing an article in a blogging system: In this example you can see: - * providing a :ref:`default connection` - - * defining fields with mapping configuration - - * setting index name - - * defining custom methods - - * overriding the built-in ``.save()`` method to hook into the persistence - life cycle - - * retrieving and saving the object into Elasticsearch - - * accessing the underlying client for other APIs +- providing a default connection +- defining fields with mapping configuration +- setting index name +- defining custom methods +- overriding the built-in ``.save()`` method to hook into the persistence + life cycle +- retrieving and saving the object into Elasticsearch +- accessing the underlying client for other APIs You can see more in the :ref:`persistence` chapter. @@ -284,7 +282,7 @@ Writing this as a ``dict``, we would have the following code: }, ) -Using the DSL, we can now express this query as such: +Using the DSL, we can now express this query as such: .. code:: python