Skip to content

Commit

Permalink
Update docs before 8.9.0 release (#1669)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pquentin
pquentin committed Sep 7, 2023
1 parent 29ca74d commit 3073976
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 68 deletions.
51 changes: 23 additions & 28 deletions README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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
--------------
Expand All @@ -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",
Expand Down Expand Up @@ -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") \
Expand All @@ -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
Expand All @@ -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()})
Expand Down Expand Up @@ -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.

Expand Down
78 changes: 38 additions & 40 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/elastic/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
Expand All @@ -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
--------

Expand All @@ -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.

Expand All @@ -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

Expand All @@ -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
--------------
Expand All @@ -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" : {
Expand Down Expand Up @@ -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") \
Expand All @@ -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
Expand All @@ -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()})
Expand All @@ -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()
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 3073976

Please sign in to comment.