Client

This page describes how to create a new client, what a client does when created, and a few other details you need to know to work with Elastic. If you want to know how to create an index, add documents, or search, you'll find that under Services.

What is a client?

In a nutshell, a client is way to communicate with Elasticsearch. When interacting with Elasticsearch, a few things need to be known in advance. For example, Elastic needs to know to which Elasticsearch cluster/nodes you want to connect to, what happens when a connection to a node is lost (because the node goes down for some reason) etc. All of these details are abstracted away in a client.

How do I create a client?

That's very simple. Let's assume you have a) Elasticsearch installed and running with its default settings (i.e. available at http://127.0.0.1:9200) and b) you got Elastic by running go get github.com/olivere/elastic on the command line, all you need to do is:

// Import net/http and elastic
import (
  "net/http"

  "github.com/olivere/elastic"
)

...
// Create a client
client, err := elastic.NewClient()
if err != nil {
  // Handle error
  panic(err)
}
...

If your Elasticsearch server is running on a different IP and/or port, just provide a URL to NewClient:

// Create a client and connect to http://192.168.2.10:9201
client, err := elastic.NewClient(elastic.SetURL("http://192.168.2.10:9201"))
if err != nil {
  // Handle error
  panic(err)
}

If the parameters to NewClient seem strange, read this article by Dave Cheney for how it works and why it's useful.

If you have an Elasticsearch cluster with several nodes, you can provide a list of URLs to connect to. However, this is not necessary as Elastic will automatically figure out all nodes in your cluster for you automatically (see sniffing).

// Create a client and connect to nodes http://127.0.0.1:9200 and http://127.0.0.1:9201
client, err := elastic.NewClient(elastic.SetURL("http://127.0.0.1:9200", "http://127.0.0.1:9201"))
if err != nil {
  // Handle error
  panic(err)
}

What configuration settings can I use?

Elastic comes with the following configuration settings:

• SetHttpClient(*http.Client) allows you to configure your own http.Client and/or http.Transport (default is http.DefaultClient).
• SetURL(...string) allows you to specify which URLs to connect to (default is http://127.0.0.1:9200).
• SetSniff(bool) allows you to specify whether Elastic should sniff the cluster periodically (default is true).
• SetSnifferTimeout(time.Duration) is the time before Elastic times out on sniffing nodes (default is 2 seconds).
• SetSnifferTimeoutStartup(time.Duration) is the sniffing timeout used while creating a new client. It is typically larger than sniffer timeout and proved to help on slow startup (default is 5 seconds).
• SetSnifferInterval(time.Duration) allows you to specify the interval between two sniffer processes (default is 15 minutes).
• SetHealthcheck(bool) allows you to specify whether Elastic will perform health checks by trying to connect to its nodes periodically (default is true).
• SetHealthcheckTimeout(time.Duration) is the timeout for health checks (default is 1 second).
• SetHealthcheckTimeoutStartup(time.Duration) is the health check timeout used while creating a new client. It is typically larger than health check timeout and might help on slow startup (default is 5 seconds).
• SetHealthcheckInterval(time.Duration) specifies the interval between two health checks (default is 60 seconds).
• SetMaxRetries(int) specifies the maximum number of retries for a single HTTP request before giving up (default is 0). If you set it to zero, there will be no retries.
• SetDecoder(elastic.Decoder) allows you to set your own decoder for JSON messages from Elasticsearch (default is &elastic.DefaultDecoder{}).
• SetErrorLog(*log.Logger) sets the logger to use for error messages (default is nil). The error log will contain e.g. messages about nodes joining the cluster or marked as dead.
• SetInfoLog(*log.Logger) sets the logger to use for informational messages (default is nil). The info log will contain e.g. requests and their response time.
• SetTraceLog(*log.Logger) sets the logger to use for printing HTTP requests and responses (default is nil). This is useful for debugging what's going on on the wire.

Here's a full example of configuring a new client:

// Obtain a client for an Elasticsearch cluster of two nodes,
// running on 10.0.1.1 and 10.0.1.2. Do not run the sniffer.
// Set the healthcheck interval to 10s. When requests fail,
// retry 5 times. Print error messages to os.Stderr and informational
// messages to os.Stdout.
client, err := elastic.NewClient(
  elastic.SetURL("http://10.0.1.1:9200", "http://10.0.1.2:9200"),
  elastic.SetSniff(false),
  elastic.SetHealthcheckInterval(10*time.Second),
  elastic.SetMaxRetries(5),
  elastic.SetErrorLog(log.New(os.Stderr, "ELASTIC ", log.LstdFlags)),
  elastic.SetInfoLog(log.New(os.Stdout, "", log.LstdFlags)))

Okay, I have a client. What do I do now?

You might want to visit the page about services