github.com/hashicorp/nomad/api@v0.0.0-20240306165712-3193ac204f65/search.go (about)

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  package api
     5  
     6  import (
     7  	"github.com/hashicorp/nomad/api/contexts"
     8  )
     9  
    10  type Search struct {
    11  	client *Client
    12  }
    13  
    14  // Search returns a handle on the Search endpoints
    15  func (c *Client) Search() *Search {
    16  	return &Search{client: c}
    17  }
    18  
    19  // PrefixSearch returns a set of matches for a particular context and prefix.
    20  func (s *Search) PrefixSearch(prefix string, context contexts.Context, q *QueryOptions) (*SearchResponse, *QueryMeta, error) {
    21  	var resp SearchResponse
    22  	req := &SearchRequest{Prefix: prefix, Context: context}
    23  
    24  	qm, err := s.client.putQuery("/v1/search", req, &resp, q)
    25  	if err != nil {
    26  		return nil, nil, err
    27  	}
    28  
    29  	return &resp, qm, nil
    30  }
    31  
    32  type SearchResponse struct {
    33  	Matches     map[contexts.Context][]string
    34  	Truncations map[contexts.Context]bool
    35  	QueryMeta
    36  }
    37  
    38  type SearchRequest struct {
    39  	Prefix  string
    40  	Context contexts.Context
    41  	QueryOptions
    42  }
    43  
    44  // FuzzySearch returns a set of matches for a given context and string.
    45  func (s *Search) FuzzySearch(text string, context contexts.Context, q *QueryOptions) (*FuzzySearchResponse, *QueryMeta, error) {
    46  	var resp FuzzySearchResponse
    47  
    48  	req := &FuzzySearchRequest{
    49  		Context: context,
    50  		Text:    text,
    51  	}
    52  
    53  	qm, err := s.client.putQuery("/v1/search/fuzzy", req, &resp, q)
    54  	if err != nil {
    55  		return nil, nil, err
    56  	}
    57  
    58  	return &resp, qm, nil
    59  }
    60  
    61  // FuzzyMatch is used to describe the ID of an object which may be a machine
    62  // readable UUID or a human readable Name. If the object is a component of a Job,
    63  // the Scope is a list of IDs starting from Namespace down to the parent object of
    64  // ID.
    65  //
    66  // e.g. A Task-level service would have scope like,
    67  //
    68  //	["<namespace>", "<job>", "<group>", "<task>"]
    69  type FuzzyMatch struct {
    70  	ID    string   // ID is UUID or Name of object
    71  	Scope []string `json:",omitempty"` // IDs of parent objects
    72  }
    73  
    74  // FuzzySearchResponse is used to return fuzzy matches and information about
    75  // whether the match list is truncated specific to each type of searchable Context.
    76  type FuzzySearchResponse struct {
    77  	// Matches is a map of Context types to IDs which fuzzy match a specified query.
    78  	Matches map[contexts.Context][]FuzzyMatch
    79  
    80  	// Truncations indicates whether the matches for a particular Context have
    81  	// been truncated.
    82  	Truncations map[contexts.Context]bool
    83  
    84  	QueryMeta
    85  }
    86  
    87  // FuzzySearchRequest is used to parameterize a fuzzy search request, and returns
    88  // a list of matches made up of jobs, allocations, evaluations, and/or nodes,
    89  // along with whether or not the information returned is truncated.
    90  type FuzzySearchRequest struct {
    91  	// Text is what names are fuzzy-matched to. E.g. if the given text were
    92  	// "py", potential matches might be "python", "mypy", etc. of jobs, nodes,
    93  	// allocs, groups, services, commands, images, classes.
    94  	Text string
    95  
    96  	// Context is the type that can be matched against. A Context of "all" indicates
    97  	// all Contexts types are queried for matching.
    98  	Context contexts.Context
    99  
   100  	QueryOptions
   101  }