Skip to content

Update docs before 8.9.0 release #1669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 7, 2023
Merged

Update docs before 8.9.0 release #1669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 23 additions & 28 deletions README
View file
Open in desktop
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
Open in desktop
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