Elasticsearch Client Libraries

Raw HTTP requests work for learning and quick tests. Production applications benefit from official client libraries instead. A client builds requests, handles connection pools, retries failed calls, and converts responses into objects the language understands. Developers write less plumbing code and focus on the application.

  Your application code
          │
          ▼
  [ Elasticsearch client library ]
     • builds the HTTP request
     • manages connections
     • retries on failure
     • parses the JSON response
          │
          ▼
  Elasticsearch cluster

Official Clients

Language	Package
Python	elasticsearch
JavaScript and Node.js	@elastic/elasticsearch
Java	elasticsearch-java
.NET	Elastic.Clients.Elasticsearch
Go	go-elasticsearch
PHP	elasticsearch-php
Ruby	elasticsearch-ruby

Match the major version of the client to the major version of the cluster. A version 8 client talks to a version 8 server. Mismatches can cause errors that are hard to trace.

Python: Connecting

Install the package with pip, and create a client object with the cluster address and credentials. API keys offer a safer option than a shared password, since each key carries limited permissions and can be revoked alone.

pip install elasticsearch

from elasticsearch import Elasticsearch

es = Elasticsearch(
    "https://localhost:9200",
    api_key="YOUR_API_KEY",
    ca_certs="/path/to/http_ca.crt"
)

print(es.info()["version"]["number"])

Read the key from an environment variable or a secrets manager. Hard-coded keys leak through source control.

Python: Index, Get, Search

# Add a document
es.index(
    index="products",
    id="1",
    document={"name": "Steel Bottle", "price": 18.5, "stock": 120}
)

# Fetch it by ID
doc = es.get(index="products", id="1")
print(doc["_source"]["name"])

# Search
result = es.search(
    index="products",
    query={"match": {"name": "bottle"}}
)

for hit in result["hits"]["hits"]:
    print(hit["_score"], hit["_source"]["name"])

Each method mirrors a REST endpoint. The names stay close to the API documentation, so knowledge from earlier topics transfers directly.

Python: Bulk Loading with Helpers

The helpers module turns a list of Python dictionaries into efficient bulk requests and handles batching.

from elasticsearch import helpers

actions = [
    {"_index": "products", "_id": i, "_source": {"name": f"Item {i}", "price": i * 2.5}}
    for i in range(1, 1001)
]

success, errors = helpers.bulk(es, actions, raise_on_error=False)
print(success, "documents indexed")

JavaScript with Node.js

The Node client uses promises, so await keeps the code readable.

npm install @elastic/elasticsearch

const { Client } = require('@elastic/elasticsearch');

const client = new Client({
  node: 'https://localhost:9200',
  auth: { apiKey: process.env.ES_API_KEY },
  tls: { ca: require('fs').readFileSync('./http_ca.crt') }
});

async function run() {
  await client.index({
    index: 'products',
    id: '2',
    document: { name: 'Canvas Backpack', price: 42 }
  });

  const result = await client.search({
    index: 'products',
    query: { match: { name: 'backpack' } }
  });

  console.log(result.hits.hits);
}

run();

Good Habits for Production Code

Habit	Reason
Create one client and reuse it	Connection pooling needs a long-lived object
Set request timeouts	Slow calls never freeze the application
Enable retries for temporary errors	Short network drops heal themselves
Catch exceptions by type	Not-found and conflict errors deserve different responses
Use API keys with minimal rights	Limits damage if a key leaks
Use bulk helpers for imports	Single calls waste time

from elasticsearch import NotFoundError

try:
    es.get(index="products", id="999")
except NotFoundError:
    print("Document does not exist")

Handling Multiple Nodes

Pass several node addresses, and the client spreads requests across them. A failed node drops out of rotation until it recovers.

es = Elasticsearch(
    ["https://node1:9200", "https://node2:9200", "https://node3:9200"],
    api_key="YOUR_API_KEY",
    ca_certs="/path/to/http_ca.crt",
    max_retries=3,
    retry_on_timeout=True,
    request_timeout=15
)

Cloud deployments offer a cloud ID instead of a node list. The client decodes it into the correct address, which keeps configuration short.

Choosing an Authentication Method

Clients support several ways to prove identity. Pick the lightest option that meets the security needs of the project.

Method	How It Works	Best For
Username and password	Basic credentials sent over HTTPS	Local learning, quick tests
API key	Generated token with limited rights	Applications and services
Service token	Token tied to a service account	Internal system components
Cloud ID with API key	Short code that decodes to the cluster address	Managed cloud deployments

Typical Application Structure

A web application rarely lets the browser talk to Elasticsearch directly. A backend service receives the visitor's request, validates it, builds the query through the client, and returns a trimmed answer. This design hides credentials and blocks risky queries.

  Browser  ──→  Backend API  ──→  Client library  ──→  Elasticsearch
  (search       (validates       (retries,              (runs the
   box)          input)           pooling)               query)
                    │
                    └── returns only the fields the page needs

Keep query construction in one module of the codebase. A single place to change field names, boosts, and filters saves hours when the search design evolves.

Upgrading Clients Safely

Client libraries evolve with each Elasticsearch release. Read the migration notes before raising a version number, since method names and response shapes occasionally change. Pin the client version in the project's dependency file so a routine install never swaps it silently. Run the application's search tests against a staging cluster after every upgrade, and compare a few key queries before and after to confirm identical results.

Previous lesson

Back to course

Next lesson