elastic

package
v0.239.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 29, 2026 License: AGPL-3.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// ReqIDHeader is the value that will be used to assign a unique ID to an Elasticsearch API request (that can be
	// used to associate the API request with a web server request).
	ReqIDHeader = "X-Opaque-Id"
)

Variables

View Source 
var (
	ErrInvalidAggType = errors.New("invalid aggregation type")
	ErrAggNotFound    = errors.New("aggregation not found")
)
View Source 
var Connect = sync.OnceValue(func() error {
	if err := loadConfigOnce(); err != nil {
		return fmt.Errorf("load config environment: %w", err)
	}

	var options []elasticsearch.Option
	options = append(options,

		elasticsearch.WithLogger(&Logger{EnableResponseBody: false, EnableRequestBody: false}),

		elasticsearch.WithRetry(5, 429, 502, 503, 504),
		elasticsearch.WithTransportOptions(
			elastictransport.WithRetryBackoff(func(attempt int) time.Duration {

				return time.Duration(1<<uint(attempt)) * 100 * time.Millisecond
			}),
		),
	)

	switch {
	case cfg.CloudID != "":
		options = append(options,
			elasticsearch.WithCloudID(cfg.CloudID),
			elasticsearch.WithAPIKey(cfg.APIKey))
	case len(cfg.URLs) > 0:
		options = append(options, elasticsearch.WithAddresses(cfg.URLs...))
		if cfg.CAFile != "" {
			cert, err := os.ReadFile(cfg.CAFile)
			if err != nil {
				return fmt.Errorf("read CA cert: %w", err)
			}
			options = append(options, elasticsearch.WithCACert(cert))

			switch {
			case cfg.APIKey != "":
				options = append(options, elasticsearch.WithAPIKey(cfg.APIKey))
			case cfg.Username != "" && cfg.Password != "":
				options = append(options,
					elasticsearch.WithBasicAuth(cfg.Username, cfg.Password),
				)
			}
		}
	default:
		return errors.New("invalid config")
	}

	esclient, err := elasticsearch.NewTyped(options...)
	if err != nil {
		return fmt.Errorf("create typed client: %w", err)
	}

	api = API{TypedClient: esclient}
	initialized.Store(true)

	slog.Debug("Elasticsearch connection created.")

	return nil
})

Connect sets up a connection to Elasticsearch.

View Source 
var ErrNotFound = errors.New("not found")

Functions

func AsAPIError added in v0.237.0 

func AsAPIError(err error) *models.APIError

func Count 

func Count(ctx context.Context, index string, queries ...query.Option) (int64, error)

Count will return the number of docs matching the given queries in the given index.

func CreateDoc 

func CreateDoc[T ~string, O any](
	ctx context.Context,
	index string,
	id T,
	doc O,
	options ...Option[*create.Create],
) error

CreateDoc will create the given document, with given id, in the given index.

func CreateIndexIfNotExists added in v0.157.0 

func CreateIndexIfNotExists(ctx context.Context, prefix string) (bool, error)

func DecodePagination 

func DecodePagination[T ~string](pagination *T) ([]types.FieldValueVariant, error)

DecodePagination will take a Pagination object, HTML-unescape the string then unmarshal it back into sort values.

func DeleteDoc 

func DeleteDoc[T ~string](ctx context.Context, index string, id T, options ...Option[*delete.Delete]) error

DeleteDoc deletes the document with the given id from the given index.

func DeleteDocs 

func DeleteDocs(ctx context.Context, index string, queries ...query.Option) error

DeleteDocs performs a delete by query request on the given index to delete documents matching the given queries.

func EncodePagination 

func EncodePagination[T ~string](sortValues []types.FieldValue) (T, error)

EncodePagination will take sort values returned from a query, marshal them to JSON, then HTML-escape the string into a Pagination object, which is safe for use in API query parameters.

func ExtractAggregation added in v0.121.0 

func ExtractAggregation[T any](aggs map[string]types.Aggregate, name string) (T, bool, error)

ExtractAggregation recursively searches for an aggregation by name. It searches top-level Aggregations and then digs into bucket sub-aggregations.

func ExtractBuckets added in v0.121.0 

func ExtractBuckets[T BucketTypes](container any) ([]T, error)

ExtractBuckets extracts the bucket object from the aggregation as a slice of the given type. If the aggregation cannot be extracted to the type, a non-nil error is returned that will contain details.

func ExtractBucketsAsMap added in v0.207.0 

func ExtractBucketsAsMap[T BucketTypes](container any) (map[string]T, error)

ExtractBucketsAsMap extracts the bucket object from the aggregation as a map[string]T of given type. If the aggregation cannot be extracted to the type, a non-nil error is returned that will contain details.

func GenerateIndexName added in v0.157.0 

func GenerateIndexName(prefix string) string

func GetDoc 

func GetDoc[T ~string, O any](ctx context.Context, index string, id T) (O, error)

GetDoc retrieves the doc with the given id from the given index. A non-nil error is returned on a failure.

func GetDocs 

func GetDocs[T ~string, O any](
	ctx context.Context,
	index string,
	ids ...T,
) ([]O, error)

GetDocs performs an `_mget` request to fetch the documents from the given index with the given ids. A non-nil error is returned on a failure.

func NewCountRequest 

func NewCountRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	options ...Option[*count.Count],
) *count.Count

NewCountRequest creates a new count request with the given options.

func NewDeleteByQueryRequest 

func NewDeleteByQueryRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index string,
	options ...Option[*deletebyquery.DeleteByQuery],
) *deletebyquery.DeleteByQuery

NewDeleteByQueryRequest creates a new delete by query request that will operate on the given index with the given options.

func NewGetRequest 

func NewGetRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index string,
	id string,
	options ...Option[*get.Get],
) *get.Get

NewGetRequest creates a new get object with the given options.

func NewMGetRequest 

func NewMGetRequest(ctx context.Context, api *elasticsearch.TypedClient, options ...Option[*mget.Mget]) *mget.Mget

NewMGetRequest creates a new mget object with the given options.

func NewSearchRequest 

func NewSearchRequest(ctx context.Context, options ...Option[*search.Search]) *search.Search

NewSearchRequest creates a new search request with the given options.

func NewUpdateDocRequest 

func NewUpdateDocRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index, id string,
	doc any,
	options ...Option[*update.Update],
) *update.Update

NewUpdateDocRequest creates a new doc update request with the given options.

func SearchAll 

func SearchAll[O any](
	ctx context.Context,
	index string,
	query query.Option,
	paginationSize int,
	options ...Option[*search.Search],
) ([]O, error)

SearchAll performs a paginated search request to retrieve *all* documents matching the given query. Unlike Search, it does not stop when the request hits count is reached.

func Shutdown added in v0.190.3 

func Shutdown(ctx context.Context) error

Shutdown gracefully closes the Elasticsearch connection (if it has been initialized/created).

func UpdateDoc 

func UpdateDoc[T ~string](
	ctx context.Context,
	index string,
	id T,
	updates any,
	options ...Option[*update.Update],
) error

UpdateDoc performs a partial doc update on the document with the given id in the given index. A non-nil error is returned on a failure.

func UpdateIndexAlias added in v0.157.0 

func UpdateIndexAlias(ctx context.Context, alias string, index string) error

UpdateIndexAlias performs a swap of an alias to the given index. It adds the given index to the alias, sets it as the write destination, then removes any existing aliased indicies so the index remains as the only aliased one.

https://www.elastic.co/docs/manage-data/data-store/aliases

Types

type API 

type API struct {
	*elasticsearch.TypedClient
}

API is an object that provides access to the Elasticsearch API.

func GetAPI added in v0.190.3 

func GetAPI() (*API, error)

GetAPI will set up a new connection to Elasticsearch. It loads the config for the connection from the environment.

type Aggs added in v0.121.0 

type Aggs map[string]types.Aggregations

type BucketTypes added in v0.121.0 

type BucketTypes interface {
	types.StringTermsBucket | types.StringRareTermsBucket | types.FiltersBucket
}

BucketTypes is a type constraint for all aggregation bucket types.

type Logger 

type Logger struct {
	EnableRequestBody  bool
	EnableResponseBody bool
}

Logger is a custom elastictransport.Logger.

func (*Logger) LogRoundTrip 

func (l *Logger) LogRoundTrip(
	req *http.Request,
	res *http.Response,
	err error,
	_ time.Time,
	dur time.Duration,
) error

LogRoundTrip should not modify the request or response, except for consuming and closing the body. Implementations have to check for nil values in request and response.

func (*Logger) RequestBodyEnabled 

func (l *Logger) RequestBodyEnabled() bool

RequestBodyEnabled makes the client pass a copy of request body to the logger.

func (*Logger) ResponseBodyEnabled 

func (l *Logger) ResponseBodyEnabled() bool

ResponseBodyEnabled makes the client pass a copy of response body to the logger.

type Option 

type Option[T any] func(T) T

Option is a functional option for a request of type T.

func WithAggregation added in v0.237.0 

func WithAggregation[T supportsAggregations[T]](key string, value types.AggregationsVariant) Option[T]

WithAggregation option adds an aggregation to perform with the request.

func WithAggregations 

func WithAggregations[T supportsAggregations[T]](aggregations map[string]types.Aggregations) Option[T]

WithAggregations option sets the aggregations to perform with the request.

func WithCollapse added in v0.237.0 

func WithCollapse[T supportsCollapse[T]](field string) Option[T]

WithCollapse option sets that duplicate results for the given field should be collapsed down to the first result.

func WithDocAsUpsert added in v0.120.0 

func WithDocAsUpsert[T supportsDocAsUpsert[T]](value bool) Option[T]

WithDocAsUpsert option specifies that the doc should be added if it does not already exist. Normally, the request would not add a document if none already exist.

func WithDocIDs added in v0.237.0 

func WithDocIDs[T supportsIDs[T]](ids ...string) Option[T]

WithDocIDs option sets the doc IDs to retrieve.

func WithDocSorting added in v0.120.0 

func WithDocSorting[T supportsSort[T]]() Option[T]

WithDocSorting option is a convenience option to sort the results by doc id. This option is useful when fetching all results or deep pagination where sort order is irrelevant.

func WithFrom added in v0.188.0 

func WithFrom[T supportsFrom[T]](from int) Option[T]

From option sets the pagination point within the results.

func WithHeader added in v0.120.0 

func WithHeader[T supportsHeader[T]](key, value string) Option[T]

WithHeader option sets a HTTP header on the request.

func WithIndex 

func WithIndex[T supportsIndex[T]](index string) Option[T]

WithIndex option sets the index the request will operate on.

func WithPrimaryTerm added in v0.237.0 

func WithPrimaryTerm[T supportsPrimaryTerm[T]](term int64) Option[T]

WithPrimaryTerm option to specifies the primary term of the doc on which to operate.

func WithQuery added in v0.237.0 

func WithQuery[T supportsQuery[T]](options ...query.Option) Option[T]

WithQuery option sets a query as a part of the request.

func WithRefresh 

func WithRefresh[T supportsRefresh[T]](value refresh.Refresh) Option[T]

WithRefresh option sets the refresh value on the request.

func WithRetriever added in v0.177.0 

func WithRetriever[T supportsRetriever[T]](options ...retriever.Option) Option[T]

WithRetriever option sets a retriever as part of the request.

func WithRetryOnConflict 

func WithRetryOnConflict[T supportsRetryOnConflict[T]](retries int) Option[T]

WithRetryOnConflict option sets the number of times the request will be retried if there is a conflict.

func WithSearchAfter 

func WithSearchAfter[T supportsSearchAfter[T]](sortresults ...types.FieldValueVariant) Option[T]

WithSearchAfter option sets the point after which results should be fetched.

func WithSeqNo added in v0.237.0 

func WithSeqNo[T supportsSeqNo[T]](seqno int64) Option[T]

WithSeqNo option specifies the sequence no of the doc on which to operate.

func WithSeqNoPrimaryTerm added in v0.231.0 

func WithSeqNoPrimaryTerm[T supportsSeqNoPrimaryTerm[T]](value bool) Option[T]

WithSeqNoPrimaryTerm option specifies that the results should return the sequence no and primary term of each hit.

func WithSize 

func WithSize[T supportsSize[T]](size int) Option[T]

WithSize option sets the number of results that will be returned.

func WithSort added in v0.120.0 

func WithSort[T supportsSort[T]](sorts ...types.SortCombinationsVariant) Option[T]

WithSort option sets how the results will be sorted.

func WithTrackHits added in v0.237.0 

func WithTrackHits[T supportsTrackHits[T]](value TrackHits) Option[T]

WithTrackHits option sets whether total hits should be tracked.

type SearchResponse added in v0.121.0 

type SearchResponse[O any] struct {
	*search.Response

	Results    []O
	Pagination []types.FieldValue
}

SearchResponse represents the results of a search request. In addition to exposing the raw API response, the object contains marshaled results and pagination values. 

func Search[O any](
	ctx context.Context,
	index string,
	options ...Option[*search.Search],
) (*SearchResponse[O], error)

Search performs a _search request to find documents matching the given query.

type TrackHits 

type TrackHits bool

TrackHits is a boolean indicating whether to track total hits.

func (TrackHits) TrackHitsCaster 

func (t TrackHits) TrackHitsCaster() *types.TrackHits

Source Files

View all Source files

Directories

Path Synopsis
Package ilm contains wrappers that help with creating ILM policies.
 Package ilm contains wrappers that help with creating ILM policies.
Package query contains methods for building Elasticsearch queries.
 Package query contains methods for building Elasticsearch queries.
Package templates contains wrappers for helping with creating index and component templates.
 Package templates contains wrappers for helping with creating index and component templates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.