elastic

package
v0.35.0 Latest Latest
Warning

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

 Go to latest Published: Jan 27, 2026 License: AGPL-3.0 Imports: 35 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 Connect = sync.OnceValue(func() error {
	if err := config.Init(); err != nil {
		return fmt.Errorf("init config: %w", err)
	}
	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 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(api *elasticsearch.TypedClient, options ...Option[CountRequest]) *count.Count

NewCountRequest creates a new count request with the given options.

func NewDeleteByQueryRequest 

func NewDeleteByQueryRequest(
	api *elasticsearch.TypedClient,
	index string,
	options ...any,
) *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(api *elasticsearch.TypedClient, index, id string, options ...any) *get.Get

NewGetRequest creates a new get doc request that will operate on the given index with the given options.

func NewMGetRequest 

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

NewMGetRequest creates a new mget object with the given options.

func NewMSearchRequest 

func NewMSearchRequest(api *elasticsearch.TypedClient, options ...Option[MsearchRequest]) *msearch.Msearch

NewMSearchRequest creates a new multisearch request with the given options.

func NewSearchRequest 

func NewSearchRequest(options ...Option[SearchRequest]) *search.Search

NewSearchRequest creates a new search request with the given options.

func NewUpdateDocRequest 

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

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

func Search[O any](
	ctx context.Context,
	index string,
	query query.Option,
	count int,
	options ...Option[SearchRequest],
) ([]O, []types.FieldValue, error)

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

func SearchAll 

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

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 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 CountOption 

type CountOption Option[*count.Count]

CountOption is a functional option to apply to a count request.

type CountRequest 

type CountRequest interface {
	RequestCommon[*count.Count]
	RequestWithIndex[*count.Count]
	RequestWithQuery[*count.Count]
}

CountRequest wraps the count API endpoint.

type FieldValue 

type FieldValue struct {
	// contains filtered or unexported fields
}

FieldValue represents a value of a field.

func NewFieldValue 

func NewFieldValue(value any) FieldValue

NewFieldValue converts any value into a FieldValue.

func (FieldValue) FieldValueCaster 

func (v FieldValue) FieldValueCaster() *types.FieldValue

FieldValueCaster is required to allow FieldValue to be used as an Elasticsearch field value.

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 

type MgetRequest interface {
	RequestCommon[*mget.Mget]
	RequestWithIDs[*mget.Mget]
	RequestWithIndex[*mget.Mget]
}

MgetRequest represents an Elasticsearch _mget request.

type MsearchRequest 

type MsearchRequest interface {
	RequestCommon[*msearch.Msearch]
	AddSearch(header types.MultisearchHeader, body types.SearchRequestBody) error
}

MsearchRequest represents an Elasticsearch _msearch request.

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.

func UpdateDocAsUpsert 

func UpdateDocAsUpsert() Option[UpdateDocRequest]

UpdateDocAsUpsert ensures that a doc update will act as an upsert if there is no existing doc.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update#operation-update-body-application-json-doc_as_upsert

func WithAggregations 

func WithAggregations[T any, R RequestWithAggregations[T]](aggs aggregations.Aggs) Option[R]

WithAggregations adds the given aggregation definitions to the search.

func WithCollapseField 

func WithCollapseField(field string) Option[SearchRequest]

func WithFields 

func WithFields[T any, V RequestWithFields[T]](options ...types.FieldAndFormatVariant) Option[V]

WithFields option specifies the request should return the given fields.

func WithIDs 

func WithIDs[T any, V RequestWithIDs[T]](ids ...string) Option[V]

WithIDs option specifies the document IDs to operate on.

func WithIndex 

func WithIndex[T any, V RequestWithIndex[T]](index string) Option[V]

WithIndex option specifies the index for the request to operate on.

func WithQueryOptions 

func WithQueryOptions[T any, R RequestWithQuery[T]](options ...query.Option) Option[R]

WithQueryOptions option applies the given query options to the request.

func WithRefresh 

func WithRefresh(value string) Option[UpdateDocRequest]

WithRefresh sets the refresh value for the request.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update#operation-update-refresh

func WithRequestID 

func WithRequestID[T any, V RequestCommon[T]](id string) Option[V]

WithRequestID option sets the appropriate request ID header to the given value in the request.

func WithRetryOnConflict 

func WithRetryOnConflict(attempts int) Option[UpdateDocRequest]

WithRetryOnConflict sets the number of retries the request will make if a version conflict is detected.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update#operation-update-retry_on_conflict

func WithSearchAfter 

func WithSearchAfter[T any, V RequestWithSearchAfter[T]](values ...types.FieldValueVariant) Option[V]

WithSearchAfter option sets the sort value to fetch the next set of results. It can accept either a []types.FieldValue or a []byte (html-encoded []types.FieldValue).

https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#search-after

func WithSize 

func WithSize[T any, V RequestWithSize[T]](size int) Option[V]

WithSize option defines the number of results returned.

func WithSortOptions 

func WithSortOptions[T any, V RequestWithSort[T]](options ...types.SortCombinationsVariant) Option[V]

WithSortOptions option adds the given sorting options to the search.

func WithTrackTotalHits 

func WithTrackTotalHits(value bool) Option[SearchRequest]

type RequestCommon 

type RequestCommon[T any] interface {
	Header(key string, value string) T
}

RequestCommon represents the common methods for any Elasticsearch request,.

type RequestWithAggregations 

type RequestWithAggregations[T any] interface {
	Aggregations(aggs map[string]types.Aggregations) T
}

RequestWithAggregations represents any Elasticsearch request that can accept aggregations.

type RequestWithFields 

type RequestWithFields[T any] interface {
	Fields(fields ...types.FieldAndFormatVariant) T
}

RequestWithFields represents any Elasticsearch request that can retrieve specific fields.

type RequestWithIDs 

type RequestWithIDs[T any] interface {
	Ids(id ...string) T
}

RequestWithIDs represents any Elasticsearch request that can accept a list of document IDs.

type RequestWithIndex 

type RequestWithIndex[T any] interface {
	Index(index string) T
}

RequestWithIndex represents any Elasticsearch request that can specify an index to operate on.

type RequestWithQuery 

type RequestWithQuery[T any] interface {
	Query(query types.QueryVariant) T
}

RequestWithQuery represents any Elasticsearch request that can accept a query.

type RequestWithSearchAfter 

type RequestWithSearchAfter[T any] interface {
	SearchAfter(values ...types.FieldValueVariant) T
}

RequestWithSearchAfter represents any Elasticsearch request that can accept a "search after" value (i.e., pagination).

type RequestWithSize 

type RequestWithSize[T any] interface {
	Size(size int) T
}

RequestWithSize represents any Elasticsearch request that allows specifying a size (or number of results).

type RequestWithSort 

type RequestWithSort[T any] interface {
	Sort(sort ...types.SortCombinationsVariant) T
}

RequestWithSort represents any Elasticsearch request that can be sorted.

type SearchRequest 

type SearchRequest interface {
	RequestCommon[*search.Search]
	RequestWithIndex[*search.Search]
	RequestWithQuery[*search.Search]
	RequestWithAggregations[*search.Search]
	RequestWithSize[*search.Search]
	RequestWithSearchAfter[*search.Search]
	RequestWithSort[*search.Search]
	RequestWithFields[*search.Search]
	TrackTotalHits(trackhits types.TrackHitsVariant) *search.Search
	Collapse(collapse types.FieldCollapseVariant) *search.Search
}

SearchRequest represents a `_search` API request.

type TrackHits 

type TrackHits bool

func (TrackHits) TrackHitsCaster 

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

type UpdateDocRequest 

type UpdateDocRequest interface {
	RequestCommon[*update.Update]
	DocAsUpsert(docasupsert bool) *update.Update
	Refresh(refresh refresh.Refresh) *update.Update
	RetryOnConflict(retryonconflict int) *update.Update
}

UpdateDocRequest wraps the doc update api endpoint.

Source Files

View all Source files

Directories

Path Synopsis
Package aggregations contains objects and methods for processing Elasticsearch aggregations.
 Package aggregations contains objects and methods for processing Elasticsearch aggregations.
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.