elastic

elastic_* is an ecosystem of community crates for interacting with Elasticsearch from Rust. The API is targetting Elastic 5.x.

Crate functionality covers:

• http client
• type mapping

Quick reference:

• crates
• samples

NOTE: This client is under active churn right now while the pieces are tied together. The documentation will improve shortly.

Build Status

Platform	Channel	Status
Linux / OSX	Nightly
Windows	Nightly

Documentation

Version	Docs
master
current

Goals

To provide a strongly-typed, full-featured and efficient Elasticsearch client for Rust over (eventually) asynchronous io. Rust gives us a lot of tools for building super-performant but highly accessible libraries, which we aim to continue.

The REST API is provided by an inline JSON macro so it's efficient and always in line with whatever version of Elasticsearch you're targeting. This means you don't need to learn another API for interacting with Elasticsearch; queries mocked in Sense can just be copy+pasted into your Rust code.

The core focus of this project is on strong typing over your document types and query responses in Elasticsearch, rather than trying to map the entire Query DSL.

Support for Elastic's plugin products, like watcher and graph could be added as feature-gated modules in the elastic_hyper and elastic_rotor clients and elastic_types as necessary.

Alternatives

If you'd like to use a strongly-typed Query DSL builder see rs-es. This client does the hard work of providing an idiomatic Rust API for interacting with Elasticsearch. It has the advantage of letting you know your queries will parse at compile-time instead of runtime.

Example

See the examples folder.

Add elastic and json_str to your Cargo.toml:

[dependencies]
elastic = "*"

# Optional for request bodies
json_str = "*"

And reference in your crate root:

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

use elastic::prelude::*;

Get a client instance:

let client = Client::new(RequestParams::default()).unwrap();

Create a search request:

let body = json_str!({
    query: {
        query_string: {
            query: "*"
        }
    }
});

let req = SearchRequest::for_index("_all", body);

Send the request and iterate through the returned hits:

let res: Response = client
    .request(req)
    .send()
    .and_then(|res| res.json())
    .unwrap();

for hit in res.hits() {
    println!("{:?}", hit);
}

Development

Development is active, but because functionality is split across crates it can be hard to track where the effort is going. There is a GitHub Project to easily track priorities at the crate-level.

The elastic crate brings these independent units together into a cohesive API. It aims to provide the glue between them and offer some typical defaults. If you have a more specialised use-case, you can pick and choose the crates that will best support it.

elastic sits on a stack with hard dependencies on the following libraries:

• reqwest/hyper for HTTP
• serde for serialisation

There hasn't been much effort put into abstracting these dependencies at this stage.

Crates

elastic bundles up a couple of crates into a single client. If you want to pick and choose functionality, you can work with these crates independently.

elastic_reqwest

A synchronous reqwest implementation of the Elasticsearch REST API.

elastic_requests

Zero-copy request types for the REST API endpoints. These are automatically generated from the official spec.

elastic_responses

Idiomatic support for inspecting Elasticsearch responses and iterating over hits.

elastic_types

A library for building Elasticsearch types in Rust. Define your Elasticsearch types as PORS (Plain Old Rust Structures) and generate an equivalent Elasticsearch mapping from them, where correctness is enforced by Rust's type system.

elastic_rotor

An experimental REST API client that handles a single specific usecase: high throughput.