effdsl

package module

v2.6.0 Latest Latest Go to latest Published: Jul 16, 2025 License: MIT Imports: 3 Imported by: 24

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/sdqri/effdsl

Links

Open Source Insights

README ¶

effdsl

GitHub Release GitHub License

This module provides a simple and functional way to build Elasticsearch queries in Go.

🚀 Key Features

Type-safe query construction: 🛡️ Avoids error-prone maps and raw string literals by using intuitive function calls, enhancing type safety, auto-completion, and compile-time validation.
Procedural query creation: ✨ Designed for straightforward and refined query building, particularly useful when queries need to be generated programmatically.
Comprehensive query support: 📚 Covers most compound, full-text, and term-level queries, with easy extension for additional types.

For more information, detailed guides, and examples, please read the documentation.

Getting started

Getting effdsl

With Go module support, simply add the following import

import "github.com/sdqri/effdsl/v2"

to your code, and then go [build|run|test] will automatically fetch the necessary dependencies.

Otherwise, run the following Go command to install the effdsl package:

$ go get -u github.com/sdqri/effdsl/v2

How to use

Start with effdsl.Define(), and use types and documentations to find suitable options.

🔍 Examples:

Traditional Way:

Here’s a simple match query in the traditional way using raw strings in Go:

import (
    es "github.com/elastic/go-elasticsearch/v8"
)

query := `{
  "query": {
    "match": {
      "message": {
        "query": "Hello World"
      }
    }
  }
}`

res, err := es.Search(
  es.Search.WithBody(strings.NewReader(query)),
)

Using effdsl:

And here’s the same query using effdsl:

import (
    es "github.com/elastic/go-elasticsearch/v8"
    
    "github.com/sdqri/effdsl/v2"
    mq "github.com/sdqri/effdsl/v2/queries/matchquery"
)

query, err := effdsl.Define(
    effdsl.WithQuery(
        mq.MatchQuery("message", "Hello World"),
    ),
)

res, err := es.Search(
  es.Search.WithBody(strings.NewReader(query)),
)

For more examples and details on query parameters, visit the documentation.

🤝 Contribution

Contributions are welcome! Whether it's fixing a bug 🐛, adding a new feature 🌟, or improving the documentation 📚, your help is appreciated. Please check out the CONTRIBUTING.md guide to get started.

📜 License

This project is licensed under the MIT License. For more details, see the License file. 📄 ( In short: You can use, modify, and distribute this software freely as long as you include the original copyright notice and license. The software is provided "as-is" without warranties or guarantees.)

Documentation ¶

Index ¶

Constants ¶

View Source

const (
	FORMAT_EPOCH_MILLIS                            = "epoch_millis"
	FORMAT_EPOCH_SECOND                            = "epoch_second"
	FORMAT_DATE_OPTIONAL_TIME                      = "date_optional_time"
	FORMAT_STRICT_DATE_OPTIONAL_TIME               = "strict_date_optional_time"
	FORMAT_STRICT_DATE_OPTIONAL_TIME_NANOS         = "strict_date_optional_time_nanos"
	FORMAT_BASIC_DATE                              = "basic_date"
	FORMAT_BASIC_DATE_TIME                         = "basic_date_time"
	FORMAT_BASIC_DATE_TIME_NO_MILLIS               = "basic_date_time_no_millis"
	FORMAT_BASIC_ORDINAL_DATE                      = "basic_ordinal_date"
	FORMAT_BASIC_ORDINAL_DATE_TIME                 = "basic_ordinal_date_time"
	FORMAT_BASIC_ORDINAL_DATE_TIME_NO_MILLIS       = "basic_ordinal_date_time_no_millis"
	FORMAT_BASIC_TIME                              = "basic_time"
	FORMAT_BASIC_TIME_NO_MILLIS                    = "basic_time_no_millis"
	FORMAT_BASIC_T_TIME                            = "basic_t_time"
	FORMAT_BASIC_T_TIME_NO_MILLIS                  = "basic_t_time_no_millis"
	FORMAT_BASIC_WEEK_DATE                         = "basic_week_date"
	FORMAT_STRICT_BASIC_WEEK_DATE                  = "strict_basic_week_date"
	FORMAT_BASIC_WEEK_DATE_TIME                    = "basic_week_date_time"
	FORMAT_STRICT_BASIC_WEEK_DATE_TIME             = "strict_basic_week_date_time"
	FORMAT_BASIC_WEEK_DATE_TIME_NO_MILLIS          = "basic_week_date_time_no_millis"
	FORMAT_STRICT_BASIC_WEEK_DATE_TIME_NO_MILLIS   = "strict_basic_week_date_time_no_millis"
	FORMAT_DATE                                    = "date"
	FORMAT_STRICT_DATE                             = "strict_date"
	FORMAT_DATE_HOUR                               = "date_hour"
	FORMAT_STRICT_DATE_HOUR                        = "strict_date_hour"
	FORMAT_DATE_HOUR_MINUTE                        = "date_hour_minute"
	FORMAT_STRICT_DATE_HOUR_MINUTE                 = "strict_date_hour_minute"
	FORMAT_DATE_HOUR_MINUTE_SECOND                 = "date_hour_minute_second"
	FORMAT_STRICT_DATE_HOUR_MINUTE_SECOND          = "strict_date_hour_minute_second"
	FORMAT_DATE_HOUR_MINUTE_SECOND_FRACTION        = "date_hour_minute_second_fraction"
	FORMAT_STRICT_DATE_HOUR_MINUTE_SECOND_FRACTION = "strict_date_hour_minute_second_fraction"
	FORMAT_DATE_HOUR_MINUTE_SECOND_MILLIS          = "date_hour_minute_second_millis"
	FORMAT_STRICT_DATE_HOUR_MINUTE_SECOND_MILLIS   = "strict_date_hour_minute_second_millis"
	FORMAT_DATE_TIME                               = "date_time"
	FORMAT_STRICT_DATE_TIME                        = "strict_date_time"
	FORMAT_DATE_TIME_NO_MILLIS                     = "date_time_no_millis"
	FORMAT_STRICT_DATE_TIME_NO_MILLIS              = "strict_date_time_no_millis"
	FORMAT_HOUR                                    = "hour"
	FORMAT_STRICT_HOUR                             = "strict_hour"
	FORMAT_HOUR_MINUTE                             = "hour_minute"
	FORMAT_STRICT_HOUR_MINUTE                      = "strict_hour_minute"
	FORMAT_HOUR_MINUTE_SECOND                      = "hour_minute_second"
	FORMAT_STRICT_HOUR_MINUTE_SECOND               = "strict_hour_minute_second"
	FORMAT_HOUR_MINUTE_SECOND_FRACTION             = "hour_minute_second_fraction"
	FORMAT_STRICT_HOUR_MINUTE_SECOND_FRACTION      = "strict_hour_minute_second_fraction"
	FORMAT_HOUR_MINUTE_SECOND_MILLIS               = "hour_minute_second_millis"
	FORMAT_STRICT_HOUR_MINUTE_SECOND_MILLIS        = "strict_hour_minute_second_millis"
	FORMAT_ORDINAL_DATE                            = "ordinal_date"
	FORMAT_STRICT_ORDINAL_DATE                     = "strict_ordinal_date"
	FORMAT_ORDINAL_DATE_TIME                       = "ordinal_date_time"
	FORMAT_STRICT_ORDINAL_DATE_TIME                = "strict_ordinal_date_time"
	FORMAT_ORDINAL_DATE_TIME_NO_MILLIS             = "ordinal_date_time_no_millis"
	FORMAT_STRICT_ORDINAL_DATE_TIME_NO_MILLIS      = "strict_ordinal_date_time_no_millis"
	FORMAT_TIME                                    = "time"
	FORMAT_STRICT_TIME                             = "strict_time"
	FORMAT_TIME_NO_MILLIS                          = "time_no_millis"
	FORMAT_STRICT_TIME_NO_MILLIS                   = "strict_time_no_millis"
	FORMAT_T_TIME                                  = "t_time"
	FORMAT_STRICT_T_TIME                           = "strict_t_time"
	FORMAT_T_TIME_NO_MILLIS                        = "t_time_no_millis"
	FORMAT_STRICT_T_TIME_NO_MILLIS                 = "strict_t_time_no_millis"
	FORMAT_WEEK_DATE                               = "week_date"
	FORMAT_STRICT_WEEK_DATE                        = "strict_week_date"
	FORMAT_WEEK_DATE_TIME                          = "week_date_time"
	FORMAT_STRICT_WEEK_DATE_TIME                   = "strict_week_date_time"
	FORMAT_WEEK_DATE_TIME_NO_MILLIS                = "week_date_time_no_millis"
	FORMAT_STRICT_WEEK_DATE_TIME_NO_MILLIS         = "strict_week_date_time_no_millis"
	FORMAT_WEEKYEAR                                = "weekyear"
	FORMAT_STRICT_WEEKYEAR                         = "strict_weekyear"
	FORMAT_WEEKYEAR_WEEK                           = "weekyear_week"
	FORMAT_STRICT_WEEKYEAR_WEEK                    = "strict_weekyear_week"
	FORMAT_WEEKYEAR_WEEK_DAY                       = "weekyear_week_day"
	FORMAT_STRICT_WEEKYEAR_WEEK_DAY                = "strict_weekyear_week_day"
	FORMAT_YEAR                                    = "year"
	FORMAT_STRICT_YEAR                             = "strict_year"
	FORMAT_YEAR_MONTH                              = "year_month"
	FORMAT_STRICT_YEAR_MONTH                       = "strict_year_month"
	FORMAT_YEAR_MONTH_DAY                          = "year_month_day"
	FORMAT_STRICT_YEAR_MONTH_DAY                   = "strict_year_month_day"
)

View Source

const (
	SORT_MISSING_FIRST = "_first"
	SORT_MISSING_LAST  = "_last"
)

View Source

const MaxNestedDepth = 5

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type BodyOption ¶

type BodyOption func(*SearchBody) error

func WithCollapse ¶ added in v2.3.0

func WithCollapse(field string) BodyOption

You can use the collapse parameter to collapse search results based on field values. The collapsing is done by selecting only the top sorted document per collapse key. [Collapse search results]: https://www.elastic.co/guide/en/elasticsearch/reference/current/collapse-search-results.html

func WithCollpse deprecated

func WithCollpse(field string) BodyOption

Deprecated: use WithCollapse

func WithPIT ¶

func WithPIT(id string, keepAlive string) BodyOption

A search request by default executes against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between search_after requests, then the results of those requests might not be consistent as changes happening between searches are only visible to the more recent point in time. [Point in time]: https://www.elastic.co/guide/en/elasticsearch/reference/current/point-in-time-api.html

func WithPaginate ¶

func WithPaginate(from uint64, size uint64) BodyOption

By default, searches return the top 10 matching hits. To page through a larger set of results, you can use the search API's from and size parameters. The from parameter defines the number of hits to skip, defaulting to 0. The size parameter is the maximum number of hits to return. Together, these two parameters define a page of results. [Paginate search results]: https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#paginate-search-results

func WithQuery ¶

func WithQuery(queryResult QueryResult) BodyOption

func WithSearchAfter ¶

func WithSearchAfter(sortValues ...any) BodyOption

By default, you cannot use from and size to page through more than 10,000 hits. This limit is a safeguard set by the index.max_result_window index setting. If you need to page through more than 10,000 hits, use the search_after parameter instead. You can use the search_after parameter to retrieve the next page of hits using a set of sort values from the previous page. [Search after]: https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#search-after

func WithSort ¶

func WithSort(sortClauseResults ...SortClauseResult) BodyOption

Allows you to add one or more sorts on specific fields. Each sort can be reversed as well. The sort is defined on a per field level, with special field name for _score to sort by score, and _doc to sort by index order. [Sort search results]: https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#sort-search-results

func WithSourceFilter ¶

func WithSourceFilter(opts ...SourceFitlerOption) BodyOption

You can use the _source parameter to select what fields of the source are returned. This is called source filtering. The following search API request sets the _source request body parameter to false. The document source is not included in the response. [Source filtering]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#source-filtering

func WithSuggest ¶

func WithSuggest(suggestResults ...SuggestResult) BodyOption

WithSuggest - allows you to use suggest

func WithTrackScores ¶ added in v2.4.0

func WithTrackScores() BodyOption

If scores are not computed. By setting track_scores to true, scores will still be computed and tracked. [Track scores]: https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#script-based-sortingfunc WithTrackScores() BodyOption {

type CollapseS ¶

type CollapseS struct {
	Field string `json:"field"`
}

func Collapse ¶

func Collapse(field string) CollapseS

func (CollapseS) MarshalJSON ¶

func (sc CollapseS) MarshalJSON() ([]byte, error)

type M ¶

type M map[string]any

func (M) MarshalJSON ¶

func (m M) MarshalJSON() ([]byte, error)

type MockedQuery ¶

type MockedQuery M

func (MockedQuery) MarshalJSON ¶

func (q MockedQuery) MarshalJSON() ([]byte, error)

func (MockedQuery) QueryInfo ¶

func (q MockedQuery) QueryInfo() string

type Nested ¶ added in v2.4.0

type Nested struct {
	Path     string      `json:"path"`
	Filter   QueryResult `json:"filter,omitempty"`
	MaxChild *int        `json:"max_children,omitempty"`
	Nested   *Nested     `json:"nested,omitempty"`
}

func NewNested ¶ added in v2.4.0

func NewNested(path string, filter QueryResult, maxChild *int, nested *Nested) *Nested

func (Nested) ToNestedSort ¶ added in v2.4.0

func (ns Nested) ToNestedSort(currentDepth int) (*NestedSort, error)

type NestedSort ¶ added in v2.4.0

type NestedSort struct {
	Path     string      `json:"path"`
	Filter   any         `json:"filter,omitempty"`
	MaxChild *int        `json:"max_children,omitempty"`
	Nested   *NestedSort `json:"nested,omitempty"`
}

type NumericType ¶ added in v2.4.0

type NumericType string

const (
	SORT_NUMERIC_TYPE_DOUBLE     NumericType = "double"
	SORT_NUMERIC_TYPE_LONG       NumericType = "long"
	SORT_NUMERIC_TYPE_DATE       NumericType = "date"
	SORT_NUMERIC_TYPE_DATE_NANOS NumericType = "date_nanos"
)

type PITS ¶

type PITS struct {
	ID        string `json:"id,omitempty"`
	KeepAlive string `json:"keep_alive,omitempty"`
}

func PIT ¶

func PIT(id string, keepAlive string) PITS

func (PITS) MarshalJSON ¶

func (pit PITS) MarshalJSON() ([]byte, error)

type Query ¶

type Query interface {
	QueryInfo() string
	json.Marshaler
}

type QueryResult ¶

type QueryResult struct {
	Ok  Query
	Err error
}

func MockQuery ¶

func MockQuery(m M) QueryResult

type SearchAfterResult ¶

type SearchAfterResult struct {
	Ok  SearchAfterType
	Err error
}

func SearchAfter ¶

func SearchAfter(sortValues ...any) SearchAfterResult

type SearchAfterS ¶

type SearchAfterS []any

func (SearchAfterS) MarshalJSON ¶

func (sa SearchAfterS) MarshalJSON() ([]byte, error)

func (SearchAfterS) SearchAfterInfo ¶

func (sa SearchAfterS) SearchAfterInfo() string

type SearchAfterType ¶

type SearchAfterType interface {
	SearchAfterInfo() string
	json.Marshaler
}

type SearchBody ¶

type SearchBody struct {
	Source      json.Marshaler         `json:"_source,omitempty"`
	From        *uint64                `json:"from,omitempty"`
	Size        *uint64                `json:"size,omitempty"`
	Query       Query                  `json:"query,omitempty"`
	Sort        []SortClauseType       `json:"sort,omitempty"`
	TrackScore  bool                   `json:"track_scores,omitempty"`
	SearchAfter SearchAfterType        `json:"search_after,omitempty"`
	Collapse    json.Marshaler         `json:"collapse,omitempty"`
	PIT         json.Marshaler         `json:"pit,omitempty"`
	Suggest     map[string]SuggestType `json:"suggest,omitempty"`
}

func Define ¶

func Define(opts ...BodyOption) (body *SearchBody, err error)

type SortClauseParameter ¶ added in v2.4.0

type SortClauseParameter func(params *sortClauseParameters) error

func WithFormat ¶ added in v2.4.0

func WithFormat(format string) SortClauseParameter

func WithMissing ¶ added in v2.4.0

func WithMissing(missing string) SortClauseParameter

func WithNested ¶ added in v2.4.0

func WithNested(nested *Nested) SortClauseParameter

func WithNumericType ¶ added in v2.4.0

func WithNumericType(numericType NumericType) SortClauseParameter

func WithSortMode ¶ added in v2.4.0

func WithSortMode(mode SortMode) SortClauseParameter

func WithUnmappedType ¶ added in v2.4.0

func WithUnmappedType(unmappedType string) SortClauseParameter

type SortClauseResult ¶

type SortClauseResult struct {
	Ok  SortClauseType
	Err error
}

func SortClause ¶

func SortClause(field string, order SortOrder, opts ...SortClauseParameter) SortClauseResult

type SortClauseS ¶

type SortClauseS struct {
	Field        string       `json:"-"`
	Order        SortOrder    `json:"order,omitempty"`
	Format       *string      `json:"format,omitempty"`
	Missing      *string      `json:"missing,omitempty"`
	Mode         *SortMode    `json:"mode,omitempty"`
	NumericType  *NumericType `json:"numeric_type,omitempty"`
	Nested       *NestedSort  `json:"nested,omitempty"`
	UnmappedType *string      `json:"unmapped_type,omitempty"`
}

func (SortClauseS) MarshalJSON ¶

func (sq SortClauseS) MarshalJSON() ([]byte, error)

func (SortClauseS) SortClauseInfo ¶

func (sq SortClauseS) SortClauseInfo() string

type SortClauseType ¶

type SortClauseType interface {
	SortClauseInfo() string
	json.Marshaler
}

type SortMode ¶ added in v2.4.0

type SortMode string

const (
	SORT_MODE_MIN    SortMode = "min"
	SORT_MODE_MAX    SortMode = "max"
	SORT_MODE_SUM    SortMode = "sum"
	SORT_MODE_AVG    SortMode = "avg"
	SORT_MODE_MEDIAN SortMode = "median"
)

type SortOrder ¶

type SortOrder string

const (
	SORT_DEFAULT SortOrder = "default"
	SORT_ASC     SortOrder = "asc"
	SORT_DESC    SortOrder = "desc"
)

type SourceFilterS ¶

type SourceFilterS struct {
	Includes []string `json:"includes,omitempty"`
	Excludes []string `json:"excludes,omitempty"`
}

func SourceFilter ¶

func SourceFilter(opts ...SourceFitlerOption) SourceFilterS

func (SourceFilterS) MarshalJSON ¶

func (sf SourceFilterS) MarshalJSON() ([]byte, error)

type SourceFitlerOption ¶

type SourceFitlerOption func(*SourceFilterS)

func WithExcludes ¶

func WithExcludes(fields ...string) SourceFitlerOption

func WithIncludes ¶

func WithIncludes(fields ...string) SourceFitlerOption

type SuggestMode ¶

type SuggestMode string

SuggestMode - The suggest mode controls what suggestions are included or controls for what suggest text terms, suggestions should be suggested.

const (
	// SuggestModeMissing - Only provide suggestions for suggest text terms that are not in the index (default).
	SuggestModeMissing SuggestMode = "score"
	// SuggestModePopular - Only suggest suggestions that occur in more docs than the original suggest text term.
	SuggestModePopular SuggestMode = "popular"
	// Suggest any matching suggestions based on terms in the suggest text.
	SuggestModeAlways SuggestMode = "always"
)

type SuggestResult ¶

type SuggestResult struct {
	Ok  SuggestType
	Err error
}

func Suggesters deprecated

func Suggesters(globalText string, s Suggester) SuggestResult

Deprecated: Use NewSuggest() or BuildSuggest() instead.

Suggests similar looking terms based on a provided text by using a suggester. Suggesters: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#search-suggesters

type SuggestS ¶

type SuggestS struct {
	GlobalText string `json:"text,omitempty"` // To avoid repetition of the suggest text, it is possible to define a global text.
	Suggester
}

func (SuggestS) MarshalJSON ¶

func (s SuggestS) MarshalJSON() ([]byte, error)

func (SuggestS) SuggestName ¶ added in v2.5.0

func (s SuggestS) SuggestName() string

type SuggestSort ¶

type SuggestSort string

SuggestSort - Defines how suggestions should be sorted per suggest text term.

const (
	// SortScore - Sort by score first, then document frequency and then the term itself.
	SortScore SuggestSort = "score"
	// FrequencyScore - Sort by document frequency first, then similarity score and then the term itself.
	FrequencyScore SuggestSort = "frequency"
)

type SuggestType ¶ added in v2.5.0

type SuggestType interface {
	SuggestName() string
	json.Marshaler
}

type Suggester ¶

type Suggester interface {
	json.Marshaler
	// contains filtered or unexported methods
}

func TermSuggester ¶

func TermSuggester(terms ...TermSuggest) Suggester

TermSuggester - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#term-suggester

type TermS ¶

type TermS struct {
	Field       string      `json:"field"`              // The field to fetch the candidate suggestions from. This is a required option that either needs to be set globally or per suggestion.
	Analyzer    string      `json:"analyzer,omitempty"` // The analyzer to analyse the suggest text with. Defaults to the search analyzer of the suggest field.
	Size        int         `json:"size,omitempty"`     // The maximum corrections to be returned per suggest text token.
	Sort        SuggestSort `json:"sort,omitempty"`     // Defines how suggestions should be sorted per suggest text term. Two possible values: score, frequency
	SuggestMode SuggestMode `json:"suggest_mode,omitempty"`
}

type TermSuggest ¶

type TermSuggest interface {
	GetName() string
}

func Term ¶

func Term(name, text, field string, opts ...TermSuggestOption) TermSuggest

type TermSuggestOption ¶

type TermSuggestOption func(*TermS)

func WithTermSuggestAnalyzer ¶

func WithTermSuggestAnalyzer(analyzer string) TermSuggestOption

func WithTermSuggestMode ¶

func WithTermSuggestMode(mode SuggestMode) TermSuggestOption

func WithTermSuggestSize ¶

func WithTermSuggestSize(size int) TermSuggestOption

func WithTermSuggestSort ¶

func WithTermSuggestSort(sort SuggestSort) TermSuggestOption

type TermSuggesterS ¶

type TermSuggesterS struct {
	Name string `json:"-"`              //
	Text string `json:"text,omitempty"` // The suggest text. The suggest text is a required option that needs to be set globally or per suggestion.
	Term TermS  `json:"term"`           // (Required) The term suggester suggests terms based on edit distance. The provided suggest text is analyzed before terms are suggested. The suggested terms are provided per analyzed suggest text token. The term suggester doesn’t take the query into account that is part of request.
}

func (TermSuggesterS) GetName ¶

func (t TermSuggesterS) GetName() string

type TermsSuggest ¶

type TermsSuggest []TermSuggest

TermSuggester - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#term-suggester

func (TermsSuggest) MarshalJSON ¶

func (ts TermsSuggest) MarshalJSON() ([]byte, error)

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
queries
boolquery
boostingquery
constantscore
dismaxquery
existsquery
fuzzyquery
idsquery
matchallquery
matchboolprefix
matchnonequery
matchphraseprefix
matchphrasequery
matchquery
multimatchquery
nestedquery
prefixquery
querystring
rangequery
regexpquery
simplequerystring
termquery
termsquery
termssetquery
wildcardquery
suggesters
completionsuggester
phrasesuggester
termsuggester
utils