opensearch

README

OpenSearch Go Client

• Welcome!
• Project Resources
• Code of Conduct
• License
• Copyright

Welcome!

opensearch-go is a community-driven, open source fork of go-elasticsearch licensed under the Apache v2.0 License. For more information, see opensearch.org.

Project Resources

• Project Website
• Developer Guide
• User Guide
• Documentation
• Need help? Try Forums
• Project Principles
• Contributing to OpenSearch
• Maintainer Responsibilities
• Release Management
• Admin Responsibilities
• Security

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

License

This project is licensed under the Apache v2.0 License.

Copyright

Copyright OpenSearch Contributors. See NOTICE for details.

Documentation

Overview

Package opensearch provides a Go client for OpenSearch.

Create the client with the NewDefaultClient function:

opensearch.NewDefaultClient()

The OPENSEARCH_URL/ELASTICSEARCH_URL environment variable is used instead of the default URL, when set. Use a comma to separate multiple URLs. It is an error to set both environment variable.

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

cfg := opensearch.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.VersionTLS11,
    },
  },
}

opensearch.NewClient(cfg)

See the opensearch_integration_test.go file for more information.

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

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

log.Println(res)

See the github.com/opensearch-project/opensearch-go/opensearchapi package for more information about using the API.

See the github.com/opensearch-project/opensearch-go/opensearchtransport package for more information about configuring the transport.

Index

• Constants
• func ParseVersion(version string) (int64, int64, int64, error)
• type Client
  • func NewClient(cfg Config) (*Client, error)
  • func NewDefaultClient() (*Client, error)
  • func (c *Client) DiscoverNodes() error
  • func (c *Client) Metrics() (opensearchtransport.Metrics, error)
  • func (c *Client) Perform(req *http.Request) (*http.Response, error)
• type Config

Examples

• NewClient
• NewClient (Logger)
• NewDefaultClient

Constants

const Version = version.Client

Version returns the package version as a string.

Functions

func ParseVersion

func ParseVersion(version string) (int64, int64, int64, error)

ParseVersion returns an int64 representation of version.

Types

type Client

type Client struct {
	*opensearchapi.API // Embeds the API methods
	Transport          opensearchtransport.Interface
	// contains filtered or unexported fields
}

Client represents the OpenSearch client.

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 OPENSEARCH_URL/ELASTICSEARCH_URL environment variable, if set, to configure the addresses; use a comma to separate multiple URLs.

It's an error to set both OPENSEARCH_URL and ELASTICSEARCH_URL.

Example

cfg := opensearch.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.VersionTLS11,
		},
	},
}

client, _ := opensearch.NewClient(cfg)
log.Print(client.Transport.(*opensearchtransport.Client).URLs())

Example (Logger)

// import "github.com/opensearch-project/opensearch-go/opensearchtransport"

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

cfg := opensearch.Config{
	Logger: &opensearchtransport.ColorLogger{Output: os.Stdout},
}

opensearch.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 OPENSEARCH_URL/ELASTICSEARCH_URL environment variable, if set, to configure the addresses; use a comma to separate multiple URLs.

It's an error to set both OPENSEARCH_URL and ELASTICSEARCH_URL.

Example

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

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

log.Print(client.Transport.(*opensearchtransport.Client).URLs())

func (*Client) DiscoverNodes

func (c *Client) DiscoverNodes() error

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

func (*Client) Metrics

func (c *Client) Metrics() (opensearchtransport.Metrics, error)

Metrics returns the client metrics.

func (*Client) Perform

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

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

type Config

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

	Header http.Header // Global HTTP request header.

	Signer signer.Signer

	// 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.
	EnableRetryOnTimeout bool  // Default: false.
	MaxRetries           int   // Default: 3.

	CompressRequestBody bool // 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.

	UseResponseCheckOnly bool

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

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

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

Config represents the client configuration.