|
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