[[overview]]
== Overview

This is the official Ruby client for Elastic Enterprise Search.

[discrete]
=== Compatibility

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**:

For **Elastic Enterprise Search 7.0** and later, use the major version 7 (`7.x.y`) of the library.

[discrete]
=== HTTP Library
This library uses https://github.com/elastic/elastic-transport-ruby[elastic-transport], the low-level Ruby client for connecting to an Elastic clusters - also used in the official https://github.com/elastic/elasticsearch-ruby[Elasticsearch Ruby Client]. It uses https://rubygems.org/gems/faraday[Faraday], which supports several https://lostisland.github.io/faraday/adapters/[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 https://github.com/drbrain/net-http-persistent[Net::HTTP::Persistent], https://github.com/toland/patron[patron] or https://github.com/typhoeus/typhoeus[Typhoeus]. For JRuby, https://github.com/cheald/manticore[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:

[source,ruby]
---------------------------------------------------
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 https://github.com/elastic/elastic-transport-ruby/blob/main/lib/elastic/transport/transport/errors.rb[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 https://github.com/elastic/elastic-transport-ruby#exception-handling[here]. You can find the full documentation for `elastic-transport` at https://rubydoc.info/gems/elastic-transport[RubyDoc].

The clients pass different options to transport, you can check them out https://rubydoc.info/github/elastic/enterprise-search-ruby/Elastic/EnterpriseSearch/Client[on RubyDocs].

[discrete]
==== Setting the host and port

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.

[discrete]
=== Logging

You can enable logging with the default logger by passing `log: true` as a parameter to the client's initializer, or pass in a Logger object with the `:logger` parameter:

[source,rb]
----------------------------
logger = MyLogger.new
client = Elastic::EnterpriseSearch::Client.new(logger: logger)
----------------------------

[discrete]
=== License

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.