Elasticsearch Python Cheat Sheet

1Install & connectthe client

pip install elasticsearch★
The official client. Add extras: elasticsearch[async] for the async client. Python 3.10+.
from elasticsearch import Elasticsearch es = Elasticsearch("https://localhost:9200", api_key="...")★
API key auth is preferred. Also basic_auth=("user","pass"), or cloud_id= for Elastic Cloud.
es = Elasticsearch("https://localhost:9200", api_key="...", ca_certs="http_ca.crt")
TLS on by default for local clusters — point at the CA cert (or verify_certs=False for dev only).
es.info() · es.ping()★
Sanity check the connection & cluster version.

2Index & CRUD docsdocuments

es.index(index="books", id=1, document={"title":"Dune", "year":1965})★
Create/replace a doc. Pass the JSON as document=. Omit id to auto-generate one.
es.get(index="books", id=1)["_source"]★
Fetch by id; the doc body is under _source. es.exists(index=, id=) for a boolean.
es.update(index="books", id=1, doc={"year":1966})★
Partial update via doc= (or a script). es.delete(index=, id=) to remove.
es.indices.refresh(index="books")note
Indexing is near-real-time (~1s). refresh=True on the write, or refresh the index, to make a doc searchable immediately (tests/demos).

3Bulk & helpersload at volume

from elasticsearch import helpers actions = [{"_index":"books", "_id":d["id"], "_source":d} for d in docs] helpers.bulk(es, actions)★
The right way to load many docs — one request per batch, not one per doc. Each action names _index/_id/_source.
for ok, item in helpers.streaming_bulk(es, gen(), chunk_size=1000): if not ok: log(item)★
streaming_bulk yields per-doc results from a generator — constant memory for huge loads. parallel_bulk for threads.
actions = [{"_op_type":"update", "_id":1, "doc":{...}}, ...]
_op_type can be index/create/update/delete per action.
# bulk returns (success_count, errors) — check errors!gotcha
A partial-failure bulk still "succeeds" at the HTTP level. Inspect the errors list (or pass raise_on_error=True).

4Search basicsquery=

r = es.search(index="books", query={"match":{"title":"dune"}})★v9
Pass the query under query= (NOT body=). Add size=, from_=, sort=, source= as kwargs.
r["hits"]["total"]["value"] # match count [h["_source"] for h in r["hits"]["hits"]]★
Results are under hits.hits; each has _source, _id, and _score.
es.search(index="books", query={...}, size=20, from_=40, sort=[{"year":"desc"}], source=["title"])
Page with size+from_ (note the trailing underscore — from is a Python keyword). source= selects fields.
es.count(index="books", query={...})
Just the count, no documents.

5Query typesthe DSL

{"match":{"title":"dune messiah"}} # analyzed full-text★
match = full-text (tokenized/analyzed). term = exact, un-analyzed (use on keyword fields, not text).
{"bool":{ "must":[{"match":{"title":"dune"}}], "filter":[{"range":{"year":{"gte":1960}}}], "must_not":[...], "should":[...]}}★
bool composes queries: must (scored AND), filter (unscored AND, cacheable), should (OR/boost), must_not (NOT). Put exact filters in filter for speed.
{"multi_match":{"query":"dune", "fields":["title","body"]}}
Search several fields at once. Also match_phrase, wildcard, prefix, terms (list), exists, match_all.
es.search(index="books", knn={"field":"vec", "query_vector":v, "k":10})
kNN vector search is a top-level knn= kwarg — the basis of semantic/hybrid search.

6Aggregationsanalytics

r = es.search(index="books", size=0, aggs={ "by_year":{"terms":{"field":"year", "size":10}}})★
Set size=0 to get only aggregations (no hits). Read them from r["aggregations"].
r["aggregations"]["by_year"]["buckets"]★
Bucket aggs (terms, date_histogram, range) return buckets with key + doc_count.
aggs={"avg_year":{"avg":{"field":"year"}}}
Metric aggs: avg, sum, min, max, stats, cardinality (unique count), percentiles.
# nest aggs: put an "aggs" inside a bucket agg for sub-aggregations
Aggregations nest arbitrarily — e.g. average price per category.

7Mappings & settingsindex schema

es.indices.create(index="books", mappings={"properties":{ "title":{"type":"text"}, "year":{"type":"integer"}, "tags":{"type":"keyword"}}}, settings={"number_of_shards":1})★v9
Pass mappings= & settings= as kwargs (not body=). Define types explicitly for control over search behavior.
es.indices.put_mapping(index="books", properties={"isbn":{"type":"keyword"}})
Add fields later (you can't change an existing field's type — reindex for that).
es.indices.exists(index="books") · es.indices.delete(index="books")
Index lifecycle. es.indices.get_mapping, put_settings, refresh, forcemerge.
es.indices.put_alias(index="books_v2", name="books")
Aliases point a stable name at a physical index — enables zero-downtime reindexing.

8text vs keywordthe #1 mapping choice

# text -> analyzed (tokenized) -> full-text match # keyword -> exact string -> term / sort / aggregate★
The core distinction. Use text for searchable prose, keyword for IDs/tags/enums you filter, sort, or aggregate on.
# term query on a `text` field returns nothing / wrong resultsgotcha
A text field is lowercased & tokenized, so an exact term rarely matches. Use match on text, term on keyword.
{"type":"text", "fields":{"raw":{"type":"keyword"}}}★
A multi-field: index the same value as both text (search via title) and keyword (sort/aggregate via title.raw). Very common.
es.indices.analyze(index="books", text="Dune Messiah", analyzer="standard")
Debug tokenization — see exactly how an analyzer breaks text into terms.

9elasticsearch.dslfluent queries

from elasticsearch.dsl import Search, Q★integrated
The former standalone elasticsearch-dsl is now built into the client as elasticsearch.dsl — a Pythonic query builder.
s = (Search(using=es, index="books") .query("match", title="dune") .filter("range", year={"gte":1960}) .sort("-year")[:20]) for hit in s.execute(): print(hit.title)★
Chainable & lazy — nothing runs until .execute() or iteration. Hits are attribute-access objects.
Q("match", title="dune") & Q("match", author="herbert")
Q objects combine with & / | / ~ into bool queries — readable boolean logic.
class Book(Document): title = Text(); year = Integer() class Index: name = "books"
Document gives an ODM: model classes with typed fields, .save(), and .search().

11Scroll, paging & vectorslarge result sets

for doc in helpers.scan(es, index="books", query={"query":{"match_all":{}}}): process(doc["_source"])★
helpers.scan streams every matching doc (uses point-in-time/scroll under the hood) — the way to export a whole index.
# from_ + size can't page past index.max_result_window (10000)gotcha
Deep pagination fails past 10k. Use search_after (with a sort + PIT) or helpers.scan for large exports.
es.open_point_in_time(index="books", keep_alive="1m")
Point-in-time + search_after is the modern, consistent deep-pagination pattern.
es.reindex(source={"index":"books"}, dest={"index":"books_v2"})
Server-side reindex to change mappings/analyzers — then flip the alias.

12Migration & ecosystemwhat changed

# es.search(body={"query":...}) -> es.search(query=...)removed
The big migration: the catch-all body= parameter was deprecated in 8.x and removed in 9.x. Lift each top-level key (query, aggs, mappings, settings, size…) into its own kwarg.
# version-match the client to the cluster (9.x client -> 9.x server)★
Elastic ships one client major per stack major (elasticsearch7/8/9 pin-packages exist). Mismatched majors can break.
# related: Kibana (UI), Logstash/Beats (ingest), OpenSearch (fork)
The wider stack. OpenSearch is the AWS fork with its own opensearch-py client (similar API).
es.sql.query(query="SELECT title FROM books WHERE year > 1960")
Elasticsearch SQL for those who prefer SQL over the DSL. ES|QL is the newer piped query language.

Elasticsearch Python cheat sheet

Outline

Connect & index

Search

Mappings & admin

DSL & async

Ops & ecosystem

Connect & Index

Search

Mappings & Index Admin

DSL & Async

Ops & Ecosystem

Worth memorizing