#elasticsearch #search

elastic

A modular sync and async client for the Elasticsearch REST API

33 releases

0.21.0-pre.2 Feb 23, 2019
0.20.10 May 7, 2018
0.20.9 Feb 6, 2018
0.20.8 Dec 17, 2017
0.10.0 Mar 20, 2017

#85 in Database interfaces

Download history 525/week @ 2018-11-10 230/week @ 2018-11-17 325/week @ 2018-11-24 405/week @ 2018-12-01 236/week @ 2018-12-08 145/week @ 2018-12-15 125/week @ 2018-12-22 44/week @ 2018-12-29 203/week @ 2019-01-05 162/week @ 2019-01-12 35/week @ 2019-01-19 159/week @ 2019-01-26 92/week @ 2019-02-02 103/week @ 2019-02-09 104/week @ 2019-02-16

713 downloads per month
Used in 1 crate

MIT/Apache

635KB
12K SLoC


lib.rs:

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 6.x

This crate depends heavily on the following crates:

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.2"
elastic_derive = "~0.21.0-pre.2"

The following optional dependencies may also be useful:

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

Then reference in your crate root:

# fn main() {}
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:

# extern crate elastic;
# use elastic::prelude::*;
# use std::str::FromStr;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
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()?;
# Ok(())
# }

Individual requests can override these parameter values:

# extern crate elastic;
# extern crate serde_json;
# use serde_json::Value;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
let client = SyncClientBuilder::new().build()?;

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

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:

# extern crate serde;
# #[macro_use] extern crate serde_derive;
# #[macro_use] extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
#[derive(Serialize, Deserialize, ElasticType)]
struct MyType {
#[elastic(id(expr = "ToString::to_string"))]
pub id: String,
pub title: String,
pub timestamp: Date<DefaultDateMapping>
}
# Ok(())
# }

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

# extern crate serde;
# #[macro_use] extern crate serde_derive;
# #[macro_use] extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType { }
# let client = SyncClientBuilder::new().build()?;
client.document::<MyType>()
.put_mapping()
.send()?;
# Ok(())
# }

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

# extern crate serde;
# #[macro_use] extern crate serde_derive;
# #[macro_use] extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType {
#     pub id: String,
#     pub title: String,
#     pub timestamp: Date<DefaultDateMapping>
# }
# let client = SyncClientBuilder::new().build()?;
let doc = MyType {
id: "1".to_owned(),
title: String::from("A title"),
timestamp: Date::now()
};

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

Call [Client.document_get][Client.document_get] to retrieve a single document from an index:

# extern crate serde;
# #[macro_use] extern crate serde_derive;
# #[macro_use] extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType {
#     pub id: String,
#     pub title: String,
#     pub timestamp: Date<DefaultDateMapping>
# }
# let client = SyncClientBuilder::new().build()?;
let response = client.document::<MyType>()
.get(1)
.send()?;

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

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

Searching documents

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

# extern crate serde;
# #[macro_use] extern crate serde_json;
# #[macro_use] extern crate serde_derive;
# #[macro_use] extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() { run().unwrap() }
# fn run() -> Result<(), Box<::std::error::Error>> {
# #[derive(Debug, Serialize, Deserialize, ElasticType)]
# struct MyType { }
# let client = SyncClientBuilder::new().build()?;
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);
}
# Ok(())
# }

Crate design

This crate is mostly a meta-package composed of a number of smaller pieces including:

  • elastic_requests API request builders
  • elastic_responses API response parsers
  • elastic_types tools for document and mapping APIs

This crate glues these libraries together with some simple assumptions about how they're going to be used.

Links

Dependencies

~18MB
~400K SLoC