Get started with the serverless Ruby client

edit

Get started with the serverless Ruby client

edit

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
edit
  • 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
edit
From GitHub’s releases
edit

You can install the Ruby Client from RubyGems:

gem install elasticsearch-serverless --pre

Check releases for the latest available versions.

From the source code
edit

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
edit

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
edit

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
edit

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
edit

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.

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
edit

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
edit

You can get documents by using the following code:

> client.get(index: 'books', id: 'id') # Replace 'id' with a valid doc ID
Searching
edit

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
edit

You can call the update API to update a document:

> response = client.update(
  index: 'books',
  id: 'id',  # Replace 'id' with a valid doc ID
  body: { doc: { page_count: 312 } }
)
Deleting a document
edit

You can call the delete API to delete a document:

> client.delete(index: 'books', id: 'id')  # Replace 'id' with a valid doc ID
Deleting an index
edit
> client.indices.delete(index: 'books')