Elasticsearch DSL

A high-level Python library for Elasticsearch that provides an idiomatic way to write and manipulate queries. Built on top of the official low-level elasticsearch-py client, it stays close to the Elasticsearch JSON DSL while exposing the whole range of functionality through Python classes and expressions. This package also provides optional document persistence with Python object mapping and index management capabilities.

Note: As of version 8.18.0, this package serves as a compatibility layer that redirects imports to elasticsearch.dsl in the main elasticsearch package.

Package Information

• Package Name: elasticsearch-dsl
• Language: Python
• Installation: pip install elasticsearch-dsl
• Python Support: 3.8+
• Dependencies: elasticsearch>=8.0.0, python-dateutil, typing-extensions

Core Imports

import elasticsearch_dsl

Common imports for document and search operations:

from elasticsearch_dsl import Document, Search, Q, A, connections

Field types for document mapping:

from elasticsearch_dsl import Text, Keyword, Date, Integer, Boolean, Object, Nested

Basic Usage

from elasticsearch_dsl import Document, Search, Text, Keyword, Date, Integer, connections

# Configure connection
connections.create_connection(hosts=['localhost:9200'])

# Define a document
class Article(Document):
    title = Text(analyzer='snowball')
    body = Text(analyzer='snowball')
    tags = Keyword()
    published_date = Date()
    view_count = Integer()
    
    class Index:
        name = 'blog_articles'

# Create index and mappings
Article.init()

# Create and save a document
article = Article(
    title='Getting Started with Elasticsearch DSL',
    body='This article explains how to use elasticsearch-dsl...',
    tags=['elasticsearch', 'python', 'tutorial'],
    published_date='2023-10-01',
    view_count=150
)
article.save()

# Search for documents
search = Search(index='blog_articles')
search = search.filter('term', tags='elasticsearch')
search = search.query('match', title='elasticsearch')

response = search.execute()
for hit in response:
    print(f"{hit.title} - Views: {hit.view_count}")

Architecture

Elasticsearch DSL organizes functionality into several key components:

• Documents: Object-relational mapping between Python objects and Elasticsearch documents
• Search: Query builder and execution with fluent API
• Fields: Type system for document structure and Elasticsearch mapping
• Queries: Comprehensive query DSL mirroring Elasticsearch's JSON query syntax
• Aggregations: Statistical analysis and data grouping operations
• Analysis: Text processing, tokenization, and custom analyzer configuration
• Connections: Client connection management with support for multiple clusters

This architecture enables both simple document operations and complex analytical queries while maintaining type safety and providing a Pythonic interface to Elasticsearch's full feature set.

Capabilities

Document Operations

Object-relational mapping for Elasticsearch documents with automatic index management, CRUD operations, bulk processing, and lifecycle hooks. Supports both synchronous and asynchronous operations.

class Document:
    def __init__(self, **kwargs): ...
    def save(self, **kwargs): ...
    def delete(self, **kwargs): ...
    @classmethod
    def get(cls, id, **kwargs): ...
    @classmethod
    def init(cls, **kwargs): ...

class AsyncDocument:
    async def save(self, **kwargs): ...
    async def delete(self, **kwargs): ...
    @classmethod
    async def get(cls, id, **kwargs): ...

Document Operations

Search and Query Building

Fluent API for building and executing Elasticsearch queries with support for filtering, sorting, pagination, and result processing. Includes both basic and advanced query types.

class Search:
    def __init__(self, **kwargs): ...
    def query(self, query, **kwargs): ...
    def filter(self, query, **kwargs): ...
    def exclude(self, query, **kwargs): ...
    def sort(self, *keys): ...
    def execute(self): ...

def Q(name, **params): ...

Search and Queries

Field Types and Mapping

Comprehensive field type system for defining document structure and Elasticsearch mappings with support for all Elasticsearch field types including text, numeric, date, geographic, and specialized fields.

class Text:
    def __init__(self, analyzer=None, **kwargs): ...

class Keyword:
    def __init__(self, **kwargs): ...

class Date:
    def __init__(self, format=None, **kwargs): ...

class Integer:
    def __init__(self, **kwargs): ...

class Object:
    def __init__(self, properties=None, **kwargs): ...

class Nested:
    def __init__(self, **kwargs): ...

Field Types

Aggregations and Analytics

Statistical analysis and data grouping with support for metric aggregations, bucket aggregations, and pipeline aggregations. Enables complex analytical queries and data summarization.

def A(name, **params): ...

class Aggs:
    def bucket(self, name, agg_type, **params): ...
    def metric(self, name, agg_type, **params): ...

Aggregations

Text Analysis and Processing

Custom analyzer creation, tokenizer configuration, and text processing setup for multilingual and domain-specific search requirements.

def analyzer(name, **kwargs): ...
def tokenizer(name, **kwargs): ...
def char_filter(name, **kwargs): ...
def token_filter(name, **kwargs): ...

Analysis

Connection Management

Connection configuration and management for single and multiple Elasticsearch clusters with support for authentication, SSL, connection pooling, and both synchronous and asynchronous clients.

def create_connection(alias='default', **kwargs): ...
def get_connection(alias='default'): ...
def configure(**kwargs): ...

# Async variants
def create_async_connection(alias='default', **kwargs): ...
def get_async_connection(alias='default'): ...

Connections

Index Management and Operations

Index creation, configuration, and lifecycle management with support for settings, mappings, aliases, and templates. Enables comprehensive control over Elasticsearch indices and their behavior.

class Index:
    def __init__(self, name, using=None): ...
    def settings(self, **kwargs): ...
    def create(self, ignore=400, **kwargs): ...
    def delete(self, ignore=404, **kwargs): ...

class IndexTemplate:
    def __init__(self, name, using=None): ...
    def body(self, **kwargs): ...
    def create(self, **kwargs): ...

Index Management

Error Handling

The library raises specific exceptions for different error conditions:

class ElasticsearchDslException(Exception): ...
class UnknownDslObject(ElasticsearchDslException): ...
class ValidationException(ElasticsearchDslException): ...
class IllegalOperation(ElasticsearchDslException): ...

Common exceptions from the underlying elasticsearch package should also be handled in application code.