[[getting-started-ruby]]
== Getting started

This page guides you through the installation process of the Ruby client, shows 
you how to instantiate the client, and how to perform basic Elasticsearch 
operations with it.

[discrete]
=== Requirements

A currently maintained version of Ruby (3.0+) or JRuby (9.3+).

[discrete]
=== Installation 

To install the latest version of the client, run the following command:

[source,shell]
--------------------------
gem install elasticsearch
--------------------------

Refer to the <<ruby-install>> page to learn more.


[discrete]
=== Connecting

You can connect to the Elastic Cloud using an API key and the Elasticsearch 
endpoint. 

[source,rb]
----
client = Elasticsearch::Client.new(
  cloud_id: '<CloudID>',
  api_key: '<ApiKey>'
)
----

Your Elasticsearch endpoint can be found on the **My deployment** page of your 
deployment:

image::images/es_endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"]

You can generate an API key on the **Management** page under Security.

image::images/create_api_key.png[alt="Create API key",align="center"]

For other connection options, refer to the <<connecting>> section.


[discrete]
=== Operations

Time to use Elasticsearch! This section walks you through the basic, and most 
important, operations of Elasticsearch. For more operations and more advanced 
examples, refer to the <<examples>> page.


[discrete]
==== Creating an index

This is how you create the `my_index` index:

[source,rb]
----
client.indices.create(index: 'my_index')
----


[discrete]
==== Indexing documents

This is a simple way of indexing a document:

[source,rb]
----
document = { name: 'elasticsearch-ruby' }
response = client.index(index: 'my_index', body: document)
# You can get the indexed document id with:
response['_id']
=> "PlgIDYkBWS9Ngdx5IMy-"
id = response['_id']
----


[discrete]
==== Getting documents

You can get documents by using the following code:

[source,rb]
----
client.get(index: 'my_index', id: id)
----


[discrete]
==== Searching documents

This is how you can create a single match query with the Ruby client: 

[source,rb]
----
client.search(index: 'my_index', body: { query: { match_all: {} } })
----


[discrete]
==== Updating documents

This is how you can update a document, for example to add a new field:

[source,rb]
----
client.update(index: 'my_index', id: id, body: { doc: { language: 'Ruby' } })
----


[discrete]
==== Deleting documents

[source,rb]
----
client.delete(index: 'my_index', id: id)
----


[discrete]
==== Deleting an index

[source,rb]
----
client.indices.delete(index: 'my_index')
----


[discrete]
== Further reading

* Use <<Helpers>> for a more confortable experience with the APIs.