Crate elastic [−] [src]
Elasticsearch API Client
A modular and efficient native client for the Elasticsearch REST API.
Supported Versions
elastic |
Elasticsearch |
---|---|
0.x |
5.x |
The client provides a flexible API with a default happy-path so you can customise the way you use it. It depends heavily on the following crates:
reqwest
/hyper
as the default HTTP layerserde
/serde_json
for serialisation.
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 = "*" elastic_derive = "*"
The following optional dependencies may also be useful:
json_str = "*" serde = "*" serde_json = "*" serde_derive = "*"
Then reference in your crate root:
extern crate elastic; #[macro_use] extern crate elastic_derive;
Examples
Creating a client
The Client
type is used to make interact with an Elasticsearch cluster.
The Client
will use a default set of request parameters that are passed to each request.
Properties like the host and query parameters can be configured for all requests:
use elastic::prelude::*; use elastic::http::header::Authorization; let builder = ClientBuilder::new() .base_url("http://es_host:9200") .params(|p| p .url_param("pretty", true) .header(Authorization("let me in".to_owned()))); let client = builder.build().unwrap();
Individual requests can override these parameter values:
let client = ClientBuilder::new().build().unwrap(); let response = client.search::<Value>() .params(|p| p.url_param("pretty", true)) .send() .unwrap();
For more details, see the client
and requests
modules.
Making requests
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 { pub id: i32, pub title: String, pub timestamp: Date<DefaultDateFormat> }
Call Client.put_mapping
to ensure an index has the right mapping for your document types:
client.put_mapping::<MyType>(index("myindex")) .send() .unwrap();
Then call Client.index_document
to index documents in Elasticsearch:
let doc = MyType { id: 1, title: String::from("A title"), timestamp: Date::now() }; let response = client.index_document(index("myindex"), id(doc.id), doc) .send() .unwrap();
Call Client.get_document
to retrieve a single document from an index:
let response = client.get_document::<MyType>(index("myindex"), id(1)) .send() .unwrap(); if let Some(doc) = response.source { println!("id: {}", doc.id); }
For more details on document types, see the types
module.
Searching documents
Call Client.search
to execute Query DSL queries:
let response = client.search::<MyType>() .index("myindex") .body(json_str!({ query: { query_string: { query: "*" } } })) .send() .unwrap(); // Iterate through the hits (of type `MyType`) for hit in response.hits() { println!("{:?}", hit); }
Crate design
This crate is mostly a meta-package composed of a number of smaller pieces including:
elastic_reqwest
HTTP transportelastic_requests
API request builderselastic_responses
API response parserselastic_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
Modules
client |
HTTP client, requests and responses. |
error |
Client-side error types. |
http |
Raw HTTP modules. |
prelude |
A glob import for convenience. |
types |
Indexable documents and type mapping. |