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:
// Clone DefaultTransport to preserve connection pooling, HTTP/2, and timeouts.
tp := http.DefaultTransport.(*http.Transport).Clone()
tp.MaxIdleConnsPerHost = 10
tp.ResponseHeaderTimeout = time.Second
tp.DialContext = (&net.Dialer{Timeout: time.Second}).DialContext
tp.TLSClientConfig.MinVersion = tls.VersionTLS11
cfg := opensearch.Config{
Addresses: []string{
"http://localhost:9200",
"http://localhost:9201",
},
Username: "foo",
Password: "bar",
Transport: tp,
}
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
- Variables
- func ParseError(resp *Response) error
- func ParseVersion(version string) (int64, int64, int64, error)
- func ToPointer[V any](value V) *Vdeprecated
- type CausedBy
- type Client
- func (c *Client) Close() error
- func (c *Client) DiscoverNodes(ctx context.Context) error
- func (c *Client) Do(ctx context.Context, method string, req Request, dataPointer any) (*Response, error)deprecated
- func (c *Client) GetConfig() *Config
- func (c *Client) Metrics() (opensearchtransport.Metrics, error)
- func (c *Client) Perform(req *http.Request) (*http.Response, error)deprecated
- func (c *Client) Stream(req *http.Request) (*http.Response, error)
- type Config
- type Err
- type Error
- type MessageError
- type NoBody
- type ReasonError
- type Request
- type Response
- type RootCause
- type Streamer
- type StringError
- type StructError
Examples ¶
Constants ¶
const ( // SchemeInsecure is the HTTP scheme for insecure connections. SchemeInsecure = "http" // SchemeSecure is the HTTPS scheme for secure connections. SchemeSecure = "https" // DefaultScheme is the default connection scheme. DefaultScheme = SchemeInsecure // DefaultHost is the default OpenSearch host. DefaultHost = "localhost" // DefaultPort is the default OpenSearch port. DefaultPort = 9200 )
const Version = version.Client
Version returns the package version as a string.
Variables ¶
var ( ErrUnexpectedEmptyBody = errors.New("body is unexpectedly empty") ErrReadBody = errors.New("failed to read body") ErrJSONUnmarshalBody = errors.New("failed to json unmarshal body") ErrUnknownOpensearchError = errors.New("opensearch error response could not be parsed as error") )
Error vars
var ( ErrCreateClient = errors.New("cannot create client") ErrCreateTransport = errors.New("error creating transport") ErrParseVersion = errors.New("failed to parse opensearch version") ErrParseURL = errors.New("cannot parse url") ErrPathRequired = path.ErrRequired ErrTransportMissingMethodMetrics = errors.New("transport is missing method Metrics()") ErrTransportMissingMethodDiscoverNodes = errors.New("transport is missing method DiscoverNodes()") ErrTransportMissingMethodStream = errors.New("transport is missing method Stream()") )
Error vars
Functions ¶
func ParseError ¶
ParseError tries to parse the opensearch error into an custom error
func ParseVersion ¶
ParseVersion returns an int64 representation of version.
func ToPointer
deprecated
func ToPointer[V any](value V) *V
ToPointer converts any value to a pointer, mainly used for request parameters
Deprecated: ToPointer will be removed in v5. The helper is intentionally not part of the public API going forward; consumers within this module use the unexported `ptr` defined per-package. Once the module's go directive moves to 1.26, callers can drop any wrapper in favor of the native new(value) form (e.g. new(false)).
Types ¶
type CausedBy ¶ added in v4.6.0
type CausedBy struct {
Type string `json:"type"`
Reason string `json:"reason"`
CausedBy *CausedBy `json:"caused_by,omitempty"`
}
CausedBy represents the optional caused_by of an API error response. Causes can be nested
type Client ¶
type Client struct {
Transport opensearchtransport.Interface
// contains filtered or unexported fields
}
Client represents the OpenSearch client.
func NewClient ¶
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 ¶
package main
import (
"crypto/tls"
"log"
"net"
"net/http"
"time"
"github.com/opensearch-project/opensearch-go/v4"
"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
"github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
)
func main() {
// Clone DefaultTransport to preserve connection pooling, HTTP/2, and timeout defaults,
// then customize as needed.
tp := http.DefaultTransport.(*http.Transport).Clone()
tp.MaxIdleConnsPerHost = 10
tp.ResponseHeaderTimeout = time.Second
tp.DialContext = (&net.Dialer{Timeout: time.Second}).DialContext
tp.TLSClientConfig.MinVersion = tls.VersionTLS12
cfg := opensearchapi.Config{
Client: opensearch.Config{
Addresses: []string{
"http://localhost:9200",
},
Username: "foo",
Password: "bar",
Transport: tp,
},
}
client, _ := opensearchapi.NewClient(cfg)
log.Print(client.Client.Transport.(*opensearchtransport.Client).URLs())
}
Output:
Example (Logger) ¶
package main
import (
"os"
"github.com/opensearch-project/opensearch-go/v4"
"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
"github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
)
func main() {
// import "github.com/opensearch-project/opensearch-go/opensearchtransport"
// Use one of the bundled loggers:
//
// * opensearchtransport.TextLogger
// * opensearchtransport.ColorLogger
// * opensearchtransport.CurlLogger
// * opensearchtransport.JSONLogger
cfg := opensearchapi.Config{
Client: opensearch.Config{
Logger: &opensearchtransport.ColorLogger{Output: os.Stdout},
},
}
opensearchapi.NewClient(cfg)
}
Output:
func NewDefaultClient ¶
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 ¶
package main
import (
"context"
"log"
"github.com/opensearch-project/opensearch-go/v4/opensearchapi"
"github.com/opensearch-project/opensearch-go/v4/opensearchtransport"
)
func init() {
log.SetFlags(0)
}
func main() {
ctx := context.Background()
client, err := opensearchapi.NewDefaultClient()
if err != nil {
log.Fatalf("Error creating the client: %s\n", err)
}
_, err = client.Info(ctx, nil)
if err != nil {
log.Fatalf("Error getting the response: %s\n", err)
}
log.Print(client.Client.Transport.(*opensearchtransport.Client).URLs())
}
Output:
func (*Client) Close ¶ added in v4.7.0
Close releases the client's background resources by closing the underlying transport if it implements io.Closer -- the built-in *opensearchtransport.Client does, canceling pollers and closing idle connections -- and is a no-op for a custom Interface that does not. Safe on a zero value and idempotent.
func (*Client) DiscoverNodes ¶
DiscoverNodes reloads the client connections by fetching information from the cluster.
func (*Client) Do
deprecated
func (c *Client) Do(ctx context.Context, method string, req Request, dataPointer any) (*Response, error)
Do gets and performs the request. It also tries to parse the response into the dataPointer.
On error, Do may return a non-nil *Response alongside a non-nil error. This happens when the transport received a response but a subsequent failure occurred (a body-read failure during buffering, or an unrelated transport error such as context cancellation during retry backoff). Callers that need to distinguish a hard transport failure should check resp == nil rather than err != nil, and may inspect the returned *Response in the error case. A nil *Response always signals that no usable response was produced.
Deprecated: Use Do instead, which enforces that dataPointer is a pointer at compile time. Client.Do accepts any, so passing a non-pointer compiles but fails at runtime during JSON unmarshaling. The method remains fully functional and will not be removed; this annotation exists to steer callers toward the safer generic alternative.
func (*Client) Metrics ¶
func (c *Client) Metrics() (opensearchtransport.Metrics, error)
Metrics returns the client metrics.
func (*Client) Perform
deprecated
Perform delegates to Transport to execute a request and return a response.
Deprecated: Perform follows the v4 buffered-response contract and will be removed in v5 alongside opensearchtransport.Client.Perform. Use Client.Stream when you need raw byte forwarding (the caller owns the body) or the typed Do helpers when you want a decoded Go value.
func (*Client) Stream ¶ added in v4.7.0
Stream delegates to Transport.Stream when available, returning the raw http.Response from the underlying http.RoundTripper. The caller owns the response body and must close it. Use Stream for proxy and streaming use cases where bytes are forwarded incrementally; use Do when you want a decoded Go value.
Stream returns ErrTransportMissingMethodStream when the configured transport does not implement Streamer.
type Config ¶
type Config struct {
Addresses []string // A list of nodes to use.
Username string // Username for HTTP Basic Authentication.
// Password for HTTP Basic Authentication.
Password string // #nosec G117
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
// InsecureSkipVerify disables TLS certificate verification.
// When true, the transport's TLS config is set to skip verification,
// cloning the existing transport (or http.DefaultTransport) to preserve
// connection pooling, HTTP/2, and other defaults.
InsecureSkipVerify bool
RetryOnStatus []int // List of status codes for retry. Default: 502, 503, 504.
DisableRetry bool // Default: false.
EnableRetryOnTimeout bool // Default: false.
MaxRetries int // Default: 3.
// RequestTimeout sets a per-attempt timeout for each HTTP round-trip.
// When set, a context deadline is applied to each individual request attempt
// (including each retry). This bounds the maximum time a single request can
// block, preventing indefinite hangs on stalled connections.
// A timeout also marks the node, so the next request to it carries
// Request.Close and net/http retires the pooled connection: no new requests
// are put on it, the streams already there finish, and it is closed when the
// last one does. Otherwise an HTTP/2 retry would be multiplexed onto the
// same stalled connection and never dial. A caller's own expiring context
// deadline does not mark anything: that reports the caller gave up, not that
// the connection is bad.
// 0 = no per-attempt timeout (default), >0 = explicit timeout.
RequestTimeout time.Duration
CompressRequestBody bool // Default: false.
// DiscoverNodesOnStart triggers an asynchronous discovery cycle as soon
// as NewClient returns. nil (the default) means "auto": if Router is
// also nil and OPENSEARCH_GO_ROUTER is truthy, this is treated as true
// so the client starts populating topology before the first request.
// Any explicitly set value (true or false) is respected as-is and
// suppresses the env-var inheritance. When Router is set programmatically
// the env var is ignored entirely; the caller is responsible for
// triggering discovery if desired.
DiscoverNodesOnStart *bool
DiscoverNodesInterval time.Duration // Discover nodes periodically. Default: disabled.
// VerifyDeadAfter is the duration a dead connection can be blindly
// resurrected for use as a zombie connection when no other healthy
// connections are available. A connection proven reachable is a zombie
// candidate until it has been dead longer than this window; after that the
// discovery loop clears the mark, so the node must health-check clean again
// before it can be used. Seeds are always available and never expire this
// way. 0 = use the default window, <0 = disabled (a viable connection stays
// a zombie candidate indefinitely), >0 = explicit window. Overridable by
// OPENSEARCH_GO_VERIFY_DEAD_AFTER (bool true = default, false = disabled,
// else a duration string).
VerifyDeadAfter time.Duration
// Health check configuration
HealthCheckTimeout time.Duration // Timeout for health check requests. Default: 3s.
HealthCheckMaxRetries int // Max retries for health checks. Default: 3. Set to -1 to disable health checks.
HealthCheckJitter float64 // Jitter factor for health check timing (0.0-1.0). Default: 0.2.
// Resurrection timeout configuration for dead connection recovery.
// These control how quickly the client retries dead nodes and how aggressively
// it reconnects during cluster outages or rolling restarts.
ResurrectTimeoutInitial time.Duration // Initial backoff for dead connections. Default: 5s.
ResurrectTimeoutMax time.Duration // Max backoff before jitter. Default: 30s.
ResurrectTimeoutFactorCutoff int // Exponential backoff cutoff factor. Default: 5.
MinimumResurrectTimeout time.Duration // Absolute minimum retry interval. Default: 500ms.
JitterScale float64 // Jitter multiplier (0.0-1.0). Default: 0.5.
// Health check rate limiting to prevent overwhelming recovering servers.
// During outages, all clients reconnect simultaneously, creating TLS handshake
// pressure on recovering servers. Health check rates are auto-derived from the
// server's core count (discovered via /_nodes/_local/http,os per node).
//
// MaxRetryClusterHealth controls how often to retry the cluster health probe
// (/_cluster/health?local=true) on nodes where it was previously unavailable due to
// missing cluster:monitor/health permission (401 Unauthorized or 403 Forbidden).
// Jitter from HealthCheckJitter is applied to the interval to prevent thundering herd.
// 0 = use default (4h), <0 = disable cluster health probing entirely.
// >0 = explicit retry interval.
// Default: 4h
MaxRetryClusterHealth time.Duration
// HealthCheckRequestModifier is called on every health check HTTP request before it is sent.
// This allows injecting custom authentication headers or other modifications without
// replacing the entire health check function.
// Default: nil (no modification)
HealthCheckRequestModifier func(*http.Request)
EnableMetrics bool // Enable the metrics collection.
EnableDebugLogger bool // Enable the debug logging.
// ActiveListCap sets the maximum number of connections in the ready list's active partition per pool.
// When discovery adds connections that would exceed this cap, overflow connections
// are moved to a standby list for later rotation. This caps the number of active
// connections per client, preventing fan-out overload in large clusters.
//
// 0 = auto-derive from server capacity model:
// cap = floor(serverMaxNewConnsPerSec * ResurrectTimeoutInitial / clientsPerServer)
// With defaults (8 cores): floor(32 * 5 / 8) = 20
// >0 = explicit cap.
// <0 = disabled (all connections go to active, standby disabled).
// Default: 0 (auto-derive)
ActiveListCap int
// StandbyRotationInterval sets how often a standby connection is rotated
// into the ready list (and an active connection is evicted to standby).
// 0 = use DiscoverNodesInterval, >0 = explicit interval, <0 = disabled.
// Default: 0 (use DiscoverNodesInterval)
StandbyRotationInterval time.Duration
// StandbyRotationCount sets how many standby connections are rotated per
// discovery cycle. 0 = use default (1), >0 = explicit count.
// Default: 1
StandbyRotationCount int
// StandbyPromotionChecks sets the number of consecutive successful health
// checks required before a standby connection can be promoted to live.
// 0 = use default (3), >0 = explicit count.
// Default: 3
StandbyPromotionChecks int
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.
Router opensearchtransport.Router // Optional router for request-aware routing.
Observer opensearchtransport.ConnectionObserver // Optional observer for connection lifecycle events.
// ShardCostConfig overrides shard cost multipliers for connection scoring.
// See [opensearchtransport.Config.ShardCostConfig] for format details.
ShardCostConfig string
// Context for background operations (node discovery, health checks, stats polling).
// If nil, context.Background() is used. The transport derives a child context from
// this, so canceling the parent automatically stops all background goroutines.
// For example, passing t.Context() in tests ensures cleanup when the test ends.
//nolint:containedctx // Config struct is short-lived, context extracted during New()
Context context.Context
// Optional constructor function for a custom ConnectionPool. Default: nil.
ConnectionPoolFunc func([]*opensearchtransport.Connection, opensearchtransport.Selector) opensearchtransport.ConnectionPool
}
Config represents the client configuration.
type Err ¶
type Err struct {
RootCause []RootCause `json:"root_cause"`
Type string `json:"type"`
Reason string `json:"reason"`
CausedBy *CausedBy `json:"caused_by,omitempty"`
Index string `json:"index,omitempty"`
IndexUUID string `json:"index_uuid,omitempty"`
}
Err represents the error of an API error response
type Error ¶
type Error struct {
Err string `json:"error"`
}
Error represents an Opensearch error with only an error field
type MessageError ¶
MessageError represents an Opensearch error with a message field
type NoBody ¶ added in v4.7.0
type NoBody struct{}
NoBody is a marker type for Do calls that expect no response body. Pass (*NoBody)(nil) to skip JSON unmarshaling while retaining compile-time pointer enforcement.
type ReasonError ¶
ReasonError represents an Opensearch error with a reason field
type Request ¶
Request represents a request the client can execute. Implementations build the URL path and body from structured fields; the HTTP method is provided by the caller (the client method that knows the operation's semantics).
type Response ¶
type Response struct {
StatusCode int
Header http.Header
Body io.ReadCloser
// contains filtered or unexported fields
}
Response represents the API response.
func Do ¶ added in v4.7.0
func Do[T any](ctx context.Context, c *Client, method string, req Request, dataPointer *T) (*Response, error)
Do is a generic version of Client.Do that enforces dataPointer as a pointer at compile time. It delegates to Client.Do after the type system has guaranteed *T.
A nil dataPointer is forwarded as untyped nil so that Client.Do skips unmarshalling. This prevents a typed nil (e.g. (*MyResp)(nil)) from being widened into a non-nil any interface that would reach json.Unmarshal.
func NewResponse ¶ added in v4.7.0
NewResponse creates a Response with the given status, body, and headers.
func (*Response) HijackBody ¶ added in v4.7.0
HijackBody returns the buffered response bytes and transfers ownership to the caller, clearing r.rawBody so the Response no longer references the buffer. After Hijack the caller may mutate or retain the slice indefinitely; subsequent RawBody calls return nil. Use this when the buffer outlives the Response (logging, background processing, test fixtures).
func (*Response) RawBody ¶ added in v4.7.0
RawBody returns the buffered response bytes for inspection or comparison testing.
The returned slice aliases memory owned by Response and may be backed by pooled storage in future implementations. Callers must NOT mutate the slice and must NOT retain it past the lifetime of the request handling: copy with bytes.Clone if either is needed, or use HijackBody to transfer ownership to the caller.
Populated only for non-error responses where Client.Do successfully decoded the body into a typed dataPointer. Returns nil when:
- The response was streamed without buffering (no dataPointer).
- The response was an error (4xx/5xx); read Body directly for error-response bodies, or use ParseError to extract a typed error.
type RootCause ¶
type RootCause struct {
Type string `json:"type"`
Reason string `json:"reason"`
Index string `json:"index,omitempty"`
IndexUUID string `json:"index_uuid,omitempty"`
}
RootCause represents the root_cause of an API error response
type Streamer ¶ added in v4.7.0
Streamer is implemented by transports that expose an unbuffered Stream path: opensearchtransport.Client satisfies it. Custom opensearchtransport.Interface implementations may opt in by adding a Stream method with the same signature; Client.Stream reports ErrTransportMissingMethodStream when the underlying transport does not.
type StringError ¶
StringError represnets an Opensearch error where error is a string
type StructError ¶
StructError represents an Opensearch error with a detailed error struct
func (*StructError) UnmarshalJSON ¶
func (e *StructError) UnmarshalJSON(b []byte) error
UnmarshalJSON is a custom unmarshal function for StructError returning custom errors in special cases
Directories
¶
| Path | Synopsis |
|---|---|
|
SPDX-License-Identifier: Apache-2.0
|
SPDX-License-Identifier: Apache-2.0 |
|
Package errmask defines the bitfield used by opensearchapi to mask (ignore) specific categories of partial-failure errors.
|
Package errmask defines the bitfield used by opensearchapi to mask (ignore) specific categories of partial-failure errors. |
|
internal
|
|
|
build
Package build constructs http.Request values for the OpenSearch client without the overhead of http.NewRequest (which calls url.Parse on every invocation).
|
Package build constructs http.Request values for the OpenSearch client without the overhead of http.NewRequest (which calls url.Parse on every invocation). |
|
envvars
Package envvars holds the canonical names of OPENSEARCH_GO_* environment variables consumed by both the opensearch and opensearchtransport packages.
|
Package envvars holds the canonical names of OPENSEARCH_GO_* environment variables consumed by both the opensearch and opensearchtransport packages. |
|
path
Package path provides generated typed path builder structs for all OpenSearch API operations.
|
Package path provides generated typed path builder structs for all OpenSearch API operations. |
|
test/readiness
Package readiness implements a layered readiness FSM for integration tests.
|
Package readiness implements a layered readiness FSM for integration tests. |
|
SPDX-License-Identifier: Apache-2.0
|
SPDX-License-Identifier: Apache-2.0 |
|
testutil
Package testutil provides test helpers that depend on opensearchapi and opensearch types.
|
Package testutil provides test helpers that depend on opensearchapi and opensearch types. |
|
Package opensearchtransport provides the transport layer for the OpenSearch client.
|
Package opensearchtransport provides the transport layer for the OpenSearch client. |
|
testutil
SPDX-License-Identifier: Apache-2.0
|
SPDX-License-Identifier: Apache-2.0 |
|
testutil/mockhttp
Package mockhttp provides HTTP mocking utilities for testing OpenSearch Go client functionality.
|
Package mockhttp provides HTTP mocking utilities for testing OpenSearch Go client functionality. |
|
Package opensearchutil provides helper utilities to the Go client for OpenSearch.
|
Package opensearchutil provides helper utilities to the Go client for OpenSearch. |
|
shardhash
Package shardhash implements OpenSearch's shard routing hash algorithm.
|
Package shardhash implements OpenSearch's shard routing hash algorithm. |
|
plugins
|
|
|
aws
Package aws provides AWS request signing for OpenSearch using AWS SDK v2.
|
Package aws provides AWS request signing for OpenSearch using AWS SDK v2. |