« Get started with the serverless Python client REST APIs »

› › ›

Get started with the serverless Ruby client

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

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 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 or 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')

« Get started with the serverless Python client REST APIs »