New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Elasticsearch Python DSL Tutorials »
Elastic Docs ›Elasticsearch Python Client [8.18] ›Elasticsearch Python DSL

Configuration

edit
A newer version is available. Check out the latest documentation.

Configuration

edit

There are several ways to configure connections for the library. The easiest and most useful approach is to define one default connection that can be used every time an API call is made without explicitly passing in other connections.

Unless you want to access multiple clusters from your application, it is highly recommended that you use the create_connection method and all operations will use that connection automatically.

Default connection

edit

To define a default connection that can be used globally, use the connections module and the create_connection method like this:

from elasticsearch.dsl import connections

connections.create_connection(hosts=['localhost'], timeout=20)

Single connection with an alias

edit

You can define the alias or name of a connection so you can easily refer to it later. The default value for alias is default.

from elasticsearch.dsl import connections

connections.create_connection(alias='my_new_connection', hosts=['localhost'], timeout=60)

Additional keyword arguments (hosts and timeout in our example) will be passed to the Elasticsearch class from elasticsearch-py.

To see all possible configuration options refer to the documentation.

Multiple clusters

edit

You can define multiple connections to multiple clusters at the same time using the configure method:

from elasticsearch.dsl import connections

connections.configure(
    default={'hosts': 'localhost'},
    dev={
        'hosts': ['esdev1.example.com:9200'],
        'sniff_on_start': True
    }
)

Such connections will be constructed lazily when requested for the first time.

You can alternatively define multiple connections by adding them one by one as shown in the following example:

# if you have configuration options to be passed to Elasticsearch.__init__
# this also shows creating a connection with the alias 'qa'
connections.create_connection('qa', hosts=['esqa1.example.com'], sniff_on_start=True)

# if you already have an Elasticsearch instance ready
connections.add_connection('another_qa', my_client)

Using aliases

edit

When using multiple connections, you can refer to them using the string alias specified when you created the connection.

This example shows how to use an alias to a connection:

s = Search(using='qa')

A KeyError will be raised if there is no connection registered with that alias.

Manual

edit

If you don’t want to supply a global configuration, you can always pass in your own connection as an instance of elasticsearch.Elasticsearch with the parameter using wherever it is accepted like this:

s = Search(using=Elasticsearch('localhost'))

You can even use this approach to override any connection the object might be already associated with:

s = s.using(Elasticsearch('otherhost:9200'))

When using the dsl module, it is highly recommended that you use the built-in serializer (elasticsearch.dsl.serializer.serializer) to ensure your objects are correctly serialized into JSON every time. The create_connection method that is described here (and that the configure method uses under the hood) will do that automatically for you, unless you explicitly specify your own serializer. The built-in serializer also allows you to serialize your own objects - just define a to_dict() method on your objects and that method will be automatically called when serializing your custom objects to JSON.

« Elasticsearch Python DSL Tutorials »

On this page

Was this helpful?
Feedback