Skip to content

Commit 17b70e8

Browse files
ezimuelezimuel
committed
Updated README and docs
1 parent 17d661a commit 17b70e8

8 files changed

+132
-11
lines changed

‎README.md

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ The full documentation is available on https://metacpan.org/module/Search::Elast
1313
* Good defaults
1414
* Helper utilities for more complex operations, such as bulk indexing, scrolled searches and reindexing.
1515
* Logging support via `Log::Any`
16-
* Compatibility with the [official clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html)
1716
* Easy extensibility
1817

1918
## Install
@@ -22,6 +21,83 @@ The full documentation is available on https://metacpan.org/module/Search::Elast
2221
cpanm Search::Elasticsearch
2322
```
2423

24+
## Connecting to Elasticsearch
25+
26+
You can connect to Elasticsearch using the following examples:
27+
28+
```perl
29+
use Search::Elasticsearch;
30+
31+
# Connect to localhost:9200 (default)
32+
my $e = Search::Elasticsearch->new();
33+
34+
# Connect to http://search:9200
35+
my $e = Search::Elasticsearch->new(
36+
nodes => [ 'search:9200' ]
37+
);
38+
39+
# Round-robin between two nodes:
40+
my $e = Search::Elasticsearch->new(
41+
nodes => [
42+
'search1:9200',
43+
'search2:9200'
44+
]
45+
);
46+
```
47+
48+
After the connection you can start using the Elaticsearch endpoints
49+
as functions of `$e` object, as follows:
50+
51+
```perl
52+
# Info endpoint
53+
my $result = $e->info();
54+
55+
printf("Name: %s\n", $result->{name}); # e.g. Name: instance-001
56+
printf("Version: %s\n", $result->{version}->{number}); # e.g. Version: 8.5.2
57+
```
58+
59+
## Connecting to Elastic Cloud
60+
61+
[Elastic Cloud](https://www.elastic.co/cloud/) is the cloud solution offered by Elastic.
62+
63+
To connect the Perl client to Elastic Cloud you need the get the following data:
64+
65+
- the Elasticsearch server address (i.e. public URL);
66+
- the Elastic Cloud API key;
67+
68+
You can retrieve these data from your Elastic Cloud dashboard. You need to open the
69+
**Manage Deployments** page and **Copy endpoint of Elasticsearch** (see screenshot below).
70+
71+
![Endpoint](docs/images/copy_endpoint.png)
72+
73+
This endpoint is the server address of Test instance (e.g. https://my-test.es.us-central1.gcp.cloud.es.io).
74+
75+
After this step, you need to generate an `API key` in the `Management` page under the section `Security`.
76+
77+
![Security](docs/images/create_api_key.png)
78+
79+
When you click on `Create API key` button you can choose a name and set the
80+
other options (for example, restrict privileges, expire after time, and so on).
81+
82+
![Choose an API name](docs/images/api_key_name.png)
83+
84+
After this step you will get the `API key`in the API keys page.
85+
86+
![API key](docs/images/cloud_api_key.png)
87+
88+
**IMPORTANT**: you need to copy and store the `API key`in a secure place, since
89+
you will not be able to view it again in Elastic Cloud.
90+
91+
Finally, you can use the Elasticsearch endpoint and the API Key for connecting
92+
the Perl client as follows:
93+
94+
```perl
95+
my $e = Search::Elasticsearch->new(
96+
nodes => [ 'https://my-test.es.us-central1.gcp.cloud.es.io' ],
97+
elastic_cloud_api_key => 'insert here the API Key'
98+
);
99+
```
100+
25101
## Compatibility
26102

27103
Language clients are forward compatible; meaning that clients support communicating

‎docs/elastic_cloud.asciidoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
== Elastic Cloud
2+
3+
Search::Elasticsearch can be used to connect to https://www.elastic.co/cloud/[Elastic Cloud].
4+
5+
[Elastic Cloud](https://www.elastic.co/cloud/) is the cloud solution offered by Elastic.
6+
7+
To connect the Perl client to Elastic Cloud you need the get the following data:
8+
9+
* the Elasticsearch server address (i.e. public URL);
10+
* the Elastic Cloud API key;
11+
12+
You can retrieve these data from your Elastic Cloud dashboard. You need to open the
13+
*Manage Deployments* page and *Copy endpoint of Elasticsearch* (see screenshot below).
14+
15+
image::images/copy_endpoint.png[alt="Copy endpoint",align="center"]
16+
17+
This endpoint is the server address of Test instance (e.g. https://my-test.es.us-central1.gcp.cloud.es.io).
18+
19+
After this step, you need to generate an *API key* in the *Management* page under the section *Security*.
20+
21+
image::images/create_api_key.png[alt="Security",align="center"]
22+
23+
When you click on *Create API key* button you can choose a name and set the
24+
other options (for example, restrict privileges, expire after time, and so on).
25+
26+
image::images/api_key_name.png[alt="API key name",align="center"]
27+
28+
After this step you will get the *API key* in the API keys page.
29+
30+
image::images/cloud_api_key.png[alt="API key",align="center"]
31+
32+
**IMPORTANT**: you need to copy and store the `API key`in a secure place, since
33+
you will not be able to view it again in Elastic Cloud.
34+
35+
Finally, you can use the Elasticsearch endpoint and the API Key for connecting
36+
the Perl client as follows:
37+
38+
[source,perl]
39+
------------------------------------
40+
my $e = Search::Elasticsearch->new(
41+
nodes => [ 'https://my-test.es.us-central1.gcp.cloud.es.io' ],
42+
elastic_cloud_api_key => 'insert here the API Key'
43+
);
44+
------------------------------------

‎docs/images/api_key_name.png

32 KB
Loading

‎docs/images/cloud_api_key.png

117 KB
Loading

‎docs/images/copy_endpoint.png

81.3 KB
Loading

‎docs/images/create_api_key.png

78.7 KB
Loading

‎docs/index.asciidoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
66

7+
include::installation.asciidoc[]
8+
79
include::overview.asciidoc[]
810

9-
include::installation.asciidoc[]
11+
include::elastic_cloud.asciidoc[]

‎docs/overview.asciidoc

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,10 @@ This client provides:
2525

2626
* Logging support via Log::Any.
2727

28-
* Compatibility with the official clients for Python, Ruby, PHP and JavaScript.
29-
3028
* Easy extensibility.
3129

30+
* Easy connection to https://www.elastic.co/cloud/[Elastic Cloud].
31+
3232

3333
=== Synopsis
3434

@@ -83,19 +83,18 @@ my $results = $e->search(
8383
);
8484
------------------------------------
8585

86-
[[v0_90]]
87-
=== Elasticsearch 0.90.* and earlier
86+
[[v7_00]]
87+
=== Elasticsearch 7.00.*
8888

89-
The current version of the client supports the Elasticsearch 1.0 branch by
90-
default, which is not backwards compatible with the 0.90 branch.
89+
The current version of the client supports the Elasticsearch 8 and 7.
9190

92-
If you need to talk to a version of Elasticsearch before 1.0.0,
93-
please use `Search::Elasticsearch::Client::0_90::Direct` as follows:
91+
If you need to talk to a version of Elasticsearch 7,
92+
please use `Search::Elasticsearch::Client::7_00::Direct` as follows:
9493

9594
[source,perl]
9695
------------------------------------
9796
$es = Search::Elasticsearch->new(
98-
client => '0_90::Direct'
97+
client => '7_00::Direct'
9998
);
10099
------------------------------------
101100

0 commit comments

Comments
 (0)