-
Notifications
You must be signed in to change notification settings - Fork 1.2k
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.
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.
There are two use cases for a client.
The default use case is to have a client that does all the heavy lifting for you: It monitors nodes in your cluster and adds and removes them automatically; it does health checks for existing nodes; it has retries etc. You create this type of client with elastic.NewClient(...) (see below).
Sometimes you simply need a lightweight client, e.g. in a restricted environment like App Engine. These types of environments often need a cheap, request-scoped interface to Elasticsearch. For your convenience, there is a elastic.NewSimpleClient(...) that creates such a client for you. It disables all the fancy stuff of elastic.NewClient(...), e.g. sniffing and health checks.
Under the hood, a simple client is simply a stripped down, differently configured Client. However, both NewClient and NewSimpleClient return a *Client, so all features stay the same. Notice that you can still override client options with elastic.NewSimpleClient(...).
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 gopkg.in/olivere/elastic.v2 (for Elasticsearch 1.x), go get gopkg.in/olivere/elastic.v3 (for Elasticsearch 2.x) or go get gopkg.in/olivere/elastic.v5 (for Elasticsearch 5.x) on the command line, all you need to do is:
// Import net/http and elastic
import (
"net/http"
// Use this for Elasticsearch 1.x:
"gopkg.in/olivere/elastic.v2"
// Use this for Elasticsearch 2.x:
"gopkg.in/olivere/elastic.v3"
// Use this for Elasticsearch 5.x:
"gopkg.in/olivere/elastic.v5"
// Use this for Elasticsearch 6.x:
"github.com/olivere/elastic"
// Use this for Elasticsearch 7.x:
"github.com/olivere/elastic/v7"
)
...
// Create a client
client, err := elastic.NewClient()
if err != nil {
// Handle error
panic(err)
}
defer client.Stop()
...Notice: To create a simple client, replace elastic.NewClient() with elastic.NewSimpleClient(). All other features of Elastic are the same since both NewClient and NewSimpleClient return a *Client. They are just initialized with different options.
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)
}
defer client.Stop()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). Disable the sniffing feature if you don't want Elastic to try to add new nodes and remove unhealthy nodes from the cluster.
// 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)
}
defer client.Stop()If you tried all of the things above but keep getting an error such as No Elastic node is available, see the Connection Problems page for possible resolution.
See Configuration for the list of configuration settings.
You might want to visit the page about services