esctl/cmd/search.go

/*
Copyright © 2026 Thomas von Dein

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package cmd

import (
	"context"
	"fmt"

	"codeberg.org/scip/esctl/pkg/cfg"
	"codeberg.org/scip/esctl/pkg/es"

	"github.com/urfave/cli/v3"
)

const SearchUsage = `<sep> might be one of:
 =: Must match
!=: Must not match

You can omit a field spec and thereby search across all fields.

By default all queries contribute to matches (logical AND), use
-O to apply a logical OR operator.

You can also search multiple fields by separating them with comma, eg:
user,group=root

Use filters to further restrict results, they must match literally.

For datetime range format refer to:
https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math

For timestamp formats refer to:
https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/mapping-date-format
`

func Search(conf *cfg.Config) *cli.Command {
	return &cli.Command{
		Name:      "search",
		Aliases:   []string{"/"},
		Usage:     "search within an index",
		UsageText: "search [options] [<[field<sep>]pattern> ...]\n" + SearchUsage,

		Flags: []cli.Flag{
			&cli.StringFlag{
				Name:        "index",
				Usage:       "index to search within",
				Sources:     cli.EnvVars("ES_INDEX"),
				Destination: &conf.Index,
				Aliases:     []string{"i"},
			},
			&cli.IntFlag{
				Name:        "from",
				Usage:       "show results starting at <from>",
				Destination: &conf.From,
				Value:       0,
				Aliases:     []string{"f"},
			},
			&cli.IntFlag{
				Name:        "len",
				Usage:       "number of results to show (-1: all[max:10k], caution: might be slow)",
				Destination: &conf.To,
				Value:       20,
				Aliases:     []string{"l"},
			},
			&cli.StringSliceFlag{
				Name:        "filter",
				Usage:       "additional boolean filters. format: key=value",
				Destination: &conf.Filter,
				Aliases:     []string{"F"},
			},
			&cli.StringFlag{
				Name:        "jsonpath",
				Usage:       "jsonPath filter (e.g. source.message)",
				Destination: &conf.Path,
				Aliases:     []string{"p"},
			},
			&cli.StringFlag{
				Name:        "timerange",
				Usage:       "field:<date> to <date> (e.g. @timestamp:2026-05-05 to 2026-05-15)",
				Destination: &conf.Range,
				Aliases:     []string{"r"},
			},
			&cli.StringFlag{
				Name:        "timestamp-format",
				Usage:       "a valid ES builtin timestamp or custom format",
				Destination: &conf.TimestampFormat,
				Value:       "strict_date_hour_minute",
			},
			&cli.StringFlag{
				Name:        "sort-by",
				Usage:       "sort by a field",
				Destination: &conf.SortBy,
				Value:       "@timestamp",
				Aliases:     []string{"k"},
			},
			&cli.BoolFlag{
				Name:        "ascending",
				Usage:       "sort in ascending order (default: descending)",
				Destination: &conf.Ascending,
				Aliases:     []string{"a"},
			},
			&cli.BoolFlag{
				Name:        "tail",
				Usage:       "follow search live, like tail -f",
				Destination: &conf.Tail,
				Aliases:     []string{"T"},
			},
			&cli.BoolFlag{
				Name:        "or",
				Usage:       "logical operator (default: and)",
				Destination: &conf.Or,
				Aliases:     []string{"O"},
			},
		},

		Action: func(ctx context.Context, cmd *cli.Command) error {
			if conf.Subhelp {
				return showJsonPathHelp()
			}

			args := cmd.Args()

			if conf.To == -1 {
				conf.To = 10000
			}

			return es.Search(conf, args.Slice())
		},
	}
}

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
}