Overviewedit

This is the official Ruby client for Elastic Enterprise Search.

Compatibilityedit

Current development happens in the main branch.

The library is compatible with all Elastic Enterprise Search versions since 7.x but you have to use a matching major version:

HTTP Libraryedit

This library uses elastic-transport, the low-level Ruby client for connecting to an Elastic cluster - also used in the official Elasticsearch Ruby Client. It uses Faraday, which supports several adapters and will use Net::HTTP by default. For optimal performance with the Enterprise Search API, we suggest using an HTTP library which supports persistent ("keep-alive") connections. For the standard Ruby implementation, this could be Net::HTTP::Persistent, patron or Typhoeus. For JRuby, Manticore is a great option as well. Require the library for the adapter in your code and then pass in the :adapter parameter to the client when you initialize it:

require 'elastic-enterprise-search'
require 'faraday/net_http_persistent'

client = Elastic::EnterpriseSearch::Client.new(adapter: :net_http_persistent)

All requests, if successful, will return an Elastic::Transport::Transport::Response instance. You can access the response body, headers and status.

elastic-transport defines a number of exception classes for various client and server errors, as well as unsuccessful HTTP responses, making it possible to rescue specific exceptions with desired granularity. More details here. You can find the full documentation for elastic-transport at our official documentation and RubyDoc.

The clients pass different options to transport, you can check them out on RubyDocs.

Setting the host and portedit

If you don’t specify a host and port, the client will default to http://localhost:3002. Otherwise pass in the :host parameter as a String.

Loggingedit

You can enable logging with the default logger by passing log: true as a parameter to the client’s initializer. You can also pass in a Logger object with the :logger parameter, any confoming logger implementation will work:

logger = MyLogger.new
client = Elastic::EnterpriseSearch::Client.new(logger: logger)

To trace requests and responses in the Curl format, set the trace argument:

> client = Elastic::EnterpriseSearch::Client.new(trace: true)
> client.health
curl -X GET -H 'x-elastic-client-meta: ent=8.3.0,rb=3.1.2,t=8.0.1,fd=1.10.0,nh=0.2.0, User-Agent: elastic-transport-ruby/8.0.1 (RUBY_VERSION: 3.1.2; linux x86_64; Faraday v1.10.0), Content-Type: application/json
' 'http://localhost:9200/api/ent/v1/internal/health/?pretty'

# 2022-05-23T08:39:09+01:00 [200] (0.049s)
#
# {"name":"5b8067bf95fb", ...
 =>
#<Elastic::API::Response:0x00007f9096e15f90
 @response=
  #<Elastic::Transport::Transport::Response:0x00007f9096e160a8
   @body=
    {"name"=>"5b8067bf95fb",
    ...

This will use the elastic-transport default logger. But you can pass in a custom logger with:

client = Elastic::EnterpriseSearch::Client.new(tracer: my_tracer)

Licenseedit

Licensed to Elasticsearch B.V. under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Elasticsearch B.V. licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.