Skip to content

Commit 399ca4e

Browse files
szabosteveszabosteve
committed
[DOCS] Reorganizes Overview and Installation chapters.
1 parent 6efacfa commit 399ca4e

File tree

3 files changed

+129
-116
lines changed

3 files changed

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

0 commit comments

Comments
 (0)