API Documentation

A Word About Forward-Compatibility Kwargs

In the following documentation, the phrase “other kwargs listed below” refers to the kwargs documented in a subsequent Parameters section. However, it also implicitly includes any kwargs the caller might care to make up and have passed to ES as query string parameters. These kwargs must start with es_ for forward compatibility and will be unprefixed and converted to strings as discussed in Features.

ElasticSearch API

Unless otherwise indicated, methods return the JSON-decoded response sent by elasticsearch.

class pyelasticsearch.ElasticSearch(urls, timeout=60, max_retries=0, revival_delay=300)

An object which manages connections to elasticsearch and acts as a go-between for API calls to it

Parameters:
  • timeout – Number of seconds to wait for each request before raising Timeout
  • max_retries – How many other servers to try, in series, after a request times out or a connection fails
  • revival_delay – Number of seconds for which to avoid a server after it times out or is uncontactable
index(index, doc_type, doc, id=None, force_insert=False[, other kwargs listed below])

Put a typed JSON document into a specific index to make it searchable.

Parameters:
  • index – The name of the index to which to add the document
  • doc_type – The type of the document
  • doc – A mapping, convertible to JSON, representing the document
  • id – The ID to give the document. Leave blank to make one up.
  • force_insert – If True and a document of the given ID already exists, fail rather than updating it.
  • routing – A value hashed to determine which shard this indexing request is routed to
  • parent – The ID of a parent document, which leads this document to be routed to the same shard as the parent, unless routing overrides it.
  • timestamp – An explicit value for the (typically automatic) timestamp associated with a document, for use with ttl and such
  • ttl – The time until this document is automatically removed from the index. Can be an integral number of milliseconds or a duration like ‘1d’.
  • percolate – An indication of which percolator queries, registered against this index, should be checked against the new document: ‘*’ or a query string like ‘color:green’
  • consistency – An indication of how many active shards the contact node should demand to see in order to let the index operation succeed: ‘one’, ‘quorum’, or ‘all’
  • replication – Set to ‘async’ to return from ES before finishing replication.
  • refresh – Pass True to refresh the index after adding the document.
  • timeout – A duration to wait for the relevant primary shard to become available, in the event that it isn’t: for example, “5m”

See ES’s index API for more detail.

bulk_index(index, doc_type, docs, id_field='id'[, other kwargs listed below])

Index a list of documents as efficiently as possible.

Parameters:
  • index – The name of the index to which to add the document
  • doc_type – The type of the document
  • docs – An iterable of mappings, convertible to JSON, representing documents to index
  • id_field – The field of each document that holds its ID
  • consistency – See the ES docs.
  • refresh – See the ES docs.

See ES’s bulk API for more detail.

delete(index, doc_type, id[, other kwargs listed below])

Delete a typed JSON document from a specific index based on its ID.

Parameters:
  • index – The name of the index from which to delete
  • doc_type – The type of the document to delete
  • id – The ID of the document to delete
  • routing – See the ES docs.
  • parent – See the ES docs.
  • replication – See the ES docs.
  • consistency – See the ES docs.
  • refresh – See the ES docs.

See ES’s delete API for more detail.

delete_all(index, doc_type[, other kwargs listed below])

Delete all documents of the given doctype from an index.

Parameters:
  • index – The name of the index from which to delete. ES does not support this being empty or “_all” or a comma-delimited list of index names (in 0.19.9).
  • doc_type – The name of a document type
  • routing – See the ES docs.
  • parent – See the ES docs.
  • replication – See the ES docs.
  • consistency – See the ES docs.
  • refresh – See the ES docs.

See ES’s delete API for more detail.

delete_by_query(index, doc_type, query[, other kwargs listed below])

Delete typed JSON documents from a specific index based on query.

Parameters:
  • index – The name of the index from which to delete
  • doc_type – The type of document to delete
  • query – A dict of query DSL selecting the documents to delete
  • q – See the ES docs.
  • df – See the ES docs.
  • analyzer – See the ES docs.
  • default_operator – See the ES docs.
  • sourcerouting – See the ES docs.
  • replication – See the ES docs.
  • consistency – See the ES docs.

See ES’s delete-by-query API for more detail.

get(index, doc_type, id[, other kwargs listed below])

Get a typed JSON document from an index by ID.

Parameters:
  • index – The name of the index from which to retrieve
  • doc_type – The type of document to get
  • id – The ID of the document to retrieve
  • realtime – See the ES docs.
  • fields – See the ES docs.
  • routing – See the ES docs.
  • preference – See the ES docs.
  • refresh – See the ES docs.

See ES’s get API for more detail.

search(query, index, doc_type[, other kwargs listed below])

Execute a search query against one or more indices and get back search hits.

Parameters:
  • query – A dictionary that will convert to ES’s query DSL or a string that will serve as a textual query to be passed as the q query string parameter
  • index – An index or iterable of indexes to search
  • doc_type – A document type or iterable thereof to search
  • routing – See the ES docs.

See ES’s search API for more detail.

count(query, index, doc_type[, other kwargs listed below])

Execute a query against one or more indices and get hit count.

Parameters:
  • query – A dictionary that will convert to ES’s query DSL or a string that will serve as a textual query to be passed as the q query string parameter
  • index – An index or iterable of indexes to search
  • doc_type – A document type or iterable thereof to search
  • df – See the ES docs.
  • analyzer – See the ES docs.
  • default_operator – See the ES docs.
  • source – See the ES docs.
  • routing – See the ES docs.

See ES’s count API for more detail.

get_mapping(index=None, doc_type=None)

Fetch the mapping definition for a specific index and type.

Parameters:
  • index – An index or iterable thereof
  • doc_type – A document type or iterable thereof

Omit both arguments to get mappings for all types and indexes.

See ES’s get-mapping API for more detail.

put_mapping(index, doc_type, mapping[, other kwargs listed below])

Register specific mapping definition for a specific type against one or more indices.

Parameters:
  • index – An index or iterable thereof
  • doc_type – The document type to set the mapping of
  • mapping – A dict representing the mapping to install. For example, this dict can have top-level keys that are the names of doc types.
  • ignore_conflicts – See the ES docs.

See ES’s put-mapping API for more detail.

more_like_this(index, doc_type, id, fields[, other kwargs listed below])

Execute a “more like this” search query against one or more fields and get back search hits.

Parameters:
  • index – The index to search and where the document for comparison lives
  • doc_type – The type of document to find others like
  • id – The ID of the document to find others like
  • fields – A list of fields to compare on
  • search_type – See the ES docs.
  • search_indices – See the ES docs.
  • search_types – See the ES docs.
  • search_scroll – See the ES docs.
  • search_size – See the ES docs.
  • search_from – See the ES docs.
  • like_text – See the ES docs.
  • percent_terms_to_match – See the ES docs.
  • min_term_freq – See the ES docs.
  • max_query_terms – See the ES docs.
  • stop_words – See the ES docs.
  • min_doc_freq – See the ES docs.
  • max_doc_freq – See the ES docs.
  • min_word_len – See the ES docs.
  • max_word_len – See the ES docs.
  • boost_terms – See the ES docs.
  • boost – See the ES docs.
  • analyzer – See the ES docs.

See ES’s more-like-this API for more detail.

status(index=None[, other kwargs listed below])

Retrieve the status of one or more indices

Parameters:
  • index – An index or iterable thereof
  • recovery – See the ES docs.
  • snapshot – See the ES docs.

See ES’s index-status API for more detail.

create_index(index, settings=None)

Create an index with optional settings.

Parameters:
  • index – The name of the index to create
  • settings – A dictionary of settings

See ES’s create-index API for more detail.

delete_index(index)

Delete an index.

Parameters:index – An index or iterable thereof to delete

See ES’s delete-index API for more detail.

delete_all_indexes()

Delete all indexes.

close_index(index)

Close an index.

Parameters:index – The index to close

See ES’s close-index API for more detail.

open_index(index)

Open an index.

Parameters:index – The index to open

See ES’s open-index API for more detail.

update_settings(index, settings)

Change the settings of one or more indexes.

Parameters:
  • index – An index or iterable of indexes
  • settings – A dictionary of settings

See ES’s update-settings API for more detail.

update_all_settings(settings)

Update the settings of all indexes.

Parameters:settings – A dictionary of settings

See ES’s update-settings API for more detail.

flush(index=None[, other kwargs listed below])

Flush one or more indices (clear memory).

Parameters:
  • index – An index or iterable of indexes
  • refresh – See the ES docs.

See ES’s flush API for more detail.

refresh(index=None)

Refresh one or more indices.

Parameters:index – An index or iterable of indexes

See ES’s refresh API for more detail.

gateway_snapshot(index=None)

Gateway snapshot one or more indices.

Parameters:index – An index or iterable of indexes

See ES’s gateway-snapshot API for more detail.

optimize(index=None[, other kwargs listed below])

Optimize one or more indices.

Parameters:
  • index – An index or iterable of indexes
  • max_num_segments – See the ES docs.
  • only_expunge_deletes – See the ES docs.
  • refresh – See the ES docs.
  • flush – See the ES docs.
  • wait_for_merge – See the ES docs.

See ES’s optimize API for more detail.

health(index=None[, other kwargs listed below])

Report on the health of the cluster or certain indices.

Parameters:
  • index – The index or iterable of indexes to examine
  • level – See the ES docs.
  • wait_for_status – See the ES docs.
  • wait_for_relocating_shards – See the ES docs.
  • wait_for_nodes – See the ES docs.
  • timeout – See the ES docs.

See ES’s cluster-health API for more detail.

Error Handling

Any method representing an ES API call can raise one of the following exceptions:

exception pyelasticsearch.exceptions.ConnectionError

Exception raised there is a connection error and we are out of retries. (See the max_retries argument to ElasticSearch.)

exception pyelasticsearch.exceptions.Timeout

Exception raised when an HTTP request times out and we are out of retries. (See the max_retries argument to ElasticSearch.)

exception pyelasticsearch.exceptions.ElasticHttpError[source]

Exception raised when ES returns a non-OK (>=400) HTTP status code

error[source]

A string error message

status_code[source]

The HTTP status code of the response that precipitated the error

exception pyelasticsearch.exceptions.ElasticHttpNotFoundError[source]

Exception raised when a request to ES returns a 404

exception pyelasticsearch.exceptions.InvalidJsonResponseError[source]

Exception raised in the unlikely event that ES returns a non-JSON response

Project Versions

Table Of Contents

Previous topic

Features

Next topic

Changelog

This Page