Connectingedit

This page contains the information you need to connect and use the Client with Elasticsearch.

On this page

Authenticationedit

This document contains code snippets to show you how to connect to various Elasticsearch providers.

Elastic Cloudedit

If you are using Elastic Cloud, the client offers an easy way to connect to it. You must pass the Cloud ID that you can find in the cloud console, then your username and password.

require 'elasticsearch'

client = Elasticsearch::Client.new(
  cloud_id: '<CloudID>'
  user: '<Username>',
  password: '<Password>',
)

You can also connect to the Cloud by using API Key authentication:

client = Elasticsearch::Client.new(
  cloud_id: '<CloudID>',
  api_key: {id: '<Id>', api_key: '<APIKey>'}
)

API Key authenticationedit

You can also use the ApiKey authentication.

If you provide both basic authentication credentials and the ApiKey configuration, the ApiKey takes precedence. You can also use API Key authentication:

Elasticsearch::Client.new(
  host: host,
  transport_options: transport_options,
  api_key: credentials
)

Where credentials is either the base64 encoding of id and api_key joined by a colon or a hash with the id and api_key:

Elasticsearch::Client.new(
  host: host,
  transport_options: transport_options,
  api_key: {id: 'my_id', api_key: 'my_api_key'}
)

Basic authenticationedit

You can pass the authentication credentials, scheme and port in the host configuration hash:

client = Elasticsearch::Client.new(
  hosts:
	  [
  	   {
    	   host: 'my-protected-host',
    	   port: '443',
    	   user: 'USERNAME',
    	   password: 'PASSWORD',
    	   scheme: 'https'
  	   }
	  ]
)

Or use the common URL format:

client = Elasticsearch::Client.new(url: https://username:password@localhost:9200)

To pass a custom certificate for SSL peer verification to Faraday-based clients, use the transport_options option:

Elasticsearch::Client.new(
  url: 'https://username:password@localhost:9200',
  transport_options: {
	ssl: { ca_file: '/path/to/cacert.pem' }
  }
)

Usageedit

The following snippet shows an example of using the Ruby client:

require 'elasticsearch'

client = Elasticsearch::Client.new log: true

client.cluster.health

client.index(index: 'my-index', id: 1, body: { title: 'Test' })

client.indices.refresh(index: 'my-index')

client.search(index: 'my-index', body: { query: { match: { title: 'test' } } })

Using the Client in a Function-as-a-Service Environmentedit

This section illustrates the best practices for leveraging the Elasticsearch client in a Function-as-a-Service (FaaS) environment. The most influential optimization is to initialize the client outside of the function, the global scope. This practice does not only improve performance but also enables background functionality as – for example – sniffing. The following examples provide a skeleton for the best practices.

GCP Cloud Functionsedit

require 'functions_framework'
require 'elasticsearch'

client = Elasticsearch::Client.new(
  cloud_id: "elasic-cloud-id",
  user: "elastic",
  password: "password",
  log: true
)

FunctionsFramework.http "hello_world" do |request|
  client.search(
    index: 'stack-overflow',
    body: {
      query: {
        match: {
          title: {
            query: 'phone application'
          }
        }
      }
    }
  )
end

AWS Lambdaedit

require 'elasticsearch'

def client
  @client ||= Elasticsearch::Client.new(
    cloud_id: "elastic-cloud-id",
    user: "elastic",
    password: "password",
    log: true
  )
end

def lambda_handler(event:, context:)
  client.search(
    index: 'stack-overflow',
    body: {
      query: {
        match: {
          title: {
            query: 'phone application'
          }
        }
      }
    }
  )
end