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.
Usage
This crate is on crates.io.
To get stated, add elastic
to your Cargo.toml
:
[dependencies]
elastic = "*"
The following optional dependencies may also be useful:
elastic_derive = "*"
json_str = "*"
serde = "*"
serde_json = "*"
serde_derive = "*"
Then reference in your crate root:
extern crate elastic;
// Optional
extern crate serde;
extern crate serde_json;
#[macro_use]
extern crate serde_derive;
#[macro_use]
extern crate elastic_derive;
#[macro_use]
extern crate json_str;
# fn main() {}
Examples
Making requests
Each endpoint in the Elasticsearch REST API is provided as a strongly-typed
structure.
Use a Client
instance to send one of these requests and read the response:
use elastic::prelude::*;
// Create a client with default params (host: 'http://localhost:9200')
let client = Client::new(RequestParams::default()).unwrap();
// A ping request (HEAD '/')
let req = PingRequest::new();
// Send the ping request and unwrap the response
let response = client.request(req).send().unwrap();
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:
# use elastic::prelude::*;
let params = RequestParams::new("http://es_host:9200").url_param("pretty", true);
let client = Client::new(params).unwrap();
Individual requests can override these parameter values:
# use elastic::prelude::*;
# let params = RequestParams::new("http://es_host:9200");
# let client = Client::new(params).unwrap();
# let req = PingRequest::new();
let response = client.request(req)
.params(|p| p.url_param("pretty", false))
.send()
.unwrap();
For more details, see the client
and requests
modules.
Getting Responses
Call response
on a sent request to get a strongly typed SearchResponse
or GetResponse
:
# extern crate serde;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType {
# pub id: i32,
# pub title: String,
# pub timestamp: Date<DefaultDateFormat>
# }
# let params = RequestParams::new("http://es_host:9200");
# let client = Client::new(params).unwrap();
# let req = PingRequest::new();
let response = client.request(req)
.send()
.and_then(|res| res.response::<SearchResponse<MyType>>());
# }
Call raw
on a sent request to get a raw HttpResponse
:
# extern crate serde;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() {
# let params = RequestParams::new("http://es_host:9200");
# let client = Client::new(params).unwrap();
# let req = PingRequest::new();
let response = client.request(req)
.send()
.map(|res| res.raw());
# }
The HttpResponse
implements Read
so you can buffer out the raw
response data.
For more details see the client
and responses
module.
Defining document types
The Mapping API is provided as a custom derive plugin and 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() {
#[derive(Serialize, Deserialize, ElasticType)]
struct MyType {
pub id: i32,
pub title: String,
pub timestamp: Date<DefaultDateFormat>
}
# }
Use your document type to build index requests:
# extern crate serde;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType {
# pub id: i32,
# pub title: String,
# pub timestamp: Date<DefaultDateFormat>
# }
let doc = MyType {
id: 1,
title: String::from("A title"),
timestamp: Date::now()
};
let index = Index::from("index");
let id = Id::from(doc.id.to_string());
// A tuple of (Index, Id, MyType) can be converted into an IndexRequest
let req = IndexRequest::try_for_doc((index, id, &doc)).unwrap();
# }
Use your document type to build mapping requests:
# extern crate serde;
# #[macro_use]
# extern crate serde_derive;
# #[macro_use]
# extern crate elastic_derive;
# extern crate elastic;
# use elastic::prelude::*;
# fn main() {
# #[derive(Serialize, Deserialize, ElasticType)]
# struct MyType {
# pub id: i32,
# pub title: String,
# pub timestamp: Date<DefaultDateFormat>
# }
let index = Index::from("index");
let mapping = MyType::mapping();
// A tuple of (Index, MyTypeMapping) can be converted into a MappingRequest
let req = IndicesPutMappingRequest::try_for_mapping((index, mapping)).unwrap();
# }
For more details on document types, see the types
module.
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.