|
9 | 9 |
|
10 | 10 | **IMPORTANT NOTICE: This is a fork of the original [elasticsearch-rs repository](https://github.com/quickwit-oss/elasticsearch-rs). The API generation part has been modified for generating Elastic compatible API endpoints and types within [Quickwit](https://github.com/orgs/quickwit-oss).** |
11 | 11 |
|
12 | | -Official Rust Client for [Elasticsearch](https://github.com/elastic/elasticsearch). |
13 | | - |
14 | | -Full documentation is available at https://docs.rs/elasticsearch |
15 | | - |
16 | | -The project is still very much a _work in progress_ and in an _alpha_ state; |
17 | | -input and contributions welcome! |
18 | | - |
19 | | -## Compatibility |
20 | | - |
21 | | -The Elasticsearch Rust client is forward compatible; meaning that the client supports communicating with greater minor versions of Elasticsearch. Elasticsearch language clients are also backwards compatible with lesser supported minor Elasticsearch versions. |
22 | | - |
23 | | -## Features |
24 | | - |
25 | | -The following are a list of Cargo features that can be enabled or disabled: |
26 | | - |
27 | | -- **native-tls** *(enabled by default)*: Enables TLS functionality provided by `native-tls`. |
28 | | -- **rustls-tls**: Enables TLS functionality provided by `rustls`. |
29 | | -- **beta-apis**: Enables beta APIs. Beta APIs are on track to become stable and permanent features. Use them with |
30 | | - caution because it is possible that breaking changes are made to these APIs in a minor version. |
31 | | -- **experimental-apis**: Enables experimental APIs. Experimental APIs are just that - an experiment. An experimental |
32 | | - API might have breaking changes in any future version, or it might even be removed entirely. This feature also |
33 | | - enables `beta-apis`. |
34 | | - |
35 | | -## Getting started |
36 | | - |
37 | | -The client exposes all Elasticsearch APIs as associated functions, either on |
38 | | -the root client, `Elasticsearch`, or on one of the _namespaced clients_, such as `Cat`, `Indices`, etc. The _namespaced clients_ |
39 | | -are based on the grouping of APIs within the [Elasticsearch](https://github.com/elastic/elasticsearch/tree/master/rest-api-spec) and [X-Pack](https://github.com/elastic/elasticsearch/tree/master/x-pack/plugin/src/test/resources/rest-api-spec/api) REST API specs from which much of the client is generated. |
40 | | -All API functions are `async` only, and can be `await`ed. |
41 | | - |
42 | | -### Installing |
43 | | - |
44 | | -Add `elasticsearch` crate and version to Cargo.toml. Choose the version |
45 | | -that is compatible with the version of Elasticsearch you're using |
46 | | - |
47 | | -```toml |
48 | | -[dependencies] |
49 | | -elasticsearch = "8.7.0-alpha.1" |
50 | | -``` |
51 | | - |
52 | | -The following _optional_ dependencies may also be useful to create requests and read responses |
53 | | - |
54 | | -```toml |
55 | | -serde = "~1" |
56 | | -serde_json = "~1" |
57 | | -``` |
58 | | - |
59 | | ----- |
60 | | - |
61 | | -#### Async support with tokio |
62 | | - |
63 | | -The client uses [`reqwest`](https://crates.io/crates/reqwest) to make HTTP calls, which internally uses |
64 | | -the [`tokio`](https://crates.io/crates/tokio) runtime for async support. As such, you may require to take a dependency on `tokio` |
65 | | -in order to use the client. For example, in Cargo.toml, you may need the following dependency, |
66 | | - |
67 | | -```toml |
68 | | -tokio = { version = "*", features = ["full"] } |
69 | | -``` |
70 | | - |
71 | | -and to attribute async main function with `#[tokio::main]` |
72 | | - |
73 | | -```rust,no_run |
74 | | -#[tokio::main] |
75 | | -async fn main() -> Result<(), Box<dyn std::error::Error>> { |
76 | | - // your code ... |
77 | | - Ok(()) |
78 | | -} |
79 | | -``` |
80 | | - |
81 | | -and attribute test functions with `#[tokio::test]` |
82 | | - |
83 | | -```rust,no_run |
84 | | -#[tokio::test] |
85 | | -async fn my_test() -> Result<(), Box<dyn std::error::Error>> { |
86 | | - // your code ... |
87 | | - Ok(()) |
88 | | -} |
89 | | -``` |
90 | | - |
91 | | ----- |
92 | | - |
93 | | -### Create a client |
94 | | - |
95 | | -Build a transport to make API requests to Elasticsearch using the `TransportBuilder`, |
96 | | -which allows setting of proxies, authentication schemes, certificate validation, and |
97 | | -other transport related settings. |
98 | | - |
99 | | -To create a client to make API calls to Elasticsearch running on `http://localhost:9200` |
100 | | - |
101 | | -```rust,no_run |
102 | | -use elasticsearch::Elasticsearch; |
103 | | -
|
104 | | -fn main() { |
105 | | - let client = Elasticsearch::default(); |
106 | | -} |
107 | | -``` |
108 | | -Alternatively, you can create a client to make API calls against Elasticsearch running on a specific url |
109 | | - |
110 | | -```rust,no_run |
111 | | -use elasticsearch::{ |
112 | | - Elasticsearch, Error, |
113 | | - http::transport::Transport |
114 | | -}; |
115 | | -
|
116 | | -fn main() -> Result<(), Error> { |
117 | | - let transport = Transport::single_node("https://example.com")?; |
118 | | - let client = Elasticsearch::new(transport); |
119 | | - Ok(()) |
120 | | -} |
121 | | -``` |
122 | | - |
123 | | - If you're running against an Elasticsearch deployment in [Elastic Cloud](https://www.elastic.co/cloud/), |
124 | | - a client can be created using a [Cloud ID](https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html) |
125 | | - and credentials retrieved from the Cloud web console |
126 | | - |
127 | | -```rust,no_run |
128 | | -use elasticsearch::{ |
129 | | - auth::Credentials, |
130 | | - Elasticsearch, Error, |
131 | | - http::transport::Transport, |
132 | | -}; |
133 | | -
|
134 | | -fn main() -> Result<(), Error> { |
135 | | - let cloud_id = "cluster_name:Y2xvdWQtZW5kcG9pbnQuZXhhbXBsZSQzZGFkZjgyM2YwNTM4ODQ5N2VhNjg0MjM2ZDkxOGExYQ=="; |
136 | | - // can use other types of Credentials too, like Bearer or ApiKey |
137 | | - let credentials = Credentials::Basic("<username>".into(), "<password>".into()); |
138 | | - let transport = Transport::cloud(cloud_id, credentials)?; |
139 | | - let client = Elasticsearch::new(transport); |
140 | | - Ok(()) |
141 | | -} |
142 | | -``` |
143 | | - |
144 | | - More control over how a `Transport` is built can be |
145 | | - achieved using `TransportBuilder` to build a transport, and |
146 | | - passing it to `Elasticsearch::new()` create a new instance of `Elasticsearch` |
147 | | - |
148 | | -```rust,no_run |
149 | | -use url::Url; |
150 | | -use elasticsearch::{ |
151 | | - Error, Elasticsearch, |
152 | | - http::transport::{TransportBuilder,SingleNodeConnectionPool}, |
153 | | -}; |
154 | | -
|
155 | | -fn main() -> Result<(), Error> { |
156 | | - let url = Url::parse("https://example.com")?; |
157 | | - let conn_pool = SingleNodeConnectionPool::new(url); |
158 | | - let transport = TransportBuilder::new(conn_pool).disable_proxy().build()?; |
159 | | - let client = Elasticsearch::new(transport); |
160 | | - Ok(()) |
161 | | -} |
162 | | -``` |
163 | | - |
164 | | -### Making API calls |
165 | | - |
166 | | -The following will execute a `POST` request to `/_search?allow_no_indices=true` with |
167 | | -a JSON body of `{"query":{"match_all":{}}}` |
168 | | - |
169 | | -```rust,no_run |
170 | | -use elasticsearch::{Elasticsearch, Error, SearchParts}; |
171 | | -use serde_json::{json, Value}; |
172 | | -
|
173 | | -#[tokio::main] |
174 | | -async fn main() -> Result<(), Box<dyn std::error::Error>> { |
175 | | - let client = Elasticsearch::default(); |
176 | | -
|
177 | | - // make a search API call |
178 | | - let search_response = client |
179 | | - .search(SearchParts::None) |
180 | | - .body(json!({ |
181 | | - "query": { |
182 | | - "match_all": {} |
183 | | - } |
184 | | - })) |
185 | | - .allow_no_indices(true) |
186 | | - .send() |
187 | | - .await?; |
188 | | -
|
189 | | - // get the HTTP response status code |
190 | | - let status_code = search_response.status_code(); |
191 | | -
|
192 | | - // read the response body. Consumes search_response |
193 | | - let response_body = search_response.json::<Value>().await?; |
194 | | -
|
195 | | - // read fields from the response body |
196 | | - let took = response_body["took"].as_i64().unwrap(); |
197 | | -
|
198 | | - Ok(()) |
199 | | -} |
200 | | -``` |
201 | | - |
202 | | -The client provides functions on each API builder struct |
203 | | -for all query string parameters available for that API. APIs with multiple |
204 | | -URI path variants, where some can contain parts parameters, are modelled as enums. |
205 | | - |
206 | | -`Elasticsearch` also has an async `send` function on the root that allows sending an |
207 | | -API call to an endpoint not represented as an API function, for example, experimental |
208 | | -and beta APIs |
209 | | - |
210 | | -```rust,no_run |
211 | | -use elasticsearch::{http::Method, Elasticsearch, Error, SearchParts}; |
212 | | -use http::HeaderMap; |
213 | | -use serde_json::Value; |
214 | | -
|
215 | | -#[tokio::main] |
216 | | -async fn main() -> Result<(), Box<dyn std::error::Error>> { |
217 | | - let client = Elasticsearch::default(); |
218 | | - let body = b"{\"query\":{\"match_all\":{}}}"; |
219 | | - let response = client |
220 | | - .send( |
221 | | - Method::Post, |
222 | | - SearchParts::Index(&["tweets"]).url().as_ref(), |
223 | | - HeaderMap::new(), |
224 | | - Option::<&Value>::None, |
225 | | - Some(body.as_ref()), |
226 | | - None, |
227 | | - ) |
228 | | - .await?; |
229 | | - Ok(()) |
230 | | -} |
231 | | -``` |
232 | | - |
233 | 12 | ## License |
234 | 13 |
|
235 | 14 | This is free software, licensed under [The Apache License Version 2.0.](LICENSE.txt). |
0 commit comments