Getting started

Note

This client is for use with Elasticsearch Serverless only. See also the Elasticsearch clients.

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

Requirements

Ruby 3.0 or higher installed on your system.
To use the elasticsearch-serverless gem, you must have an API key and Elasticsearch endpoint for an Elasticsearch Serverless project.

Installation

From GitHub’s releases

You can install the Ruby Client from RubyGems:

gem install elasticsearch-serverless --pre

Check releases for the latest available versions.

From the source code

You can install the Ruby client from the client’s source code with the following commands:

		# From the project's root directory:
gem build elasticsearch-serverless.gemspec
gem install elasticsearch-serverless-x.x.x.gem

	

Using the Gemfile

Alternatively, you can include the client gem in your Ruby project’s Gemfile:

gem 'elasticsearch-serverless'

Once installed, require it in your code:

require 'elasticsearch-serverless'

Running a Ruby console

You can also run the client from a Ruby console using the client’s source code. To start the console, run the following commands:

		# From the project's root directory:
bundle install
bundle exec rake console

	

Initialize the client

Initialize the client using your API key and Elasticsearch endpoint:

		client = ElasticsearchServerless::Client.new(
  api_key: 'your_api_key',
  url: 'https://...'
)

	

To get API keys for the Elasticsearch endpoint for a project, see Get started.

Using the API

After you’ve initialized the client, you can start ingesting documents. You can use the bulk API for this. This API enables you to index, update, and delete several documents in one request.

Note

The code examples in this section use the Ruby console. To set up the console, Running a Ruby console.

Creating an index and ingesting documents

You can call the bulk API with a body parameter, an array of hashes that define the action, and a document.

The following is an example of indexing some classic books into the books index:

		# First, build your data:
> body = [
  { index: { _index: 'books', data: {name: "Snow Crash", author: "Neal Stephenson", release_date: "1992-06-01", page_count: 470} } },
  { index: { _index: 'books', data: {name: "Revelation Space", author: "Alastair Reynolds", release_date: "2000-03-15", page_count: 585} } },
  { index: { _index: 'books', data: {name: "1984", author: "George Orwell", release_date: "1949-06-08", page_count: 328} } },
  { index: { _index: 'books', data: {name: "Fahrenheit 451", author: "Ray Bradbury", release_date: "1953-10-15", page_count: 227} } },
  { index: { _index: 'books', data: {name: "Brave New World", author: "Aldous Huxley", release_date: "1932-06-01", page_count: 268} } },
  { index: { _index: 'books', data: {name: "The Handmaid's Tale", author: "Margaret Atwood", release_date: "1985-06-01", page_count: 311} } }
]
# Then ingest the data via the bulk API:
> response = client.bulk(body: body)
# You can check the response if the items are indexed and have a document (doc) ID:
> response['items']
# Returns:
#  =>
# [{"index"=>{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>0, "_primary_term"=>1, "status"=>201}},
#  {"index"=>{"_index"=>"books", "_id"=>"Ptink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>1, "_primary_term"=>1, "status"=>201}},
#  {"index"=>{"_index"=>"books", "_id"=>"P9ink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>2, "_primary_term"=>1, "status"=>201}},
#  {"index"=>{"_index"=>"books", "_id"=>"QNink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>3, "_primary_term"=>1, "status"=>201}},
#  {"index"=>{"_index"=>"books", "_id"=>"Qdink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>4, "_primary_term"=>1, "status"=>201}},
#  {"index"=>{"_index"=>"books", "_id"=>"Qtink4cBmDx329iqhzM2", "_version"=>1, "result"=>"created", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>5, "_primary_term"=>1, "status"=>201}}]

	

When you use the client to make a request to Elasticsearch, it returns an API response object. You can check the HTTP return code by calling status and the HTTP headers by calling headers on the response object. The response object also behaves as a Hash, so you can access the body values directly as seen on the previous example with response['items'].

Getting documents

You can get documents by using the following code:

> client.get(index: 'books', id: 'id')1

Replace 'id' with a valid doc ID

Searching

Now that some data is available, you can search your documents using the search API:

		> response = client.search(index: 'books', q: 'snow')
> response['hits']['hits']
# Returns:
# => [{"_index"=>"books", "_id"=>"Pdink4cBmDx329iqhzM2", "_score"=>1.5904956, "_source"=>{"name"=>"Snow Crash", "author"=>"Neal Stephenson", "release_date"=>"1992-06-01", "page_count"=>470}}]

	

Updating a document

You can call the update API to update a document:

		> response = client.update(
  index: 'books',
  id: 'id', 1
  body: { doc: { page_count: 312 } }
)

	

Replace 'id' with a valid doc ID

Deleting a document

You can call the delete API to delete a document:

> client.delete(index: 'books', id: 'id') 1

Replace 'id' with a valid doc ID

Deleting an index

> client.indices.delete(index: 'books')