Crate elastic

Elasticsearch API Client

A modular and efficient native client for the Elasticsearch REST API.

Supported Versions

elastic	Elasticsearch
0.0.x - 0.20.x	5.x
0.21.x	7.x

This crate depends heavily on the following crates:

• reqwest/hyper as the default HTTP layer
• serde/serde_json for serialisation
• futures/tokio for async io.

elastic is designed to scale up to the complexity of Elasticsearch's API, and with the complexity of the environments Elasticsearch is deployed in.

Usage

This crate is on crates.io. To get stated, add elastic to your Cargo.toml:

[dependencies]
elastic = "~0.21.0-pre.5"
elastic_derive = "~0.21.0-pre.5"

The following optional dependencies may also be useful:

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

Then reference in your crate root:

extern crate elastic;
#[macro_use]
extern crate elastic_derive;

Examples

Creating a synchronous client

The SyncClient type is an easy way to interact with an Elasticsearch cluster. A synchronous client can be created through the SyncClientBuilder.

The builder allows you to configure default parameters for all requests:

use elastic::http::header::{self, AUTHORIZATION, HeaderValue};

let auth = HeaderValue::from_str("let me in")?;

let builder = SyncClientBuilder::new()
    .static_node("http://es_host:9200")
    .params_fluent(move |p| p
        .url_param("pretty", true)
        .header(AUTHORIZATION, auth.clone()));

let client = builder.build()?;

Individual requests can override these parameter values:

let client = SyncClientBuilder::new().build()?;

let response = client.search::<Value>()
                     .params_fluent(|p| p.url_param("pretty", false))
                     .send()?;

elastic also offers an AsyncClient. For more details, see the client and requests modules.

Making requests

For a list of common client methods, see here.

Each endpoint in the Elasticsearch REST API is provided as a strongly-typed structure. The client offers high-level request builders for some common Elasticsearch operations.

Getting and Indexing documents

The Document Mapping API is provided as a custom derive plugin and set of Rust traits. Derive Serialize, Deserialize and ElasticType on your document types:

#[derive(Serialize, Deserialize, ElasticType)]
struct MyType {
    #[elastic(id(expr = "id.to_string()"))]
    pub id: i32,
    pub title: String,
    pub timestamp: Date<DefaultDateMapping>
}

Call Client.document().put_mapping() to ensure an index has the right mapping for your document types:

client.document::<MyType>()
      .put_mapping()
      .send()?;

Then call Client.document().index() to index documents in Elasticsearch:

let doc = MyType {
    id: "1".to_owned(),
    title: String::from("A title"),
    timestamp: Date::now()
};

let response = client.document()
                     .index(doc)
                     .send()?;

Call Client.document().get() to retrieve a single document from an index:

let response = client.document::<MyType>()
                     .get(1)
                     .send()?;

if let Some(doc) = response.into_document() {
    println!("id: {}", doc.id);
}

For more details on document types, see the types module.

Searching documents

Call Client.doument().search() to execute Query DSL queries:

let response = client.document::<MyType>()
                     .search()
                     .body(json!({
                         "query": {
                            "query_string": {
                                "query": "*"
                            }
                         }
                     }))
                     .send()?;

// Iterate through the hits (of type `MyType`)
for hit in response.hits() {
    println!("{:?}", hit);
}

Links

• Elasticsearch Docs
• Github

Re-exports

pub use self::error::Error;

Modules

client	HTTP client, requests and responses.
endpoints	REST API endpoints.
error	Client-side error types.
http	Raw HTTP modules.
params	Common url params like Id and Index.
prelude	A glob import for convenience.
types	Indexable documents and type mapping.

Type Definitions

AsyncClient	An asynchronous Elasticsearch client.
SyncClient	A synchronous Elasticsearch client.