elasticsearch

README

go-elasticsearch

The official Go client for Elasticsearch.

Download the latest version of Elasticsearch or sign-up for a free trial of Elastic Cloud.

Compatibility

Go

Starting from version 8.12.0, this library follow the Go language policy. Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release.

Elasticsearch

Language clients are forward compatible; meaning that clients support communicating with greater or equal minor versions of Elasticsearch. Elasticsearch language clients are only backwards compatible with default distributions and without guarantees made.

When using Go modules, include the version in the import path, and specify either an explicit version or a branch:

require github.com/elastic/go-elasticsearch/v8 v8.0.0
require github.com/elastic/go-elasticsearch/v7 7.17

It's possible to use multiple versions of the client in a single project:

// go.mod
github.com/elastic/go-elasticsearch/v7 v7.17.0
github.com/elastic/go-elasticsearch/v8 v8.0.0

// main.go
import (
  elasticsearch7 "github.com/elastic/go-elasticsearch/v7"
  elasticsearch8 "github.com/elastic/go-elasticsearch/v8"
)
// ...
es7, _ := elasticsearch7.NewDefaultClient()
es8, _ := elasticsearch8.NewDefaultClient()

The main branch of the client is compatible with the current master branch of Elasticsearch.

Installation

Refer to the Installation section of the getting started documentation.

Connecting

Refer to the Connecting section of the getting started documentation.

Operations

• Creating an index
• Indexing documents
• Getting documents
• Searching documents
• Updating documents
• Deleting documents
• Deleting an index

Helpers

The esutil package provides convenience helpers for working with the client. At the moment, it provides the esutil.JSONReader() and the esutil.BulkIndexer helpers.

Examples

The _examples folder contains a number of recipes and comprehensive examples to get you started with the client, including configuration and customization of the client, using a custom certificate authority (CA) for security (TLS), mocking the transport for unit tests, embedding the client in a custom type, building queries, performing requests individually and in bulk, and parsing the responses.

License

This software is licensed under the Apache 2 license. See NOTICE.

Documentation

Overview

Package elasticsearch provides a Go client for Elasticsearch.

Create the client with the NewDefaultClient function:

elasticsearch.NewDefaultClient()

The ELASTICSEARCH_URL environment variable is used instead of the default URL, when set. Use a comma to separate multiple URLs.

To configure the client, pass a Config object to the NewClient function:

cfg := elasticsearch.Config{
  Addresses: []string{
    "http://localhost:9200",
    "http://localhost:9201",
  },
  Username: "foo",
  Password: "bar",
  Transport: &http.Transport{
    MaxIdleConnsPerHost:   10,
    ResponseHeaderTimeout: time.Second,
    DialContext:           (&net.Dialer{Timeout: time.Second}).DialContext,
    TLSClientConfig: &tls.Config{
      MinVersion:         tls.VersionTLS12,
    },
  },
}

elasticsearch.NewClient(cfg)

When using the Elastic Service (https://elastic.co/cloud), you can use CloudID instead of Addresses. When either Addresses or CloudID is set, the ELASTICSEARCH_URL environment variable is ignored.

See the elasticsearch_integration_test.go file and the _examples folder for more information.

Call the Elasticsearch APIs by invoking the corresponding methods on the client:

res, err := es.Info()
if err != nil {
  log.Fatalf("Error getting response: %s", err)
}

log.Println(res)

See the github.com/elastic/go-elasticsearch/esapi package for more information about using the API.

See the github.com/elastic/elastic-transport-go package for more information about configuring the transport.

Index

• Constants
• func NewOpenTelemetryInstrumentation(provider trace.TracerProvider, captureSearchBody bool) elastictransport.Instrumentation
• type BaseClient
  • func (c *BaseClient) DiscoverNodes() error
  • func (c *BaseClient) InstrumentationEnabled() elastictransport.Instrumentation
  • func (c *BaseClient) Metrics() (elastictransport.Metrics, error)
  • func (c *BaseClient) Perform(req *http.Request) (*http.Response, error)
• type Client
  • func NewClient(cfg Config) (*Client, error)
  • func NewDefaultClient() (*Client, error)
• type Config
• type TypedClient
  • func NewTypedClient(cfg Config) (*TypedClient, error)

Examples

• NewClient
• NewClient (Logger)
• NewDefaultClient

Constants

const (

	// Version returns the package version as a string.
	Version = version.Client

	// HeaderClientMeta Key for the HTTP Header related to telemetry data sent with
	// each request to Elasticsearch.
	HeaderClientMeta = "x-elastic-client-meta"
)

Functions

func NewOpenTelemetryInstrumentation

func NewOpenTelemetryInstrumentation(provider trace.TracerProvider, captureSearchBody bool) elastictransport.Instrumentation

NewOpenTelemetryInstrumentation provides the OpenTelemetry integration for both low-level and TypedAPI. provider is optional, if nil is passed the integration will retrieve the provider set globally by otel. captureSearchBody allows to define if the search queries body should be included in the span. Search endpoints are:

search
async_search.submit
msearch
eql.search
terms_enum
search_template
msearch_template
render_search_template

Types

type BaseClient

type BaseClient struct {
	Transport elastictransport.Interface
	// contains filtered or unexported fields
}

BaseClient represents the Elasticsearch client.

func (*BaseClient) DiscoverNodes

func (c *BaseClient) DiscoverNodes() error

DiscoverNodes reloads the client connections by fetching information from the cluster.

func (*BaseClient) InstrumentationEnabled

func (c *BaseClient) InstrumentationEnabled() elastictransport.Instrumentation

InstrumentationEnabled propagates back to the client the Instrumentation provided by the transport.

func (*BaseClient) Metrics

func (c *BaseClient) Metrics() (elastictransport.Metrics, error)

Metrics returns the client metrics.

func (*BaseClient) Perform

func (c *BaseClient) Perform(req *http.Request) (*http.Response, error)

Perform delegates to Transport to execute a request and return a response.

type Client

type Client struct {
	BaseClient
	*esapi.API
}

Client represents the Functional Options API.

func NewClient

func NewClient(cfg Config) (*Client, error)

NewClient creates a new client with configuration from cfg.

It will use http://localhost:9200 as the default address.

It will use the ELASTICSEARCH_URL environment variable, if set, to configure the addresses; use a comma to separate multiple URLs.

If either cfg.Addresses or cfg.CloudID is set, the ELASTICSEARCH_URL environment variable is ignored.

It's an error to set both cfg.Addresses and cfg.CloudID.

Example

cfg := elasticsearch.Config{
	Addresses: []string{
		"http://localhost:9200",
	},
	Username: "foo",
	Password: "bar",
	Transport: &http.Transport{
		MaxIdleConnsPerHost:   10,
		ResponseHeaderTimeout: time.Second,
		DialContext:           (&net.Dialer{Timeout: time.Second}).DialContext,
		TLSClientConfig: &tls.Config{
			MinVersion: tls.VersionTLS12,
		},
	},
}

es, _ := elasticsearch.NewClient(cfg)
log.Print(es.Transport.(*elastictransport.Client).URLs())

Example (Logger)

// import "github.com/elastic/go-elasticsearch/v8/elastictransport"

// Use one of the bundled loggers:
//
// * elastictransport.TextLogger
// * elastictransport.ColorLogger
// * elastictransport.CurlLogger
// * elastictransport.JSONLogger

cfg := elasticsearch.Config{
	Logger: &elastictransport.ColorLogger{Output: os.Stdout},
}

elasticsearch.NewClient(cfg)

func NewDefaultClient

func NewDefaultClient() (*Client, error)

NewDefaultClient creates a new client with default options.

It will use http://localhost:9200 as the default address.

It will use the ELASTICSEARCH_URL environment variable, if set, to configure the addresses; use a comma to separate multiple URLs.

Example

es, err := elasticsearch.NewDefaultClient()
if err != nil {
	log.Fatalf("Error creating the client: %s\n", err)
}

res, err := es.Info()
if err != nil {
	log.Fatalf("Error getting the response: %s\n", err)
}
defer res.Body.Close()

log.Print(es.Transport.(*elastictransport.Client).URLs())

type Config

type Config struct {
	Addresses []string // A list of Elasticsearch nodes to use.
	Username  string   // Username for HTTP Basic Authentication.
	Password  string   // Password for HTTP Basic Authentication.

	CloudID                string // Endpoint for the Elastic Service (https://elastic.co/cloud).
	APIKey                 string // Base64-encoded token for authorization; if set, overrides username/password and service token.
	ServiceToken           string // Service token for authorization; if set, overrides username/password.
	CertificateFingerprint string // SHA256 hex fingerprint given by Elasticsearch on first launch.

	Header http.Header // Global HTTP request header.

	// PEM-encoded certificate authorities.
	// When set, an empty certificate pool will be created, and the certificates will be appended to it.
	// The option is only valid when the transport is not specified, or when it's http.Transport.
	CACert []byte

	RetryOnStatus []int                           // List of status codes for retry. Default: 502, 503, 504.
	DisableRetry  bool                            // Default: false.
	MaxRetries    int                             // Default: 3.
	RetryOnError  func(*http.Request, error) bool // Optional function allowing to indicate which error should be retried. Default: nil.

	CompressRequestBody      bool // Default: false.
	CompressRequestBodyLevel int  // Default: gzip.DefaultCompression.
	PoolCompressor           bool // If true, a sync.Pool based gzip writer is used. Default: false.

	DiscoverNodesOnStart  bool          // Discover nodes when initializing the client. Default: false.
	DiscoverNodesInterval time.Duration // Discover nodes periodically. Default: disabled.

	EnableMetrics           bool // Enable the metrics collection.
	EnableDebugLogger       bool // Enable the debug logging.
	EnableCompatibilityMode bool // Enable sends compatibility header

	DisableMetaHeader bool // Disable the additional "X-Elastic-Client-Meta" HTTP header.

	RetryBackoff func(attempt int) time.Duration // Optional backoff duration. Default: nil.

	Transport http.RoundTripper         // The HTTP transport object.
	Logger    elastictransport.Logger   // The logger object.
	Selector  elastictransport.Selector // The selector object.

	// Optional constructor function for a custom ConnectionPool. Default: nil.
	ConnectionPoolFunc func([]*elastictransport.Connection, elastictransport.Selector) elastictransport.ConnectionPool

	Instrumentation elastictransport.Instrumentation // Enable instrumentation throughout the client.
}

Config represents the client configuration.

type TypedClient

type TypedClient struct {
	BaseClient
	*typedapi.API
}

TypedClient represents the Typed API.

func NewTypedClient

func NewTypedClient(cfg Config) (*TypedClient, error)

NewTypedClient create a new client with the configuration from cfg.

This version uses the same configuration as NewClient.

It will return the client with the TypedAPI.