marshall explain output only in debug mode

README.md

@@ -4,6 +4,48 @@
 
 Elasticsearch CLI
 
+## Introduction
+
+This is a handy cli tool which interfaces to an elasticsearch cluster
+(or two of them if you're using cross cluster replication). It is a
+work-in-progress project yet, things might change occasionally. Expect
+a stable release once we reach major version 1.0.0.
+
+Features:
+
+- Configuration of cluster credentials using environment vars or
+  config file. Multiple clusters can be configured. `esctl cluster ls`
+  shows which one is reachable.
+- Shell completion support (bash, zsh and fish). Put this into your
+  rc: `source <(esctl completion bash)`.
+- Cluster settings can be viewed and modified.
+- Search: you can search indices using full text or by fields, select
+  logical condition (OR, AND), use PIT, limit datetime (ES date math
+  can be used), etc. It is however not yet possible to create
+  recursive searches like: `(cond1 AND cond2) OR (cond3 OR cond4)`.
+- Cross cluster replication (ccr): view, pause, resume, delete
+  replication. You can also manage follower configuration.
+- Index management: manage aliases, create, modify, delete indices,
+  display field mappings etc.
+- Node management: only list nodes yet.
+- Shard management: only list shards yet.
+- Snapshot management: only list snapshots yet.
+- Role management: only list roles yet. There's also a `role diff`
+  subcommand, which is for internal use. It can be used to verify if
+  role defs in a CSV match the deployed roles.
+- Repl: this is an interactive REPL (read eval print loop) towards the
+  elasticsearch API. You can run API calls on the current selected
+  cluster w/o the hassle to specify the whole url, credentials etc. It
+  has line editing and history support. If `jq` is installed output
+  JSON will be syntax highlighted.
+- Doc support. You can put, delete and show docs for an index. Very
+  handy if you want to play with it. Just create a new index:
+  `esctl index create foo` and then insert docs into it for search
+  experiments:
+  ```console
+  esctl doc add -i foo '{"title":"curry in a hurry", "message":"australian thai"}'
+  ```
+
 ## Usage
 
 Command tree:
@@ -34,6 +76,7 @@ Command tree:
      delete
      show
  help
+ help-jsonpath
  index
      alias
          create
@@ -52,6 +95,7 @@ Command tree:
      show
  repl
  role
+     diff
      list
      show
  search
@@ -91,10 +135,6 @@ can omit `-c ...`.
 If you want to  work on a specific cluster, specify  its name with the
 global `-C` option.
 
-## Introduction
-
-FIXME
-
 ## Installation
 
 The tool does not have any dependencies.  Just download the binary for

TODO.md

@@ -1,33 +1,13 @@
 - [Go client docs](https://www.elastic.co/docs/reference/elasticsearch/clients/go/typed-api)
 - [ES API docs](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get)
 
-- Fix index names custom completion
-  https://github.com/urfave/cli/issues/2332
-  https://github.com/urfave/cli/issues/2333
-
 - index show: add more details, see screenshots
 
 - add shard explain, aka:
   get /_cluster/allocation/explain {"index":"yourindex", "primary": true, "shard":0}
 
 
-- add validate:
+- add datastream support:
+  https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-stream
   
-> GET /mock/_validate/query?rewrite=true {"from":0,"query":{"bool":{"must":[{"match_all":{}}]}},"size":20,"sort":[{"name":{"order":"desc"}}]}
-{
-  "valid": false
-}
-
-- add explain to search (maybe option -e)
-
-> GET /mock/_explain/1780043878 {"query":{"bool":{"must":[{"match_all":{}}]}}}
-{
-  "_index": "mock",
-  "_id": "1780043878",
-  "matched": true,
-  "explanation": {
-    "value": 1.0,
-    "description": "*:*",
-    "details": []
-  }
-}
+  also exclude data stream backing indices from index ls

cmd/doc.go

@@ -89,19 +89,9 @@ func DocShow(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Path,
 				Aliases:     []string{"p"},
 			},
-			&cli.BoolFlag{
-				Name:        "help-jsonpath",
-				Usage:       "show jsonPath help",
-				Destination: &conf.Subhelp,
-				Aliases:     []string{"H"},
-			},
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if args.Len() != 1 {
@@ -161,10 +151,6 @@ func DocDelete(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if args.Len() == 0 && !conf.All {

cmd/root.go

@@ -98,6 +98,7 @@ func Main() int {
 			Version(conf),
 			Debug(conf),
 			Roles(conf),
+			HelpJsonPath(conf),
 		},
 
 		Before: func(ctx context.Context, cmd *cli.Command) (context.Context, error) {
@@ -119,6 +120,45 @@ func Main() int {
 	return Finish(cmd.Run(context.Background(), os.Args))
 }
 
+func HelpJsonPath(conf *cfg.Config) *cli.Command {
+	msg := `jsonPath usage:
+
+name.last          >> "Anderson"
+age                >> 37
+children           >> ["Sara","Alex","Jack"]
+children.#         >> 3
+children.1         >> "Alex"
+child*.2           >> "Jack"
+c?ildren.0         >> "Sara"
+fav\.movie         >> "Deer Hunter"
+friends.#.first    >> ["Dale","Roger","Jane"]
+friends.1.last     >> "Craig"
+
+You can also  query an array for  the first match by  using #(...), or
+find all matches  with #(...)#. Queries support the ==,  !=, <, <=, >,
+>= comparison operators  and the simple pattern matching  % (like) and
+!% (not like) operators. Eg:
+
+friends.#(last=="Murphy").first    >> "Dale"
+friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
+friends.#(age>45)#.last            >> ["Craig","Murphy"]
+friends.#(first%"D*").last         >> "Murphy"
+friends.#(first!%"D*").last        >> "Craig"
+friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]
+
+Documentation: https://github.com/tidwall/gjson/blob/master/SYNTAX.md`
+
+	return &cli.Command{
+		Name:  "help-jsonpath",
+		Usage: "show jsonpath help",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			_, err := fmt.Println(msg)
+			return err
+		},
+	}
+}
+
 func Version(conf *cfg.Config) *cli.Command {
 	return &cli.Command{
 		Name:  "version",

cmd/search.go

@@ -18,7 +18,6 @@ package cmd
 
 import (
 	"context"
-	"fmt"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"codeberg.org/scip/esctl/pkg/es"
@@ -113,12 +112,6 @@ func Search(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Ascending,
 				Aliases:     []string{"a"},
 			},
-			&cli.BoolFlag{
-				Name:        "help-jsonpath",
-				Usage:       "show jsonPath help",
-				Destination: &conf.Subhelp,
-				Aliases:     []string{"H"},
-			},
 			&cli.BoolFlag{
 				Name:        "tail",
 				Usage:       "follow search live, like tail -f",
@@ -131,13 +124,21 @@ func Search(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Or,
 				Aliases:     []string{"O"},
 			},
+			&cli.BoolFlag{
+				Name:        "validate",
+				Usage:       "validate search query",
+				Destination: &conf.Validate,
+				Aliases:     []string{"v"},
+			},
+			&cli.BoolFlag{
+				Name:        "explain",
+				Usage:       "explain search query",
+				Destination: &conf.Explain,
+				Aliases:     []string{"e"},
+			},
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if conf.To == -1 {
@@ -148,34 +149,3 @@ func Search(conf *cfg.Config) *cli.Command {
 		},
 	}
 }
-
-func showJsonPathHelp() error {
-	_, err := fmt.Println(`jsonPath usage:
-
-name.last          >> "Anderson"
-age                >> 37
-children           >> ["Sara","Alex","Jack"]
-children.#         >> 3
-children.1         >> "Alex"
-child*.2           >> "Jack"
-c?ildren.0         >> "Sara"
-fav\.movie         >> "Deer Hunter"
-friends.#.first    >> ["Dale","Roger","Jane"]
-friends.1.last     >> "Craig"
-
-You can also  query an array for  the first match by  using #(...), or
-find all matches  with #(...)#. Queries support the ==,  !=, <, <=, >,
->= comparison operators  and the simple pattern matching  % (like) and
-!% (not like) operators. Eg:
-
-friends.#(last=="Murphy").first    >> "Dale"
-friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
-friends.#(age>45)#.last            >> ["Craig","Murphy"]
-friends.#(first%"D*").last         >> "Murphy"
-friends.#(first!%"D*").last        >> "Craig"
-friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]
-
-Documentation: https://github.com/tidwall/gjson/blob/master/SYNTAX.md`)
-
-	return err
-}

pkg/cfg/config.go

@@ -34,7 +34,7 @@ import (
 )
 
 const (
-	Version string = `v0.0.17`
+	Version string = `v0.0.18`
 )
 
 var (
@@ -70,6 +70,7 @@ type Config struct {
 	Range                          string   // search: -r
 	TimestampFormat                string   // search: --timestamp-format
 	Explain                        bool     // search: -e
+	Validate                       bool     // search: --validate
 	SortBy                         string   // sort: -k
 	Ascending                      bool     // sort: -a
 	Exclude                        string   // cluster compare: -e (regexp)

pkg/es/index.go

@@ -53,15 +53,24 @@ func IndexNames(conf *cfg.Config) ([]string, error) {
 }
 
 func filterIndices(conf *cfg.Config, list indices.Response) indices.Response {
+	// apply partials filter first
+	selectedlist := indices.Response{}
+	for _, index := range list {
+		if !conf.Partials && strings.HasPrefix(*index.Index, "partial-") {
+			continue
+		}
+		selectedlist = append(selectedlist, index)
+	}
+
 	if len(conf.Filter) == 0 {
-		return list
+		return selectedlist
 	}
 
 	// we support just one filter here, for now
 	filter := *regexp.MustCompile(conf.Filter[0])
 	newlist := indices.Response{}
 
-	for _, index := range list {
+	for _, index := range selectedlist {
 		if filter.MatchString(*index.Index) {
 			newlist = append(newlist, index)
 		}

pkg/es/search.go

@@ -18,6 +18,7 @@ package es
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"log"
 	"log/slog"
@@ -28,8 +29,10 @@ import (
 	"github.com/alecthomas/repr"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/core/search"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/esdsl"
+	"github.com/elastic/go-elasticsearch/v9/typedapi/indices/validatequery"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types/enums/sortorder"
+	"github.com/tidwall/gjson"
 )
 
 const (
@@ -43,8 +46,11 @@ Execute an ES search.
 	additional filters can be given as -F key=value
 */
 func Search(conf *cfg.Config, queries []string) error {
-	searchEs := conf.DefaultCluster.ES.Search().
-		Index(conf.Index)
+	if conf.Validate {
+		return validateSearch(conf, queries)
+	}
+
+	searchEs := conf.DefaultCluster.ES.Search().Index(conf.Index)
 
 	queryCaster, err := prepareQuery(conf, queries)
 	if err != nil {
@@ -57,9 +63,11 @@ func Search(conf *cfg.Config, queries []string) error {
 
 	searchEs = addSort(conf, searchEs)
 
-	switch conf.Tail {
-	case true:
+	switch {
+	case conf.Tail:
 		return searchTail(conf, searchEs)
+	case conf.Explain:
+		return explainSearch(conf, searchEs)
 	default:
 		if conf.To > MAXPAGE {
 			return searchPit(conf, req)
@@ -69,6 +77,78 @@ func Search(conf *cfg.Config, queries []string) error {
 	}
 }
 
+func explainSearch(conf *cfg.Config, search *search.Search) error {
+	res, err := search.
+		Explain(true).
+		Size(1). // one's enough for explain
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to call explain search (esdsl): %s", esErrorString(err))
+	}
+
+	if conf.Debug {
+		raw, err := json.Marshal(res)
+		if err != nil {
+			return fmt.Errorf("failed to marshal explain result: %s", err)
+		}
+
+		value := gjson.Get(string(raw), "hits.hits.0._explanation")
+		fmt.Println(value.String())
+	}
+
+	if len(res.Hits.Hits) > 0 {
+		ex := res.Hits.Hits[0].Explanation_
+		fmt.Println(ex.Description)
+		fmt.Println(ex.Value)
+
+		// recurse into explanation details (it's a tree)
+		for _, ex := range ex.Details {
+			explain(&ex, "  ")
+		}
+	}
+
+	return nil
+}
+
+func explain(res *types.ExplanationDetail, indent string) {
+	fmt.Println(indent + "- " + res.Description)
+	for _, ex := range res.Details {
+		fmt.Println(indent + "  - " + ex.Description)
+		fmt.Println(indent + fmt.Sprintf("    score: %f", res.Value))
+
+		explain(&ex, indent+"  ")
+	}
+}
+
+func validateSearch(conf *cfg.Config, queries []string) error {
+	validate := conf.DefaultCluster.ES.Indices.ValidateQuery()
+
+	queryCaster, err := prepareQuery(conf, queries)
+	if err != nil {
+		return err
+	}
+
+	req := &validatequery.Request{Query: queryCaster}
+
+	validate.Request(req)
+
+	res, err := validate.
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to validate search (esdsl): %s", esErrorString(err))
+	}
+
+	slog.Debug("ES result", "search", res)
+
+	if res.Valid {
+		fmt.Println(printer.Colorize(conf, "green", "valid"))
+	} else {
+		fmt.Println(printer.Colorize(conf, "red", "invalid"))
+	}
+
+	return nil
+}
+
 func Debug(conf *cfg.Config) error {
 	res, err := conf.DefaultCluster.ES.Search().
 		Index(conf.Index).
@@ -99,9 +179,7 @@ func searchOnce(conf *cfg.Config, search *search.Search) error {
 
 	slog.Debug("ES result", "search", res)
 
-	for _, hit := range res.Hits.Hits {
-		printer.PrintDoc(conf, hit)
-	}
+	printer.PrintDocs(conf, res.Hits.Hits)
 
 	return nil
 }
@@ -141,9 +219,7 @@ func searchPit(conf *cfg.Config, req *search.Request) error {
 			break
 		}
 
-		for _, hit := range res.Hits.Hits {
-			printer.PrintDoc(conf, hit)
-		}
+		printer.PrintDocs(conf, res.Hits.Hits)
 
 		last := res.Hits.Hits[len(res.Hits.Hits)-1]
 		search = search.SearchAfterValues(last.Sort)
@@ -178,6 +254,7 @@ func searchTail(conf *cfg.Config, search *search.Search) error {
 			}
 
 			printer.PrintDoc(conf, hit)
+			fmt.Println()
 
 			docs[*hit.Id_] = 1
 		}

pkg/printer/doc.go

@@ -18,12 +18,24 @@ package printer
 
 import (
 	"fmt"
+	"slices"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 	"github.com/tidwall/gjson"
 )
 
+func PrintDocs(conf *cfg.Config, hits []types.Hit) {
+	if !conf.Ascending {
+		slices.Reverse(hits)
+	}
+
+	for _, hit := range hits {
+		PrintDoc(conf, hit)
+	}
+
+}
+
 func PrintDoc(conf *cfg.Config, hit types.Hit) {
 	var score types.Float64
 	if hit.Score_ != nil {
@@ -40,6 +52,6 @@ func PrintDoc(conf *cfg.Config, hit types.Hit) {
 		value := gjson.Get(docjson, conf.Path)
 		fmt.Println(value.String())
 	} else {
-		fmt.Println(docjson)
+		fmt.Print(docjson)
 	}
 }