elasticsearch 
Official Rust Client for Elasticsearch.
Full documentation is available at https://docs.rs/elasticsearch
The project is still very much a work in progress and in an alpha state; input and contributions welcome!
Versions and Compatibility
| Rust client | Elasticsearch | Status |
|---|---|---|
| 7.x | 7.x | alpha |
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.0client can be used against7.0.0Elasticsearch - A
7.5.0client can be used against7.6.0Elasticsearch
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.5.0 client won't contain API functions for APIs that are introduced in Elasticsearch 7.6.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.
Features
The following are a list of Cargo features that can be enabled or disabled:
- native-tls (enabled by default): Enables TLS functionality provided by
native-tls. - rustls-tls: Enables TLS functionality provided by
rustls. - beta-apis: Enables beta APIs. Beta APIs are on track to become stable and permanent features. Use them with caution because it is possible that breaking changes are made to these APIs in a minor version.
- experimental-apis: Enables experimental APIs. Experimental APIs are just that - an experiment. An experimental API might have breaking changes in any future version, or it might even be removed entirely. This feature also enables
beta-apis.
Getting started
The client exposes all Elasticsearch APIs as associated functions, either on the root client, Elasticsearch, or on one of the namespaced clients, such as Cat, Indices, etc. The namespaced clients are based on the grouping of APIs within the Elasticsearch and X-Pack REST API specs from which much of the client is generated. All API functions are async only, and can be awaited.
Installing
Add elasticsearch crate and version to Cargo.toml. Choose the version that is compatible with the version of Elasticsearch you're using
[dependencies]
elasticsearch = "8.0.0-alpha.1"
The following optional dependencies may also be useful to create requests and read responses
serde = "~1"
serde_json = "~1"
Async support with tokio
The client uses reqwest to make HTTP calls, which internally uses the tokio runtime for async support. As such, you may require to take a dependency on tokio in order to use the client. For example, in Cargo.toml, you may need the following dependency,
tokio = { version = "*", features = ["full"] }
and to attribute async main function with #[tokio::main]
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// your code ...
Ok(())
}
and attribute test functions with #[tokio::test]
#[tokio::test]
async fn my_test() -> Result<(), Box<dyn std::error::Error>> {
// your code ...
Ok(())
}
Create a client
Build a transport to make API requests to Elasticsearch using the TransportBuilder, which allows setting of proxies, authentication schemes, certificate validation, and other transport related settings.
To create a client to make API calls to Elasticsearch running on http://localhost:9200
use elasticsearch::Elasticsearch;
fn main() {
let client = Elasticsearch::default();
}
Alternatively, you can create a client to make API calls against Elasticsearch running on a specific url
use elasticsearch::{
Elasticsearch, Error,
http::transport::Transport
};
fn main() -> Result<(), Error> {
let transport = Transport::single_node("https://example.com")?;
let client = Elasticsearch::new(transport);
Ok(())
}
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
use elasticsearch::{
auth::Credentials,
Elasticsearch, Error,
http::transport::Transport,
};
fn main() -> Result<(), Error> {
let cloud_id = "cluster_name:Y2xvdWQtZW5kcG9pbnQuZXhhbXBsZSQzZGFkZjgyM2YwNTM4ODQ5N2VhNjg0MjM2ZDkxOGExYQ==";
// can use other types of Credentials too, like Bearer or ApiKey
let credentials = Credentials::Basic("<username>".into(), "<password>".into());
let transport = Transport::cloud(cloud_id, credentials)?;
let client = Elasticsearch::new(transport);
Ok(())
}
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
use url::Url;
use elasticsearch::{
Error, Elasticsearch,
http::transport::{TransportBuilder,SingleNodeConnectionPool},
};
fn main() -> Result<(), Error> {
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);
Ok(())
}
Making API calls
The following will execute a POST request to /_search?allow_no_indices=true with a JSON body of {"query":{"match_all":{}}}
use elasticsearch::{Elasticsearch, Error, SearchParts};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Elasticsearch::default();
// make a search API call
let search_response = client
.search(SearchParts::None)
.body(json!({
"query": {
"match_all": {}
}
}))
.allow_no_indices(true)
.send()
.await?;
// get the HTTP response status code
let status_code = search_response.status_code();
// read the response body. Consumes search_response
let response_body = search_response.json::<Value>().await?;
// read fields from the response body
let took = response_body["took"].as_i64().unwrap();
Ok(())
}
The client provides functions on each API builder struct for all query string parameters available for that API. APIs with multiple URI path variants, where some can contain parts parameters, are modelled as enums.
Elasticsearch also has an async send function on the root that allows sending an API call to an endpoint not represented as an API function, for example, experimental and beta APIs
use elasticsearch::{http::Method, Elasticsearch, Error, SearchParts};
use http::HeaderMap;
use serde_json::Value;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Elasticsearch::default();
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()),
None,
)
.await?;
Ok(())
}
License
This is free software, licensed under The Apache License Version 2.0..
![[Enhancement] better error handling](https://avatars.githubusercontent.com/u/33961674?v=4)
![[BUG] Failure in certificate validation](https://avatars.githubusercontent.com/u/4140019?v=4)
![[ENHANCEMENT] Migration to tokio 1.0](https://avatars.githubusercontent.com/u/1268573?v=4)
![[BUG] CA chains are not supported with native-tls](https://avatars.githubusercontent.com/u/2347189?v=4)
![[BUG] error decoding response body: missing field `<field>` at line x column y](https://avatars.githubusercontent.com/u/46896178?v=4)
![[ENHANCEMENT] Add pass through features for reqwest](https://avatars.githubusercontent.com/u/2526129?v=4)
![[ENHANCEMENT] High level query builder](https://avatars.githubusercontent.com/u/17054766?v=4)
17.4k Jan 2, 2023
4 Aug 26, 2023
3 Mar 20, 2024
7.4k Dec 28, 2022
1.8k Dec 26, 2022
69 Jan 2, 2023
3.8k Jan 7, 2023
140 Dec 16, 2022
0 Dec 31, 2021
342 Dec 26, 2022
294 Dec 23, 2022
155 Dec 31, 2022
0 Jan 10, 2022
62 Dec 10, 2022
914 Dec 24, 2022
5 Mar 9, 2022
8 Jan 3, 2022
65 Jan 4, 2023
7.4k Dec 30, 2022