diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 9a06688f..f4cc819d 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,118 +1,6 @@ -= elasticsearch += Elasticsearch Rust Client -An official Rust client for Elasticsearch. +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -== Overview - -Full documentation is hosted at https://docs.rs/elasticsearch[docs.rs] --- this page provides _only_ an overview. - -=== Elasticsearch Version Compatibility - -|=== -| Rust client | Elasticsearch -| 7.x | 7.x -|=== - -A major version of the client is compatible with the same major version of Elasticsearch. -Since Elasticsearch is developed following https://semver.org/[Semantic Versioning] principles, -Any minor/patch version of the client can be used against any minor/patch version of Elasticsearch -**within the same major version lineage**. For example, - -- A `7.5.0` client can be used against `7.0.0` Elasticsearch -- A `7.5.0` client can be used against `7.6.0` Elasticsearch - -In the former case, a 7.5.0 client may contain additional API functions that are not available -in 7.0.0 Elasticsearch. In this case, these APIs cannot be used, but for any APIs available in -Elasticsearch, the respective API functions on the client will be compatible. - -In the latter case, a 7.5.0 client won't contain API functions for APIs that are introduced in -Elasticsearch 7.6.0+, but for all other APIs available in Elasticsearch, the respective API -functions on the client will be compatible. - -**No compatibility assurances are given between different major versions of the client and -Elasticsearch**. Major differences likely exist between major versions of Elasticsearch, particularly -around request and response object formats, but also around API urls and behaviour. - -=== Installing - -Add `elasticsearch` crate and version to Cargo.toml. Choose the version -that is compatible with the version of Elasticsearch you're using - -[source,toml] ----- -[dependencies] -elasticsearch = "8.0.0-alpha.1" ----- - -The following _optional_ dependencies may also be useful to create requests and read responses - -[source,toml] ----- -serde = "~1" -serde_json = "~1" ----- - -=== Create a client - -To create a client to make API calls to Elasticsearch running on `\http://localhost:9200` - -[source,rust] ----- -let client = Elasticsearch::default(); ----- - -Alternatively, you can create a client to make API calls against Elasticsearch running on a -specific `url::Url` - -[source,rust] ----- -let transport = Transport::single_node("https://example.com")?; -let client = Elasticsearch::new(transport); ----- - -If you're running against an Elasticsearch deployment in https://www.elastic.co/cloud/[Elastic Cloud], -a client can be created using a https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html[Cloud ID] -and credentials retrieved from the Cloud web console - -[source,rust] ----- -let cloud_id = ""; -let credentials = Credentials::Basic("".into(), "".into()); -let transport = Transport::cloud(cloud_id, credentials)?; -let client = Elasticsearch::new(transport); ----- - -=== Making API calls - -The following makes an API call to `tweets/_search` with the json body -`{"query":{"match":{"message":"Elasticsearch"}}}` - -[source,rust] ----- -let response = client - .search(SearchParts::Index(&["tweets"])) - .from(0) - .size(10) - .body(json!({ - "query": { - "match": { - "message": "Elasticsearch rust" - } - } - })) - .send() - .await?; - -let response_body = response.json::().await?; -let took = response_body["took"].as_i64().unwrap(); -for hit in response_body["hits"]["hits"].as_array().unwrap() { - // print the source document - println!("{:?}", hit["_source"]); -} ----- - -== Resources - -* https://github.com/elastic/elasticsearch-rs[Source code] -* https://docs.rs/elasticsearch[API documentation] \ No newline at end of file +include::overview.asciidoc[] +include::installation.asciidoc[] \ No newline at end of file diff --git a/docs/installation.asciidoc b/docs/installation.asciidoc new file mode 100644 index 00000000..3ed8cdff --- /dev/null +++ b/docs/installation.asciidoc @@ -0,0 +1,20 @@ +[[installation]] +== Installation + +Add `elasticsearch` crate and version to Cargo.toml. Choose the version that is +compatible with the version of {es} you are using: + +[source,toml] +---- +[dependencies] +elasticsearch = "8.0.0-alpha.1" +---- + +The following _optional_ dependencies may also be useful to create requests and +read responses: + +[source,toml] +---- +serde = "~1" +serde_json = "~1" +---- diff --git a/docs/overview.asciidoc b/docs/overview.asciidoc new file mode 100644 index 00000000..8078f08e --- /dev/null +++ b/docs/overview.asciidoc @@ -0,0 +1,116 @@ +[[overview]] +== Overview + +This is the official Rust client for {es}. Full documentation is hosted on +https://docs.rs/elasticsearch[docs.rs] -- this page provides _only_ an overview. + +Further resources: + +* https://github.com/elastic/elasticsearch-rs[Source code] +* https://docs.rs/elasticsearch[API documentation] + + +[discrete] +[[features]] +=== Features + +* Fluent builders for all {es} REST API endpoints +* Persistent keep-alive connections +* TLS support with system or custom certificates +* Proxy support with authentication +* Async support with Tokio + + +[discrete] +=== {es} Version Compatibility + +|=== +| Rust client | Elasticsearch +| 7.x | 7.x +|=== + +A major version of the client is compatible with the same major version of {es}. +Since {es} is developed following https://semver.org/[Semantic Versioning] +principles, any minor/patch version of the client can be used against any +minor/patch version of {es} **within the same major version lineage**. For +example, + +- A `7.5.0` client can be used against `7.0.0` Elasticsearch +- A `7.5.0` client can be used against `7.6.0` Elasticsearch + +In the former case, a 7.5.0 client may contain additional API functions that are +not available in 7.0.0 {es}. In this case, these APIs cannot be used, but for +any APIs available in {es}, the respective API functions on the client will be +compatible. + +In the latter case, a 7.5.0 client won't contain API functions for APIs that are +introduced in {es} 7.6.0+, but for all other APIs available in {es}, the +respective API functions on the client will be compatible. + +**No compatibility assurances are given between different major versions of the +client and {es}.** Major differences likely exist between major versions of +{es}, particularly around request and response object formats, but also around +API urls and behaviour. + + +[discrete] +=== Create a client + +To create a client to make API calls to Elasticsearch running on `\http://localhost:9200` + +[source,rust] +---- +let client = Elasticsearch::default(); +---- + +Alternatively, you can create a client to make API calls against Elasticsearch running on a +specific `url::Url` + +[source,rust] +---- +let transport = Transport::single_node("https://example.com")?; +let client = Elasticsearch::new(transport); +---- + +If you're running against an Elasticsearch deployment in https://www.elastic.co/cloud/[Elastic Cloud], +a client can be created using a https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html[Cloud ID] +and credentials retrieved from the Cloud web console + +[source,rust] +---- +let cloud_id = ""; +let credentials = Credentials::Basic("".into(), "".into()); +let transport = Transport::cloud(cloud_id, credentials)?; +let client = Elasticsearch::new(transport); +---- + + +[discrete] +=== Making API calls + +The following makes an API call to `tweets/_search` with the json body +`{"query":{"match":{"message":"Elasticsearch"}}}` + +[source,rust] +---- +let response = client + .search(SearchParts::Index(&["tweets"])) + .from(0) + .size(10) + .body(json!({ + "query": { + "match": { + "message": "Elasticsearch rust" + } + } + })) + .send() + .await?; + +let response_body = response.json::().await?; +let took = response_body["took"].as_i64().unwrap(); +for hit in response_body["hits"]["hits"].as_array().unwrap() { + // print the source document + println!("{:?}", hit["_source"]); +} +---- \ No newline at end of file