Skip to content

Commit d1af56d

Browse files
szabosteveszabosteve
authored
Merge pull request #150 from szabosteve/drs.overview
[DOCS] Reorganizes Overview and Installation chapters
2 parents 51fd5da + 6171b1c commit d1af56d

File tree

3 files changed

+140
-116
lines changed

3 files changed

+140
-116
lines changed

‎docs/index.asciidoc

Lines changed: 4 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,6 @@
1-
= elasticsearch
1+
= Elasticsearch Rust Client
22

3-
An official Rust client for Elasticsearch.
3+
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
44

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.5.0` client can be used against `7.6.0` 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.5.0 client won't contain API functions for APIs that are introduced in
30-
Elasticsearch 7.6.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 = "8.0.0-alpha.1"
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.json::<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]
5+
include::overview.asciidoc[]
6+
include::installation.asciidoc[]

‎docs/installation.asciidoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[[installation]]
2+
== Installation
3+
4+
Add `elasticsearch` crate and version to Cargo.toml. Choose the version that is
5+
compatible with the version of {es} you are using:
6+
7+
[source,toml]
8+
----
9+
[dependencies]
10+
elasticsearch = "8.0.0-alpha.1"
11+
----
12+
13+
The following _optional_ dependencies may also be useful to create requests and
14+
read responses:
15+
16+
[source,toml]
17+
----
18+
serde = "~1"
19+
serde_json = "~1"
20+
----

‎docs/overview.asciidoc

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

0 commit comments

Comments
 (0)