elastic

package
v0.146.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2026 License: AGPL-3.0 Imports: 33 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 {
	clientConfig, err := loadConfigOnce()
	if err != nil {
		return fmt.Errorf("load config environment: %w", err)
	}

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

	api = API{TypedClient: esclient}

	slog.Info("Elasticsearch connection created.")

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

Functions

func BulkAdd 

func BulkAdd[T ~string, O Object[T]](
	ctx context.Context,
	index string,
	objects ...O,
) (map[T]*bulk.OperationResponse, error)

BulkAdd will create documents for the given list of objects. Responses are returned as a map of doc id to response. If the request itself fails, a non-nil error is returned.

func BulkUpdate 

func BulkUpdate[T ~string, O Object[T]](
	ctx context.Context,
	index string,
	objects ...O,
) (map[T]*bulk.OperationResponse, error)

BulkUpdate will update documents for the given list of objects. Responses are returned as a map of doc id to response. If the request itself fails, a non-nil error is returned.

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) error

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

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) 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 the given type. If the aggregation cannot be extracted to the type, a non-nil error is returned that will contain details.

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 SearchAll 

func SearchAll[O any](
	ctx context.Context,
	index string,
	query query.Option,
	paginationSize int,
	options ...func(*SearchRequest),
) ([]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 UpdateDoc 

func UpdateDoc[T ~string](
	ctx context.Context,
	index string,
	id T,
	updates any,
	options ...func(*UpdateRequest),
) 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 WithAggregations 

func WithAggregations[T HasAggregations](aggs map[string]types.Aggregations) func(T)

WithAggregations option defines aggregations to add to the request.

func WithCollapseField 

func WithCollapseField[T HasCollapse](field string) func(T)

WithCollapseField option specifies the field on which to collapse multiple results.

func WithDocAsUpsert added in v0.120.0 

func WithDocAsUpsert[T HasDocAsUpsert](value bool) func(T)

WithDocAsUpsert option defines whether to perform an upsert operation if the document does not exist.

func WithDocSorting added in v0.120.0 

func WithDocSorting[T HasSort]() func(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 WithFields 

func WithFields[T HasFields](fields ...types.FieldAndFormatVariant) func(T)

WithFields option specifies the fields to return in each result.

func WithHeader added in v0.120.0 

func WithHeader[T HasHeader](key, value string) func(T)

WithHeader option sets a header on the request.

func WithIDs 

func WithIDs[T HasIDs](ids ...string) func(T)

WithIDs option specifies the document IDs to operate on for this request.

func WithIndex 

func WithIndex[T HasIndex](index string) func(T)

WithIndex option sets the index the request will operate on.

func WithQueryOptions 

func WithQueryOptions[T HasQuery](options ...query.Option) func(T)

WithQueryOptions option defines the query options that will be applied to the request.

func WithRefresh 

func WithRefresh[T HasRefresh](value any) func(T)

WithRefresh option sets the refresh option. Note that while any value is accepted, only valid values of true, false or the string "waitfor" will have any effect.

func WithRetryOnConflict 

func WithRetryOnConflict[T HasRetryOnConflict](retries int) func(T)

WithRetryOnConflict option sets the number of retries to perform on a conflict.

func WithSearchAfter 

func WithSearchAfter[T HasSearchAfter](values ...types.FieldValueVariant) func(T)

WithSearchAfter option specifies the search after values for paginating through results.

func WithSize 

func WithSize[T HasSize](size int) func(T)

WithSize option specifies the number of results to return. In most cases, if not specified, a default of 10 results is returned.

func WithSort added in v0.120.0 

func WithSort[T HasSort](sort ...types.SortCombinationsVariant) func(T)

WithSort option specifies how the results will be sorted.

func WithTrackTotalHits 

func WithTrackTotalHits[T HasTotalHitsTracking](value bool) func(T)

WithTrackTotalHits option specifies whether to track total hits for the request.

Types

type API 

type API struct {
	*elasticsearch.TypedClient
}

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

func NewConnection 

func NewConnection() (*API, error)

NewConnection 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
}

BucketTypes is a type constraint for all aggregation bucket types.

type Config 

type Config struct {
	Development ConfigDevelopment
	Production  ConfigProduction
}

Config is the elastic configuration. It varies depending on the environment.

type ConfigDevelopment 

type ConfigDevelopment struct {
	CAFile   string   `koanf:"cafile"   validate:"required,file"`
	Username string   `koanf:"username" validate:"required"`
	Password string   `koanf:"password" validate:"required"`
	URLs     []string `koanf:"urls"     validate:"required,dive,url"`
}

ConfigDevelopment are the config options for a development environment.

type ConfigProduction 

type ConfigProduction struct {
	CloudID string `koanf:"cloudid" validate:"required"`
	APIKey  string `koanf:"apikey"  validate:"required"`
}

ConfigProduction are the config options for a production environment.

type CountRequest 

type CountRequest struct {
	*count.Count
}

func NewCountRequest 

func NewCountRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	options ...func(*CountRequest),
) *CountRequest

NewCountRequest creates a new count request with the given options.

func (*CountRequest) SetHeader added in v0.120.0 

func (r *CountRequest) SetHeader(key, value string)

func (*CountRequest) SetIndex added in v0.120.0 

func (r *CountRequest) SetIndex(index string)

func (*CountRequest) SetQueryOptions added in v0.120.0 

func (r *CountRequest) SetQueryOptions(options ...query.Option)

type DeleteByQueryRequest added in v0.120.0 

type DeleteByQueryRequest struct {
	*deletebyquery.DeleteByQuery
}

func NewDeleteByQueryRequest 

func NewDeleteByQueryRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index string,
	options ...func(*DeleteByQueryRequest),
) *DeleteByQueryRequest

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

func (*DeleteByQueryRequest) SetHeader added in v0.120.0 

func (r *DeleteByQueryRequest) SetHeader(key, value string)

func (*DeleteByQueryRequest) SetQueryOptions added in v0.120.0 

func (r *DeleteByQueryRequest) SetQueryOptions(options ...query.Option)

type FieldValue 

type FieldValue[T types.FieldValue] struct {
	// contains filtered or unexported fields
}

func NewFieldValue 

func NewFieldValue[T any](value T) *FieldValue[T]

func (*FieldValue[T]) FieldValueCaster 

func (v *FieldValue[T]) FieldValueCaster() *types.FieldValue

func (*FieldValue[T]) MarshalJSON added in v0.121.0 

func (v *FieldValue[T]) MarshalJSON() ([]byte, error)

type GetRequest added in v0.120.0 

type GetRequest struct {
	*get.Get
}

func NewGetRequest 

func NewGetRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index string,
	id string,
	options ...func(*GetRequest),
) *GetRequest

NewGetRequest creates a new get object with the given options.

func (*GetRequest) SetHeader added in v0.120.0 

func (r *GetRequest) SetHeader(key, value string)

type HasAggregations added in v0.120.0 

type HasAggregations interface {
	*SearchRequest

	SetAggregations(aggs map[string]types.Aggregations)
}

HasAggregations represents a request that can specify aggregations.

type HasCollapse added in v0.120.0 

type HasCollapse interface {
	*SearchRequest

	SetCollapseOn(field *types.FieldCollapse)
}

HasCollapse represents a request that can collapse its results on a single field in each result.

type HasDocAsUpsert added in v0.120.0 

type HasDocAsUpsert interface {
	*UpdateRequest

	SetDocAsUpsert(value bool)
}

HasDocAsUpsert represents a request that can perform an upsert operation on a document.

type HasFields added in v0.120.0 

type HasFields interface {
	*SearchRequest

	SetFields(fields ...types.FieldAndFormatVariant)
}

HasFields represents a request that can filter its results by fields.

type HasHeader added in v0.120.0 

type HasHeader interface {
	*SearchRequest | *CountRequest | *GetRequest | *MGetRequest | *DeleteByQueryRequest | *UpdateRequest

	SetHeader(key string, value string)
}

HasHeader represents a request that can set a header value.

type HasIDs added in v0.120.0 

type HasIDs interface {
	*MGetRequest

	SetIDs(ids ...string)
}

HasIDs represents a request that can operate against specific document IDs.

type HasIndex added in v0.120.0 

type HasIndex interface {
	*SearchRequest | *CountRequest | *MGetRequest | *DeleteByQueryRequest

	SetIndex(index string)
}

HasIndex represents a request that can specify an index to operate on.

type HasQuery added in v0.120.0 

type HasQuery interface {
	*SearchRequest | *CountRequest | *DeleteByQueryRequest

	SetQueryOptions(options ...query.Option)
}

HasQuery represents a request that can specify a query.

type HasRefresh added in v0.120.0 

type HasRefresh interface {
	*UpdateRequest

	SetRefresh(refresh refresh.Refresh)
}

HasRefresh represents a request that can set a refresh state for affected shards after completion.

type HasRetryOnConflict added in v0.120.0 

type HasRetryOnConflict interface {
	*UpdateRequest

	SetRetryOnConflict(retries int)
}

HasRetryOnConflict represents a request that can retry its operation on conflicts.

type HasSearchAfter added in v0.120.0 

type HasSearchAfter interface {
	*SearchRequest

	SetSearchAfter(values ...types.FieldValueVariant)
}

HasSearchAfter represents a request that can specify search after data.

type HasSize added in v0.120.0 

type HasSize interface {
	*SearchRequest

	SetSize(size int)
}

HasSize represents a request that can define a size for number of results returned.

type HasSort added in v0.120.0 

type HasSort interface {
	*SearchRequest

	SetSort(sort ...types.SortCombinationsVariant)
}

HasSort represents a request that can sort its results.

type HasTotalHitsTracking added in v0.120.0 

type HasTotalHitsTracking interface {
	*SearchRequest

	SetTrackTotalHits(value bool)
}

HasTotalHitsTracking represents a request that can track total hits.

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 MGetRequest added in v0.120.0 

type MGetRequest struct {
	*mget.Mget
}

func NewMGetRequest 

func NewMGetRequest(ctx context.Context, api *elasticsearch.TypedClient, options ...func(*MGetRequest)) *MGetRequest

NewMGetRequest creates a new mget object with the given options.

func (*MGetRequest) SetHeader added in v0.120.0 

func (r *MGetRequest) SetHeader(key, value string)

func (*MGetRequest) SetIDs added in v0.120.0 

func (r *MGetRequest) SetIDs(ids ...string)

func (*MGetRequest) SetIndex added in v0.120.0 

func (r *MGetRequest) SetIndex(index string)

type Object 

type Object[T ~string] interface {
	GetID() T
}

Object represents any kind of object that has an ID. Effectively the object can be indexed in Elasticsearch.

type Option 

type Option[T any] func(T)

Option is a generic type for functional options.

type SearchRequest 

type SearchRequest struct {
	*search.Search
}

SearchRequest represents an elastic search request.

func NewSearchRequest 

func NewSearchRequest(ctx context.Context, options ...func(*SearchRequest)) *SearchRequest

NewSearchRequest creates a new search request with the given options.

func (*SearchRequest) SetAggregations added in v0.120.0 

func (r *SearchRequest) SetAggregations(aggs map[string]types.Aggregations)

func (*SearchRequest) SetCollapseOn added in v0.120.0 

func (r *SearchRequest) SetCollapseOn(collapse *types.FieldCollapse)

func (*SearchRequest) SetFields added in v0.120.0 

func (r *SearchRequest) SetFields(fields ...types.FieldAndFormatVariant)

func (*SearchRequest) SetHeader added in v0.120.0 

func (r *SearchRequest) SetHeader(key, value string)

func (*SearchRequest) SetIndex added in v0.120.0 

func (r *SearchRequest) SetIndex(index string)

func (*SearchRequest) SetQueryOptions added in v0.120.0 

func (r *SearchRequest) SetQueryOptions(options ...query.Option)

func (*SearchRequest) SetSearchAfter added in v0.120.0 

func (r *SearchRequest) SetSearchAfter(values ...types.FieldValueVariant)

func (*SearchRequest) SetSize added in v0.120.0 

func (r *SearchRequest) SetSize(size int)

func (*SearchRequest) SetSort added in v0.120.0 

func (r *SearchRequest) SetSort(sort ...types.SortCombinationsVariant)

func (*SearchRequest) SetTrackTotalHits added in v0.120.0 

func (r *SearchRequest) SetTrackTotalHits(value bool)

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,
	query query.Option,
	options ...func(*SearchRequest),
) (*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

type UpdateRequest added in v0.120.0 

type UpdateRequest struct {
	*update.Update
}

func NewUpdateDocRequest 

func NewUpdateDocRequest(
	ctx context.Context,
	api *elasticsearch.TypedClient,
	index, id string,
	doc any,
	options ...func(*UpdateRequest),
) *UpdateRequest

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

func (*UpdateRequest) SetDocAsUpsert added in v0.120.0 

func (r *UpdateRequest) SetDocAsUpsert(value bool)

func (*UpdateRequest) SetHeader added in v0.120.0 

func (r *UpdateRequest) SetHeader(key, value string)

func (*UpdateRequest) SetRefresh added in v0.120.0 

func (r *UpdateRequest) SetRefresh(value refresh.Refresh)

func (*UpdateRequest) SetRetryOnConflict added in v0.120.0 

func (r *UpdateRequest) SetRetryOnConflict(retries int)

Source Files

View all Source files

Directories

Path Synopsis
Package bulk contains methods and structures for handling Elasticsearch bulk operations.
 Package bulk contains methods and structures for handling Elasticsearch bulk operations.
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.