esquery/es.go

116 lines
3.8 KiB
Go
Raw Normal View History

// Package esquery provides a non-obtrusive, idiomatic and easy-to-use query
// and aggregation builder for the official Go client
// (https://github.com/elastic/go-elasticsearch) for the ElasticSearch
// database (https://www.elastic.co/products/elasticsearch).
//
// esquery alleviates the need to use extremely nested maps
// (map[string]interface{}) and serializing queries to JSON manually. It also
// helps eliminating common mistakes such as misspelling query types, as
// everything is statically typed.
//
// Using `esquery` can make your code much easier to write, read and maintain,
// and significantly reduce the amount of code you write.
//
//
//
// Usage
//
//
//
// esquery provides a method chaining-style API for building and executing
// queries and aggregations. It does not wrap the official Go client nor does it
// require you to change your existing code in order to integrate the library.
// Queries can be directly built with `esquery`, and executed by passing an
// `*elasticsearch.Client` instance (with optional search parameters). Results
// are returned as-is from the official client (e.g. `*esapi.Response` objects).
//
// Getting started is extremely simple:
//
// package main
//
// import (
// "context"
// "log"
//
2022-09-22 12:04:03 +00:00
// "github.com/aquasecurity/esquery/v8"
// "github.com/elastic/go-elasticsearch/v8"
// )
//
// func main() {
// // connect to an ElasticSearch instance
// es, err := elasticsearch.NewDefaultClient()
// if err != nil {
// log.Fatalf("Failed creating client: %s", err)
// }
//
// // run a boolean search query
// qRes, err := esquery.Query(
// esquery.
// Bool().
// Must(esquery.Term("title", "Go and Stuff")).
// Filter(esquery.Term("tag", "tech")),
// ).Run(
// es,
// es.Search.WithContext(context.TODO()),
// es.Search.WithIndex("test"),
// )
// if err != nil {
// log.Fatalf("Failed searching for stuff: %s", err)
// }
//
// defer qRes.Body.Close()
//
// // run an aggregation
// aRes, err := esquery.Aggregate(
// esquery.Avg("average_score", "score"),
// esquery.Max("max_score", "score"),
// ).Run(
// es,
// es.Search.WithContext(context.TODO()),
// es.Search.WithIndex("test"),
// )
// if err != nil {
// log.Fatalf("Failed searching for stuff: %s", err)
// }
//
// defer aRes.Body.Close()
//
// // ...
// }
//
//
//
// Notes
//
//
//
//* esquery currently supports version 7 of the ElasticSearch Go client.
//* The library cannot currently generate "short queries". For example,
// whereas ElasticSearch can accept this:
//
// { "query": { "term": { "user": "Kimchy" } } }
//
// The library will always generate this:
//
// { "query": { "term": { "user": { "value": "Kimchy" } } } }
//
// This is also true for queries such as "bool", where fields like "must" can
// either receive one query object, or an array of query objects. `esquery` will
// generate an array even if there's only one query object.
package esquery
// Mappable is the interface implemented by the various query and aggregation
// types provided by the package. It allows the library to easily transform the
// different queries to "generic" maps that can be easily encoded to JSON.
type Mappable interface {
Map() map[string]interface{}
}
// Aggregation is an interface that each aggregation type must implement. It
// is simply an extension of the Mappable interface to include a Named function,
// which returns the name of the aggregation.
type Aggregation interface {
Mappable
Name() string
}