[−][src]Crate elasticsearch

Official Rust client for Elasticsearch

Elasticsearch is an official Rust client for Elasticsearch, providing an efficient asynchronous client for all stable Elasticsearch APIs that's easy to use.

Versions and Compatibility

Rust clientElasticsearch
7.x7.x

A major version of the client is compatible with the same major version of Elasticsearch. Since Elasticsearch is developed following Semantic Versioning principles, Any minor/patch version of the client can be used against any minor/patch version of Elasticsearch within the same major version lineage. For example,

  • A 7.5.0 client can be used against 7.0.0 Elasticsearch
  • A 7.4.0 client can be used against 7.5.1 Elasticsearch

In the former case, a 7.5.0 client may contain additional API functions that are not available in 7.0.0 Elasticsearch. In this case, these APIs cannot be used, but for any APIs available in Elasticsearch, the respective API functions on the client will be compatible.

In the latter case, a 7.4.0 client won't contain API functions for APIs that are introduced in Elasticsearch 7.5.0+, but for all other APIs available in Elasticsearch, the respective API functions on the client will be compatible.

No compatibility assurances are given between different major versions of the client and Elasticsearch. Major differences likely exist between major versions of Elasticsearch, particularly around request and response object formats, but also around API urls and behaviour.

Getting started

Add the elasticsearch crate and version to Cargo.toml. Choose the version that is compatible with the version of Elasticsearch you're using

[dependencies]
elasticsearch = "7.5.2-alpha.1"

The following optional dependencies may also be useful to create requests and read responses

serde = "~1"
serde_json = "~1"

Create a client

To create a client to make API calls to Elasticsearch running on http://localhost:9200

let client = Elasticsearch::default();

Alternatively, you can create a client to make API calls against Elasticsearch running on a specific url::Url

let transport = Transport::single_node("https://example.com")?;
let client = Elasticsearch::new(transport);

If you're running against an Elasticsearch deployment in Elastic Cloud, a client can be created using a Cloud ID and credentials retrieved from the Cloud web console

let cloud_id = "cluster_name:Y2xvdWQtZW5kcG9pbnQuZXhhbXBsZSQzZGFkZjgyM2YwNTM4ODQ5N2VhNjg0MjM2ZDkxOGExYQ==";
let credentials = Credentials::Basic("<username>".into(), "<password>".into());
let transport = Transport::cloud(cloud_id, credentials)?;
let client = Elasticsearch::new(transport);

More control over how a Transport is built can be achieved using TransportBuilder to build a transport, and passing it to Elasticsearch::new create a new instance of Elasticsearch

let url = Url::parse("https://example.com")?;
let conn_pool = SingleNodeConnectionPool::new(url);
let transport = TransportBuilder::new(conn_pool).disable_proxy().build()?;
let client = Elasticsearch::new(transport);

Making API calls

The client exposes all stable Elasticsearch APIs, either on the root Elasticsearch client, or on a namespace client that groups related APIs, such as Cat, which groups the Cat related APIs. All API functions are async and can be awaited.

The following makes an API call to the cat indices API

let response = client
    .cat()
    .indices(CatIndicesParts::Index(&["*"]))
    .send()
    .await?;

let response_body = response.read_body::<Value>().await?;
for record in response_body.as_array().unwrap() {
    // print the name of each index
    println!("{}", record["index"].as_str().unwrap());
}

For APIs that contain parts of the Url path to be provided by the consumer, the Url path variants are modelled as an enum, such as CatIndicesParts in the above example, which models the variants of the CatIndices API.

Indexing

Indexing a single document can be achieved with the index API

let response = client
    .index(IndexParts::IndexId("tweets", "1"))
    .body(json!({
        "id": 1,
        "user": "kimchy",
        "post_date": "2009-11-15T00:00:00Z",
        "message": "Trying out Elasticsearch, so far so good?"
    }))
    .send()
    .await?;

let successful = response.status_code().is_success();

For indexing multiple documents, the bulk API is a better option, allowing multiple operations to be sent in one API call

let mut body: Vec<JsonBody<_>> = Vec::with_capacity(4);

// add the first operation and document
body.push(json!({"index": {"_id": "1"}}).into());
body.push(json!({
    "id": 1,
    "user": "kimchy",
    "post_date": "2009-11-15T00:00:00Z",
    "message": "Trying out Elasticsearch, so far so good?"
}).into());

// add the second operation and document
body.push(json!({"index": {"_id": "2"}}).into());
body.push(json!({
    "id": 2,
    "user": "forloop",
    "post_date": "2020-01-08T00:00:00Z",
    "message": "Bulk indexing with the rust client, yeah!"
}).into());

let response = client
    .bulk(BulkParts::Index("tweets"))
    .body(body)
    .send()
    .await?;

let response_body = response.read_body::<Value>().await?;
let successful = response_body["errors"].as_bool().unwrap() == false;

Searching

The following makes an API call to tweets/_search with the json body {"query":{"match":{"message":"Elasticsearch"}}}

let response = client
    .search(SearchParts::Index(&["tweets"]))
    .from(0)
    .size(10)
    .body(json!({
        "query": {
            "match": {
                "message": "Elasticsearch rust"
            }
        }
    }))
    .send()
    .await?;

let response_body = response.read_body::<Value>().await?;
let took = response_body["took"].as_i64().unwrap();
for hit in response_body["hits"]["hits"].as_array().unwrap() {
    // print the source document
    println!("{:?}", hit["_source"]);
}

Request bodies

For APIs that expect JSON, the body associated function of the API constrains the input to a type that implements serde::Serialize trait. An example of this was the indexing a single document example above.

Some APIs expect newline delimited JSON (NDJSON) however, so the body associated for these APIs constrain the input to a vector of types that implement Body trait. An example of this was the bulk indexing multiple documents above.

The Body trait represents the body of an API call, allowing for different body implementations. As well as those to represent JSON and NDJSON, a few other types also have implementations for Body, such as byte slice. Whilst these can't be passed to the API functions directly, Elasticsearch::send can be used

let body = b"{\"query\":{\"match_all\":{}}}";

let response = client
    .send(Method::Post,
        SearchParts::Index(&["tweets"]).url().as_ref(),
        HeaderMap::new(),
        Option::<&Value>::None,
        Some(body.as_ref())
    )
    .await?;

Re-exports

pub use crate::http::transport::DEFAULT_ADDRESS;

Modules

auth

Authentication components

cat

Cat APIs

ccr

Cross-cluster Replication APIs

cluster

Cluster APIs

enrich

Enrich APIs

graph

Graph APIs

http

HTTP transport and related components

ilm

Index Lifecycle Management APIs

indices

Index APIs

ingest

Ingest APIs

license

Licensing APIs

migration

Migration APIs

ml

Machine Learning APIs

nodes

Node APIs

params

API parameters

security

Security APIs

slm

Snapshot Lifecycle Management APIs

snapshot

Snapshot APIs

sql

SQL APIs

ssl

SSL APIs

tasks

Task Management APIs

watcher

Watcher (Alerting) APIs

xpack

X-Pack APIs

Structs

Bulk

Builder for the Bulk API. Allows to perform multiple index/update/delete operations in a single request.

ClearScroll

Builder for the Clear Scroll API. Explicitly clears the search context for a scroll.

Count

Builder for the Count API. Returns number of documents matching a query.

Create

Builder for the Create API. Creates a new document in the index.

Delete

Builder for the Delete API. Removes a document from the index.

DeleteByQuery

Builder for the Delete By Query API. Deletes documents matching the provided query.

DeleteByQueryRethrottle

Builder for the Delete By Query Rethrottle API. Changes the number of requests per second for a particular Delete By Query operation.

DeleteScript

Builder for the Delete Script API. Deletes a script.

Elasticsearch

Root client for top level APIs

Error

An error within the client.

Exists

Builder for the Exists API. Returns information about whether a document exists in an index.

ExistsSource

Builder for the Exists Source API. Returns information about whether a document source exists in an index.

Explain

Builder for the Explain API. Returns information about why a specific matches (or doesn't match) a query.

FieldCaps

Builder for the Field Caps API. Returns the information about the capabilities of fields among multiple indices.

Get

Builder for the Get API. Returns a document.

GetScript

Builder for the Get Script API. Returns a script.

GetSource

Builder for the Get Source API. Returns the source of a document.

Index

Builder for the Index API. Creates or updates a document in an index.

Info

Builder for the Info API. Returns basic information about the cluster.

Mget

Builder for the Mget API. Allows to get multiple documents in one request.

Msearch

Builder for the Msearch API. Allows to execute several search operations in one request.

MsearchTemplate

Builder for the Msearch Template API. Allows to execute several search template operations in one request.

Mtermvectors

Builder for the Mtermvectors API. Returns multiple termvectors in one request.

Ping

Builder for the Ping API. Returns whether the cluster is running.

PutScript

Builder for the Put Script API. Creates or updates a script.

Reindex

Builder for the Reindex API. Allows to copy documents from one index to another, optionally filtering the source documents by a query, changing the destination index settings, or fetching the documents from a remote cluster.

ReindexRethrottle

Builder for the Reindex Rethrottle API. Changes the number of requests per second for a particular Reindex operation.

RenderSearchTemplate

Builder for the Render Search Template API. Allows to use the Mustache language to pre-render a search definition.

Scroll

Builder for the Scroll API. Allows to retrieve a large numbers of results from a single search request.

Search

Builder for the Search API. Returns results matching a query.

SearchShards

Builder for the Search Shards API. Returns information about the indices and shards that a search request would be executed against.

SearchTemplate

Builder for the Search Template API. Allows to use the Mustache language to pre-render a search definition.

Termvectors

Builder for the Termvectors API. Returns information and statistics about terms in the fields of a particular document.

Update

Builder for the Update API. Updates a document with a script or partial document.

UpdateByQuery

Builder for the Update By Query API. Performs an update on every document in the index without changing the source, for example to pick up a mapping change.

UpdateByQueryRethrottle

Builder for the Update By Query Rethrottle API. Changes the number of requests per second for a particular Update By Query operation.

Enums

BulkParts

API parts for the Bulk API

ClearScrollParts

API parts for the Clear Scroll API

CountParts

API parts for the Count API

CreateParts

API parts for the Create API

DeleteByQueryParts

API parts for the Delete By Query API

DeleteByQueryRethrottleParts

API parts for the Delete By Query Rethrottle API

DeleteParts

API parts for the Delete API

DeleteScriptParts

API parts for the Delete Script API

ExistsParts

API parts for the Exists API

ExistsSourceParts

API parts for the Exists Source API

ExplainParts

API parts for the Explain API

FieldCapsParts

API parts for the Field Caps API

GetParts

API parts for the Get API

GetScriptParts

API parts for the Get Script API

GetSourceParts

API parts for the Get Source API

IndexParts

API parts for the Index API

InfoParts

API parts for the Info API

MgetParts

API parts for the Mget API

MsearchParts

API parts for the Msearch API

MsearchTemplateParts

API parts for the Msearch Template API

MtermvectorsParts

API parts for the Mtermvectors API

PingParts

API parts for the Ping API

PutScriptParts

API parts for the Put Script API

ReindexParts

API parts for the Reindex API

ReindexRethrottleParts

API parts for the Reindex Rethrottle API

RenderSearchTemplateParts

API parts for the Render Search Template API

ScrollParts

API parts for the Scroll API

SearchParts

API parts for the Search API

SearchShardsParts

API parts for the Search Shards API

SearchTemplateParts

API parts for the Search Template API

TermvectorsParts

API parts for the Termvectors API

UpdateByQueryParts

API parts for the Update By Query API

UpdateByQueryRethrottleParts

API parts for the Update By Query Rethrottle API

UpdateParts

API parts for the Update API

Functions

serialize_coll_qs

Serializes an Option<&[&str]> with Some(value) to a comma separated string of values. Used to serialize values within the query string