Skip to content

Commit 0e554b8

Browse files
picandocodigopicandocodigo
committed
[DOCS] Updates READMEs
1 parent 256ace1 commit 0e554b8

File tree

2 files changed

+90
-44
lines changed

2 files changed

+90
-44
lines changed

‎README.md

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -54,22 +54,19 @@ The Elasticsearch client is compatible with currently maintained Ruby versions.
5454

5555
The gem's version numbers follow Elasticsearch's major versions. The `master` branch is compatible with the Elasticsearch `master` branch, which is the next major version.
5656

57-
| Gem Version | | Elasticsearch |
58-
|:-------------:|:-:| :-----------: |
59-
| 0.90 | → | 0.90 |
60-
| 1.x | → | 1.x |
61-
| 2.x | → | 2.x |
62-
| 5.x | → | 5.x |
63-
| 6.x | → | 6.x |
64-
| 7.x | → | 7.x |
65-
| master | → | master |
66-
67-
Use a release that matches the major version of Elasticsearch in your stack. Each client version is
68-
backwards compatible with all minor versions of the same major version. The client's API is
69-
compatible with Elasticsearch's API versions from 0.90 till current.
70-
71-
Check out [Elastic product end of life dates](https://www.elastic.co/support/eol)
72-
to learn which releases are still actively supported and tested.
57+
| Client version | Elasticsearch version | Supported | Tests |
58+
| :-------------: | :-------------------: | :-: | :---: |
59+
| 0.90 | 0.90 | :x: | |
60+
| 1.x | 1.x | :x: | |
61+
| 2.x | 2.x | :x: | |
62+
| 5.x | 5.x | :x: | |
63+
| 6.x | 6.x | :white_check_mark: | [![6.x](https://github.com/elastic/elasticsearch-ruby/actions/workflows/6.x.yml/badge.svg?branch=6.x)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/6.x.yml)|
64+
| 7.x | 7.x | :white_check_mark: | [![7.x](https://github.com/elastic/elasticsearch-ruby/actions/workflows/7.x.yml/badge.svg?branch=7.x)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/7.x.yml) |
65+
| master | master | :x: | [![master](https://github.com/elastic/elasticsearch-ruby/actions/workflows/master.yml/badge.svg?branch=master)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/master.yml) |
66+
67+
Use a release that matches the major version of Elasticsearch in your stack. Each client version is backwards compatible with all minor versions of the same major version. The client's API is compatible with Elasticsearch's API versions from 0.90 till current.
68+
69+
Check out [Elastic product end of life dates](https://www.elastic.co/support/eol) to learn which releases are still actively supported and tested.
7370

7471
## Installation
7572

‎elasticsearch/README.md

Lines changed: 77 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,29 @@
22

33
The `elasticsearch` library provides a Ruby client and API for [Elasticsearch](http://elasticsearch.com).
44

5+
## Usage
6+
7+
This gem is a wrapper for two separate libraries:
8+
9+
* [`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport), which provides a low-level Ruby client for connecting to [Elastic](http://elasticsearch.com) services.
10+
* [`elasticsearch-api`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-api), which provides a Ruby API for the Elasticsearch RESTful API.
11+
12+
Install the `elasticsearch` package and use the API directly:
13+
14+
```ruby
15+
require 'elasticsearch'
16+
17+
client = Elasticsearch::Client.new(log: true)
18+
19+
client.cluster.health
20+
21+
client.transport.reload_connections!
22+
23+
client.search(q: 'test')
24+
25+
# etc.
26+
```
27+
528
Features overview:
629

730
* Pluggable logging and tracing
@@ -14,25 +37,23 @@ Features overview:
1437
* Extensive documentation and examples
1538
* Emphasis on modularity and extendability of both the client and API libraries
1639

17-
(For integration with Ruby models and Rails applications,
18-
see the <https://github.com/elasticsearch/elasticsearch-rails> project.)
40+
(For integration with Ruby models and Rails applications, see the <https://github.com/elasticsearch/elasticsearch-rails> project.)
1941

2042
## Compatibility
2143

22-
The Elasticsearch client for Ruby is compatible with Ruby 1.9 and higher.
44+
The Elasticsearch client is compatible with currently maintained Ruby versions. See [Ruby Maintenance Branches](https://www.ruby-lang.org/en/downloads/branches/). We don't provide support to versions which have reached their end of life.
2345

24-
The client's API is compatible with Elasticsearch's API versions from 0.90 till current,
25-
just use a release matching major version of Elasticsearch.
46+
The client's API is compatible with Elasticsearch's API versions from 0.90 till current, just use a release matching major version of Elasticsearch.
2647

27-
| Ruby | | Elasticsearch |
28-
|:-------------:|:-:| :-----------: |
29-
| 0.90 | → | 0.90 |
30-
| 1.x | → | 1.x |
31-
| 2.x | → | 2.x |
32-
| 5.x | → | 5.x |
33-
| 6.x | → | 6.x |
34-
| 7.x | → | 7.x |
35-
| master | → | master |
48+
| Client version | Elasticsearch version | Supported | Tests |
49+
| :-------------: | :-------------------: | :-------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
50+
| 0.90 | 0.90 | :x: | |
51+
| 1.x | 1.x | :x: | |
52+
| 2.x | 2.x | :x: | |
53+
| 5.x | 5.x | :x: | |
54+
| 6.x | 6.x | :white_check_mark: | [![6.x](https://github.com/elastic/elasticsearch-ruby/actions/workflows/6.x.yml/badge.svg?branch=6.x)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/6.x.yml)|
55+
| 7.x | 7.x | :white_check_mark: | [![7.x](https://github.com/elastic/elasticsearch-ruby/actions/workflows/7.x.yml/badge.svg?branch=7.x)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/7.x.yml) |
56+
| master | master | :x: | [![master](https://github.com/elastic/elasticsearch-ruby/actions/workflows/master.yml/badge.svg?branch=master)](https://github.com/elastic/elasticsearch-ruby/actions/workflows/master.yml) |
3657

3758
## Installation
3859

@@ -51,31 +72,58 @@ or install it from a source code checkout:
5172
bundle install
5273
rake install
5374

54-
## Usage
75+
## Configuration
5576

56-
This library is a wrapper for two separate libraries:
77+
* [Identifying running tasks with X-Opaque-Id](#identifying-running-tasks-with-x-opaque-id)
78+
* [Api Key Authentication](#api-key-authentication)
5779

58-
* [`elasticsearch-transport`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-transport),
59-
which provides a low-level Ruby client for connecting to an [Elasticsearch](http://elasticsearch.com) cluster
60-
* [`elasticsearch-api`](https://github.com/elasticsearch/elasticsearch-ruby/tree/master/elasticsearch-api),
61-
which provides a Ruby API for the Elasticsearch RESTful API
80+
### Identifying running tasks with X-Opaque-Id
6281

63-
Install the `elasticsearch` package and use the API directly:
82+
The X-Opaque-Id header allows to track certain calls, or associate certain tasks with the client that started them ([more on the Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/master/tasks.html#_identifying_running_tasks)). To use this feature, you need to set an id for `opaque_id` on the client on each request. Example:
6483

6584
```ruby
66-
require 'elasticsearch'
85+
client = Elasticsearch::Client.new
86+
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')
87+
```
88+
The search request will include the following HTTP Header:
89+
```
90+
X-Opaque-Id: 123456
91+
```
6792

68-
client = Elasticsearch::Client.new log: true
93+
You can also set a prefix for X-Opaque-Id when initializing the client. This will be prepended to the id you set before each request if you're using X-Opaque-Id. Example:
94+
```ruby
95+
client = Elastic::Transport::Client.new(opaque_id_prefix: 'eu-west1_')
96+
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')
97+
```
98+
The request will include the following HTTP Header:
99+
```
100+
X-Opaque-Id: eu-west1_123456
101+
```
69102

70-
client.cluster.health
103+
### Api Key Authentication
71104

72-
client.transport.reload_connections!
105+
You can use [**API Key authentication**](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html):
106+
107+
``` ruby
108+
Elasticsearch::Client.new(
109+
host: host,
110+
transport_options: transport_options,
111+
api_key: credentials
112+
)
113+
```
73114

74-
client.search q: 'test'
115+
Where credentials is either the base64 encoding of `id` and `api_key` joined by a colon or a hash with the `id` and `api_key`:
75116

76-
# etc.
117+
``` ruby
118+
Elasticsearch::Client.new(
119+
host: host,
120+
transport_options: transport_options,
121+
api_key: {id: 'my_id', api_key: 'my_api_key'}
122+
)
77123
```
78124

125+
## API and Transport
126+
79127
Please refer to the specific library documentation for details:
80128

81129
* **Transport**:
@@ -86,10 +134,11 @@ Please refer to the specific library documentation for details:
86134
[[README]](https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-api/README.md)
87135
[[Documentation]](http://rubydoc.info/gems/elasticsearch-api/file/README.markdown)
88136

137+
89138
## Development
90139

91140
You can run `rake -T` to check the test tasks. Use `COVERAGE=true` before running a test task to check the coverage with Simplecov.
92141

93142
## License
94143

95-
This software is licensed under the [Apache 2 license](./LICENSE).
144+
This software is licensed under the [Apache 2 license](./LICENSE).

0 commit comments

Comments
 (0)