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).

Philosophy

The DSL inroduced in this library is trying to stay close to the terminology and strucutre of the actual JSON DSL used by Elasticsearch; it doesn’t try to invent a new DSL, instead it aims at providing a more convenient way how to write, and manipulate, queries without limiting you to a subset of functionality. Since it uses the same terminology and building blocks no special knowledge, on top of familiarity with the query DSL, should be required.

Example

With the low-level client you would write something like this:

from elasticsearch import Elasticsearch
es = Elasticsearch()

response = es.search(
    index="my-index",
    body={
      "query": {
        "filtered": {
          "query": {
            "bool": {
              "must": [{"match": {"title": "python"}}],
              "must_not": [{"match": {"description": "beta"}}]
            }
          },
          "filter": {"term": {"category": "search"}}
        }
      },
      "aggs" : {
        "per_tag": {
          "terms": {"field": "tags"},
          "aggs": {
            "max_lines": {"max": {"field": "lines"}}
          }
        }
      }
    }
)
for hit in response['hits']['hits']:
    print(hit['_score'], hit['_source']['title'])

Which could be very hard to modify (imagine adding another filter to that query) and is definitely no fun to write. With the python DSL you can write the same query as:

from elasticsearch_dsl import Search, Q

s = Search(using=es).index("my-index") \
    .filter("term", category="search") \
    .query("match", title="python")   \
    .query(~Q("match", description="beta"))

s.aggs.bucket('per_tag', 'terms', field='tags')\
    .metric('max_lines', 'max', field='lines')

response = s.execute()
for hit in response:
    print(hit._meta.score, hit.title)

for b in response.aggregations.per_tag.buckets:
    print(b.key, b.max_lines.value)

The library will take care of:

composing queries/filters into compound queries/filters

creating filtered queries when .filter() has been used

providing a convenient wrapper around responses

no curly or square brackets everywhere!

Migration

If you already have existing code using the elasticsearch-py library you can easily start using this DSL without committing to porting your entire application. You can create the Search object from current query dict, work with it and, at the end, serialize it back to dict to send over the wire:

body = {...} # insert complicated query here
# convert to search
s = Search.from_dict(body)
# add some filters, aggregations, queries, ...
s.filter("term", tags="python")
# optionally convert back to dict to plug back into existing code
body = s.to_dict()

Since the DSL is built on top of the low-level client there should be nothing stopping you from using your existing code or just dropping down to the low level API whenever required; for example for all the APIs not (yet) covered by the DSL.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Metadata

Release files for elasticsearch-dsl 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for elasticsearch-dsl 0.0.2
File	Size	Uploaded
elasticsearch-dsl-0.0.2.tar.gz	13.0 kB	Aug 27, 2014	Details

Built distribution (wheel)

Table of built distributions (wheels) for elasticsearch-dsl 0.0.2
File	Interpreter	ABI	Platform	Reset
elasticsearch_dsl-0.0.2-py2.py3-none-any.whl 18.7 kB Aug 27, 2014	Python 2, Python 3	none	any	Details

Total release size: 31.7 kB

Release files / elasticsearch-dsl-0.0.2.tar.gz

Download URL	elasticsearch-dsl-0.0.2.tar.gz
Size	13.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ad6ff946323027b255debcb66e3e035e545d5f8427bb5638b62e3b246d4d88a`
BLAKE2b-256 checksum How to use checksums	`a83ff0eeae1377e0aa99c0d0ea1e98580a7efd4978dccc39e0ddb97f1f4affd0`
Upload date	Aug 27, 2014
Uploaded using Trusted Publishing? What is trusted publishing?	No

Release files / elasticsearch_dsl-0.0.2-py2.py3-none-any.whl

Download URL	elasticsearch_dsl-0.0.2-py2.py3-none-any.whl
Size	18.7 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`8c465c9649d5de3e17b46385722a490511110b603ca3c13ad9c77132a467c42c`
BLAKE2b-256 checksum How to use checksums	`cab8a61902cf7ee13e4f726ac95bd5646ebf5bca91588c7bd867ac1e6aef15d5`
Upload date	Aug 27, 2014
Uploaded using Trusted Publishing? What is trusted publishing?	No