Skip to content

Commit fa26686

Browse files
russcamrusscam
committed
Add index.asciidoc for Elastic site docs page
This commit adds an index.asciidoc page to include the Rust client in the documentation on elastic.co. Tidy up README to better align content with getting started on docs.rs
1 parent 518d9a4 commit fa26686

File tree

3 files changed

+240
-69
lines changed

3 files changed

+240
-69
lines changed

‎README.md

Lines changed: 102 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,35 @@
1-
# elasticsearch-rs
1+
# elasticsearch
22

3-
Repository for the official Elasticsearch Rust Client, `elasticsearch`.
3+
An official Rust Client for Elasticsearch.
44

55
The project is still very much a _work in progress_ and in an _alpha_ state;
66
input and contributions welcome!
77

88
## Versions and Compatibility
99

10-
<table>
11-
<tr>
12-
<th><b>Rust client<b></th>
13-
<th><b>Elasticsearch<b></th>
14-
<th><b>Status</b></th>
15-
</tr>
16-
<tr>
17-
<td><code>7.x</code></td>
18-
<td><code>7.x</code></td>
19-
<td><code>alpha</code></td>
20-
</tr>
21-
</table>
22-
23-
The Rust client is largely generated from the REST API specs of Elasticsearch.
24-
As such, the API functions available align with the version of the specs from which
25-
they're generated. Elasticsearch strives to adhere to [Semantic Versioning](https://semver.org/),
26-
which is reflected in the specs and thus this client.
27-
28-
What this means in practice is that a 7.x Rust client is compatible with Elasticsearch 7.x. Where
29-
the client minor version is greater than Elasticsearch minor version, it may contain API functions
30-
for APIs that are not available in the version of Elasticsearch, but all other API functions will
31-
be compatible. Where the client minor version is less than Elasticsearch minor version, all API
32-
functions will be compatible.
10+
| Rust client | Elasticsearch | Status |
11+
|-------------|---------------|--------|
12+
| 7.x | 7.x | alpha |
13+
14+
A major version of the client is compatible with the same major version of Elasticsearch.
15+
Since Elasticsearch is developed following [Semantic Versioning](https://semver.org/) principles,
16+
Any minor/patch version of the client can be used against any minor/patch version of Elasticsearch
17+
**within the same major version lineage**. For example,
18+
19+
- A `7.5.0` client can be used against `7.0.0` Elasticsearch
20+
- A `7.4.0` client can be used against `7.5.1` Elasticsearch
21+
22+
In the former case, a 7.5.0 client may contain additional API functions that are not available
23+
in 7.0.0 Elasticsearch. In this case, these APIs cannot be used, but for any APIs available in
24+
Elasticsearch, the respective API functions on the client will be compatible.
25+
26+
In the latter case, a 7.4.0 client won't contain API functions for APIs that are introduced in
27+
Elasticsearch 7.5.0+, but for all other APIs available in Elasticsearch, the respective API
28+
functions on the client will be compatible.
29+
30+
**No compatibility assurances are given between different major versions of the client and
31+
Elasticsearch**. Major differences likely exist between major versions of Elasticsearch, particularly
32+
around request and response object formats, but also around API urls and behaviour.
3333

3434
## Overview
3535

@@ -68,33 +68,85 @@ that is compatible with the version of Elasticsearch you're using
6868
elasticsearch = "7.5.1-alpha1"
6969
```
7070

71-
#### Connecting
71+
The following _optional_ dependencies may also be useful to create requests and read responses
72+
73+
```toml
74+
serde = "~1"
75+
serde_json = "~1"
76+
```
77+
78+
#### Create a client
7279

7380
Build a transport to make API requests to Elasticsearch using the `TransportBuilder`,
7481
which allows setting of proxies and authentication schemes
7582

83+
To create a client to make API calls to Elasticsearch running on `http://localhost:9200`
84+
85+
```rust,no_run
86+
use elasticsearch::{Error, Elasticsearch};
87+
88+
fn run() {
89+
let client = Elasticsearch::default();
90+
}
91+
```
92+
Alternatively, you can create a client to make API calls against Elasticsearch running on a specific url
93+
7694
```rust,no_run
7795
use elasticsearch::{
78-
Elasticsearch, Error,
79-
auth::Credentials,
80-
http::transport::{TransportBuilder, SingleNodeConnectionPool}
96+
Error, Elasticsearch,
97+
http::transport::{Transport, SingleNodeConnectionPool}
98+
};
99+
100+
fn run() -> Result<(), Error> {
101+
let transport = Transport::single_node("https://example.com")?;
102+
let client = Elasticsearch::new(transport);
103+
Ok(())
104+
}
105+
```
106+
107+
If you're running against an Elasticsearch deployment in [Elastic Cloud](https://www.elastic.co/cloud/),
108+
a client can be created using a [Cloud ID](https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html)
109+
and credentials retrieved from the Cloud web console
110+
111+
```rust,no_run
112+
use elasticsearch::{
113+
auth::Credentials,
114+
Error, Elasticsearch,
115+
http::transport::Transport,
81116
};
82117
use url::Url;
83118
84-
async fn run() -> Result<(), Error> {
119+
fn run() -> Result<(), Error> {
120+
let cloud_id = "cluster_name:Y2xvdWQtZW5kcG9pbnQuZXhhbXBsZSQzZGFkZjgyM2YwNTM4ODQ5N2VhNjg0MjM2ZDkxOGExYQ==";
121+
let credentials = Credentials::Basic("<username>".into(), "<password>".into());
122+
let transport = Transport::cloud(cloud_id, credentials)?;
123+
let client = Elasticsearch::new(transport);
124+
Ok(())
125+
}
126+
```
85127

86-
let conn_pool = SingleNodeConnectionPool::new(Url::parse("https://example.com").unwrap());
87-
let transport = TransportBuilder::new(conn_pool)
88-
.auth(Credentials::Basic("<username>".into(), "<password>".into()))
89-
.disable_proxy()
90-
.build()?;
91-
128+
More control over how a [Transport](http::transport::Transport) is built can be
129+
achieved using [TransportBuilder](http::transport::TransportBuilder) to build a transport, and
130+
passing it to [Elasticsearch::new] create a new instance of [Elasticsearch]
131+
132+
```rust,no_run
133+
use elasticsearch::{
134+
auth::Credentials,
135+
Error, Elasticsearch,
136+
http::transport::{TransportBuilder,SingleNodeConnectionPool},
137+
};
138+
use url::Url;
139+
140+
fn run() -> Result<(), Error> {
141+
let url = Url::parse("https://example.com")?;
142+
let conn_pool = SingleNodeConnectionPool::new(url);
143+
let transport = TransportBuilder::new(conn_pool).disable_proxy().build()?;
92144
let client = Elasticsearch::new(transport);
93145
Ok(())
94146
}
95147
```
96148

97-
#### Calling an API endpoint
149+
#### Making API calls
98150

99151
The following will execute a `POST` request to `/_search?allow_no_indices=true` with
100152
a JSON body of `{"query":{"match_all":{}}}`
@@ -157,12 +209,16 @@ The `quote` and `syn` crates help
157209
- Start simple and iterate
158210
- Design of the API is conducive to ease of use
159211
- Asynchronous only
160-
- Control API invariants through arguments on API function
212+
- Control API invariants through arguments on API function. For example
213+
214+
```norun
215+
client.delete_script(DeleteScriptParts::Id("script_id"))
216+
.send()
217+
.await?;
218+
```
161219
162-
e.g. `client.delete_script("script_id".into()).send()?;`
163-
164-
An id must always be provided for a script, so the `delete_script()` function must accept
165-
it as a value.
220+
An id must always be provided for a delete script API call, so the `delete_script()` function
221+
must accept it as a value.
166222
167223
## Contributing
168224
@@ -176,12 +232,12 @@ to address it, please assign the issue to yourself, so that others know that it
176232
177233
### Sign the Contributor License Agreement
178234
179-
We do ask that you sign the [Contiributor License Agreement](https://www.elastic.co/contributor-agreement) before we can accept pull requests from you.
235+
We do ask that you sign the [Contiributor License Agreement](https://www.elastic.co/contributor-agreement)
236+
before we can accept pull requests from you.
180237
181238
### Current Setup
182239
183-
Using Rust nightly for development, whilst reqwest crate, the HTTP client used, has support for `async`
184-
in an alpha release and has a dependency which uses features that only work on nightly:
240+
Use Rust nightly for development for now:
185241
186242
```sh
187243
> rustup show
@@ -194,7 +250,7 @@ nightly-x86_64-pc-windows-msvc (default)
194250
rustc 1.41.0-nightly (a44774c3a 2019-11-25)
195251
```
196252

197-
It is expected to move to stable once dependencies compile on stable.
253+
It is expected to move to rust stable once dependencies compile on stable.
198254

199255
### Coding styleguide
200256

‎docs/index.asciidoc

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
= elasticsearch
2+
3+
An official Rust client for Elasticsearch.
4+
5+
== Overview
6+
7+
Full documentation is hosted at https://docs.rs/elasticsearch[docs.rs]
8+
-- this page provides _only_ an overview.
9+
10+
=== Elasticsearch Version Compatibility
11+
12+
|===
13+
| Rust client | Elasticsearch
14+
| 7.x | 7.x
15+
|===
16+
17+
A major version of the client is compatible with the same major version of Elasticsearch.
18+
Since Elasticsearch is developed following https://semver.org/[Semantic Versioning] principles,
19+
Any minor/patch version of the client can be used against any minor/patch version of Elasticsearch
20+
**within the same major version lineage**. For example,
21+
22+
- A `7.5.0` client can be used against `7.0.0` Elasticsearch
23+
- A `7.4.0` client can be used against `7.5.1` Elasticsearch
24+
25+
In the former case, a 7.5.0 client may contain additional API functions that are not available
26+
in 7.0.0 Elasticsearch. In this case, these APIs cannot be used, but for any APIs available in
27+
Elasticsearch, the respective API functions on the client will be compatible.
28+
29+
In the latter case, a 7.4.0 client won't contain API functions for APIs that are introduced in
30+
Elasticsearch 7.5.0+, but for all other APIs available in Elasticsearch, the respective API
31+
functions on the client will be compatible.
32+
33+
**No compatibility assurances are given between different major versions of the client and
34+
Elasticsearch**. Major differences likely exist between major versions of Elasticsearch, particularly
35+
around request and response object formats, but also around API urls and behaviour.
36+
37+
=== Installing
38+
39+
Add `elasticsearch` crate and version to Cargo.toml. Choose the version
40+
that is compatible with the version of Elasticsearch you're using
41+
42+
[source,toml]
43+
----
44+
[dependencies]
45+
elasticsearch = "7.5.1-alpha1"
46+
----
47+
48+
The following _optional_ dependencies may also be useful to create requests and read responses
49+
50+
[source,toml]
51+
----
52+
serde = "~1"
53+
serde_json = "~1"
54+
----
55+
56+
=== Create a client
57+
58+
To create a client to make API calls to Elasticsearch running on `\http://localhost:9200`
59+
60+
[source,rust]
61+
----
62+
let client = Elasticsearch::default();
63+
----
64+
65+
Alternatively, you can create a client to make API calls against Elasticsearch running on a
66+
specific `url::Url`
67+
68+
[source,rust]
69+
----
70+
let transport = Transport::single_node("https://example.com")?;
71+
let client = Elasticsearch::new(transport);
72+
----
73+
74+
If you're running against an Elasticsearch deployment in https://www.elastic.co/cloud/[Elastic Cloud],
75+
a client can be created using a https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html[Cloud ID]
76+
and credentials retrieved from the Cloud web console
77+
78+
[source,rust]
79+
----
80+
let cloud_id = "<cloud id from cloud web console>";
81+
let credentials = Credentials::Basic("<username>".into(), "<password>".into());
82+
let transport = Transport::cloud(cloud_id, credentials)?;
83+
let client = Elasticsearch::new(transport);
84+
----
85+
86+
=== Making API calls
87+
88+
The following makes an API call to `tweets/_search` with the json body
89+
`{"query":{"match":{"message":"Elasticsearch"}}}`
90+
91+
[source,rust]
92+
----
93+
let response = client
94+
.search(SearchParts::Index(&["tweets"]))
95+
.from(0)
96+
.size(10)
97+
.body(json!({
98+
"query": {
99+
"match": {
100+
"message": "Elasticsearch rust"
101+
}
102+
}
103+
}))
104+
.send()
105+
.await?;
106+
107+
let response_body = response.read_body::<Value>().await?;
108+
let took = response_body["took"].as_i64().unwrap();
109+
for hit in response_body["hits"]["hits"].as_array().unwrap() {
110+
// print the source document
111+
println!("{:?}", hit["_source"]);
112+
}
113+
----
114+
115+
== Resources
116+
117+
* https://github.com/elastic/elasticsearch-rs[Source code]
118+
* https://docs.rs/elasticsearch[API documentation]

0 commit comments

Comments
 (0)