Debian Codegraph @

search.go

raw
1 // Copyright 2012-present Oliver Eilhard. All rights reserved.
2 // Use of this source code is governed by a MIT-license.
3 // See http://olivere.mit-license.org/license.txt for details.
4
5 package elastic
6
7 import (
8 "context"
9 "encoding/json"
10 "fmt"
11 "net/url"
12 "reflect"
13 "strings"
14
15 "gopkg.in/olivere/elastic.v5/uritemplates"
16 )
17
18 // Search for documents in Elasticsearch.
19 type SearchService struct {
20 client *Client
21 searchSource *SearchSource
22 source interface{}
23 pretty bool
24 filterPath []string
25 searchType string
26 index []string
27 typ []string
28 routing string
29 preference string
30 requestCache *bool
31 ignoreUnavailable *bool
32 allowNoIndices *bool
33 expandWildcards string
34 }
35
36 // NewSearchService creates a new service for searching in Elasticsearch.
37 func NewSearchService(client *Client) *SearchService {
38 builder := &SearchService{
39 client: client,
40 searchSource: NewSearchSource(),
41 }
42 return builder
43 }
44
45 // SearchSource sets the search source builder to use with this service.
46 func (s *SearchService) SearchSource(searchSource *SearchSource) *SearchService {
47 s.searchSource = searchSource
48 if s.searchSource == nil {
49 s.searchSource = NewSearchSource()
50 }
51 return s
52 }
53
54 // Source allows the user to set the request body manually without using
55 // any of the structs and interfaces in Elastic.
56 func (s *SearchService) Source(source interface{}) *SearchService {
57 s.source = source
58 return s
59 }
60
61 // FilterPath allows reducing the response, a mechanism known as
62 // response filtering and described here:
63 // https://www.elastic.co/guide/en/elasticsearch/reference/5.6/common-options.html#common-options-response-filtering.
64 func (s *SearchService) FilterPath(filterPath ...string) *SearchService {
65 s.filterPath = append(s.filterPath, filterPath...)
66 return s
67 }
68
69 // Index sets the names of the indices to use for search.
70 func (s *SearchService) Index(index ...string) *SearchService {
71 s.index = append(s.index, index...)
72 return s
73 }
74
75 // Types adds search restrictions for a list of types.
76 func (s *SearchService) Type(typ ...string) *SearchService {
77 s.typ = append(s.typ, typ...)
78 return s
79 }
80
81 // Pretty enables the caller to indent the JSON output.
82 func (s *SearchService) Pretty(pretty bool) *SearchService {
83 s.pretty = pretty
84 return s
85 }
86
87 // Timeout sets the timeout to use, e.g. "1s" or "1000ms".
88 func (s *SearchService) Timeout(timeout string) *SearchService {
89 s.searchSource = s.searchSource.Timeout(timeout)
90 return s
91 }
92
93 // Profile sets the Profile API flag on the search source.
94 // When enabled, a search executed by this service will return query
95 // profiling data.
96 func (s *SearchService) Profile(profile bool) *SearchService {
97 s.searchSource = s.searchSource.Profile(profile)
98 return s
99 }
100
101 // Collapse adds field collapsing.
102 func (s *SearchService) Collapse(collapse *CollapseBuilder) *SearchService {
103 s.searchSource = s.searchSource.Collapse(collapse)
104 return s
105 }
106
107 // TimeoutInMillis sets the timeout in milliseconds.
108 func (s *SearchService) TimeoutInMillis(timeoutInMillis int) *SearchService {
109 s.searchSource = s.searchSource.TimeoutInMillis(timeoutInMillis)
110 return s
111 }
112
113 // TerminateAfter specifies the maximum number of documents to collect for
114 // each shard, upon reaching which the query execution will terminate early.
115 func (s *SearchService) TerminateAfter(terminateAfter int) *SearchService {
116 s.searchSource = s.searchSource.TerminateAfter(terminateAfter)
117 return s
118 }
119
120 // SearchType sets the search operation type. Valid values are:
121 // "dfs_query_then_fetch" and "query_then_fetch".
122 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-search-type.html
123 // for details.
124 func (s *SearchService) SearchType(searchType string) *SearchService {
125 s.searchType = searchType
126 return s
127 }
128
129 // Routing is a list of specific routing values to control the shards
130 // the search will be executed on.
131 func (s *SearchService) Routing(routings ...string) *SearchService {
132 s.routing = strings.Join(routings, ",")
133 return s
134 }
135
136 // Preference sets the preference to execute the search. Defaults to
137 // randomize across shards ("random"). Can be set to "_local" to prefer
138 // local shards, "_primary" to execute on primary shards only,
139 // or a custom value which guarantees that the same order will be used
140 // across different requests.
141 func (s *SearchService) Preference(preference string) *SearchService {
142 s.preference = preference
143 return s
144 }
145
146 // RequestCache indicates whether the cache should be used for this
147 // request or not, defaults to index level setting.
148 func (s *SearchService) RequestCache(requestCache bool) *SearchService {
149 s.requestCache = &requestCache
150 return s
151 }
152
153 // Query sets the query to perform, e.g. MatchAllQuery.
154 func (s *SearchService) Query(query Query) *SearchService {
155 s.searchSource = s.searchSource.Query(query)
156 return s
157 }
158
159 // PostFilter will be executed after the query has been executed and
160 // only affects the search hits, not the aggregations.
161 // This filter is always executed as the last filtering mechanism.
162 func (s *SearchService) PostFilter(postFilter Query) *SearchService {
163 s.searchSource = s.searchSource.PostFilter(postFilter)
164 return s
165 }
166
167 // FetchSource indicates whether the response should contain the stored
168 // _source for every hit.
169 func (s *SearchService) FetchSource(fetchSource bool) *SearchService {
170 s.searchSource = s.searchSource.FetchSource(fetchSource)
171 return s
172 }
173
174 // FetchSourceContext indicates how the _source should be fetched.
175 func (s *SearchService) FetchSourceContext(fetchSourceContext *FetchSourceContext) *SearchService {
176 s.searchSource = s.searchSource.FetchSourceContext(fetchSourceContext)
177 return s
178 }
179
180 // Highlight adds highlighting to the search.
181 func (s *SearchService) Highlight(highlight *Highlight) *SearchService {
182 s.searchSource = s.searchSource.Highlight(highlight)
183 return s
184 }
185
186 // GlobalSuggestText defines the global text to use with all suggesters.
187 // This avoids repetition.
188 func (s *SearchService) GlobalSuggestText(globalText string) *SearchService {
189 s.searchSource = s.searchSource.GlobalSuggestText(globalText)
190 return s
191 }
192
193 // Suggester adds a suggester to the search.
194 func (s *SearchService) Suggester(suggester Suggester) *SearchService {
195 s.searchSource = s.searchSource.Suggester(suggester)
196 return s
197 }
198
199 // Aggregation adds an aggreation to perform as part of the search.
200 func (s *SearchService) Aggregation(name string, aggregation Aggregation) *SearchService {
201 s.searchSource = s.searchSource.Aggregation(name, aggregation)
202 return s
203 }
204
205 // MinScore sets the minimum score below which docs will be filtered out.
206 func (s *SearchService) MinScore(minScore float64) *SearchService {
207 s.searchSource = s.searchSource.MinScore(minScore)
208 return s
209 }
210
211 // From index to start the search from. Defaults to 0.
212 func (s *SearchService) From(from int) *SearchService {
213 s.searchSource = s.searchSource.From(from)
214 return s
215 }
216
217 // Size is the number of search hits to return. Defaults to 10.
218 func (s *SearchService) Size(size int) *SearchService {
219 s.searchSource = s.searchSource.Size(size)
220 return s
221 }
222
223 // Explain indicates whether each search hit should be returned with
224 // an explanation of the hit (ranking).
225 func (s *SearchService) Explain(explain bool) *SearchService {
226 s.searchSource = s.searchSource.Explain(explain)
227 return s
228 }
229
230 // Version indicates whether each search hit should be returned with
231 // a version associated to it.
232 func (s *SearchService) Version(version bool) *SearchService {
233 s.searchSource = s.searchSource.Version(version)
234 return s
235 }
236
237 // Sort adds a sort order.
238 func (s *SearchService) Sort(field string, ascending bool) *SearchService {
239 s.searchSource = s.searchSource.Sort(field, ascending)
240 return s
241 }
242
243 // SortWithInfo adds a sort order.
244 func (s *SearchService) SortWithInfo(info SortInfo) *SearchService {
245 s.searchSource = s.searchSource.SortWithInfo(info)
246 return s
247 }
248
249 // SortBy adds a sort order.
250 func (s *SearchService) SortBy(sorter ...Sorter) *SearchService {
251 s.searchSource = s.searchSource.SortBy(sorter...)
252 return s
253 }
254
255 // NoStoredFields indicates that no stored fields should be loaded, resulting in only
256 // id and type to be returned per field.
257 func (s *SearchService) NoStoredFields() *SearchService {
258 s.searchSource = s.searchSource.NoStoredFields()
259 return s
260 }
261
262 // StoredField adds a single field to load and return (note, must be stored) as
263 // part of the search request. If none are specified, the source of the
264 // document will be returned.
265 func (s *SearchService) StoredField(fieldName string) *SearchService {
266 s.searchSource = s.searchSource.StoredField(fieldName)
267 return s
268 }
269
270 // StoredFields sets the fields to load and return as part of the search request.
271 // If none are specified, the source of the document will be returned.
272 func (s *SearchService) StoredFields(fields ...string) *SearchService {
273 s.searchSource = s.searchSource.StoredFields(fields...)
274 return s
275 }
276
277 // TrackScores is applied when sorting and controls if scores will be
278 // tracked as well. Defaults to false.
279 func (s *SearchService) TrackScores(trackScores bool) *SearchService {
280 s.searchSource = s.searchSource.TrackScores(trackScores)
281 return s
282 }
283
284 // SearchAfter allows a different form of pagination by using a live cursor,
285 // using the results of the previous page to help the retrieval of the next.
286 //
287 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-search-after.html
288 func (s *SearchService) SearchAfter(sortValues ...interface{}) *SearchService {
289 s.searchSource = s.searchSource.SearchAfter(sortValues...)
290 return s
291 }
292
293 // IgnoreUnavailable indicates whether the specified concrete indices
294 // should be ignored when unavailable (missing or closed).
295 func (s *SearchService) IgnoreUnavailable(ignoreUnavailable bool) *SearchService {
296 s.ignoreUnavailable = &ignoreUnavailable
297 return s
298 }
299
300 // AllowNoIndices indicates whether to ignore if a wildcard indices
301 // expression resolves into no concrete indices. (This includes `_all` string
302 // or when no indices have been specified).
303 func (s *SearchService) AllowNoIndices(allowNoIndices bool) *SearchService {
304 s.allowNoIndices = &allowNoIndices
305 return s
306 }
307
308 // ExpandWildcards indicates whether to expand wildcard expression to
309 // concrete indices that are open, closed or both.
310 func (s *SearchService) ExpandWildcards(expandWildcards string) *SearchService {
311 s.expandWildcards = expandWildcards
312 return s
313 }
314
315 // buildURL builds the URL for the operation.
316 func (s *SearchService) buildURL() (string, url.Values, error) {
317 var err error
318 var path string
319
320 if len(s.index) > 0 && len(s.typ) > 0 {
321 path, err = uritemplates.Expand("/{index}/{type}/_search", map[string]string{
322 "index": strings.Join(s.index, ","),
323 "type": strings.Join(s.typ, ","),
324 })
325 } else if len(s.index) > 0 {
326 path, err = uritemplates.Expand("/{index}/_search", map[string]string{
327 "index": strings.Join(s.index, ","),
328 })
329 } else if len(s.typ) > 0 {
330 path, err = uritemplates.Expand("/_all/{type}/_search", map[string]string{
331 "type": strings.Join(s.typ, ","),
332 })
333 } else {
334 path = "/_search"
335 }
336 if err != nil {
337 return "", url.Values{}, err
338 }
339
340 // Add query string parameters
341 params := url.Values{}
342 if s.pretty {
343 params.Set("pretty", fmt.Sprintf("%v", s.pretty))
344 }
345 if s.searchType != "" {
346 params.Set("search_type", s.searchType)
347 }
348 if s.routing != "" {
349 params.Set("routing", s.routing)
350 }
351 if s.preference != "" {
352 params.Set("preference", s.preference)
353 }
354 if s.requestCache != nil {
355 params.Set("request_cache", fmt.Sprintf("%v", *s.requestCache))
356 }
357 if s.allowNoIndices != nil {
358 params.Set("allow_no_indices", fmt.Sprintf("%v", *s.allowNoIndices))
359 }
360 if s.expandWildcards != "" {
361 params.Set("expand_wildcards", s.expandWildcards)
362 }
363 if s.ignoreUnavailable != nil {
364 params.Set("ignore_unavailable", fmt.Sprintf("%v", *s.ignoreUnavailable))
365 }
366 if len(s.filterPath) > 0 {
367 params.Set("filter_path", strings.Join(s.filterPath, ","))
368 }
369 return path, params, nil
370 }
371
372 // Validate checks if the operation is valid.
373 func (s *SearchService) Validate() error {
374 return nil
375 }
376
377 // Do executes the search and returns a SearchResult.
378 func (s *SearchService) Do(ctx context.Context) (*SearchResult, error) {
379 // Check pre-conditions
380 if err := s.Validate(); err != nil {
381 return nil, err
382 }
383
384 // Get URL for request
385 path, params, err := s.buildURL()
386 if err != nil {
387 return nil, err
388 }
389
390 // Perform request
391 var body interface{}
392 if s.source != nil {
393 body = s.source
394 } else {
395 src, err := s.searchSource.Source()
396 if err != nil {
397 return nil, err
398 }
399 body = src
400 }
401 res, err := s.client.PerformRequest(ctx, "POST", path, params, body)
402 if err != nil {
403 return nil, err
404 }
405
406 // Return search results
407 ret := new(SearchResult)
408 if err := s.client.decoder.Decode(res.Body, ret); err != nil {
409 return nil, err
410 }
411 return ret, nil
412 }
413
414 // SearchResult is the result of a search in Elasticsearch.
415 type SearchResult struct {
416 TookInMillis int64 `json:"took"` // search time in milliseconds
417 ScrollId string `json:"_scroll_id"` // only used with Scroll operations
418 Hits *SearchHits `json:"hits"` // the actual search hits
419 Suggest SearchSuggest `json:"suggest"` // results from suggesters
420 Aggregations Aggregations `json:"aggregations"` // results from aggregations
421 TimedOut bool `json:"timed_out"` // true if the search timed out
422 Error *ErrorDetails `json:"error,omitempty"` // only used in MultiGet
423 Profile *SearchProfile `json:"profile,omitempty"` // profiling results, if optional Profile API was active for this search
424 Shards *ShardsInfo `json:"_shards,omitempty"` // shard information
425 }
426
427 // TotalHits is a convenience function to return the number of hits for
428 // a search result.
429 func (r *SearchResult) TotalHits() int64 {
430 if r.Hits != nil {
431 return r.Hits.TotalHits
432 }
433 return 0
434 }
435
436 // Each is a utility function to iterate over all hits. It saves you from
437 // checking for nil values. Notice that Each will ignore errors in
438 // serializing JSON.
439 func (r *SearchResult) Each(typ reflect.Type) []interface{} {
440 if r.Hits == nil || r.Hits.Hits == nil || len(r.Hits.Hits) == 0 {
441 return nil
442 }
443 var slice []interface{}
444 for _, hit := range r.Hits.Hits {
445 v := reflect.New(typ).Elem()
446 if hit.Source == nil {
447 slice = append(slice, v.Interface())
448 continue
449 }
450 if err := json.Unmarshal(*hit.Source, v.Addr().Interface()); err == nil {
451 slice = append(slice, v.Interface())
452 }
453 }
454 return slice
455 }
456
457 // SearchHits specifies the list of search hits.
458 type SearchHits struct {
459 TotalHits int64 `json:"total"` // total number of hits found
460 MaxScore *float64 `json:"max_score"` // maximum score of all hits
461 Hits []*SearchHit `json:"hits"` // the actual hits returned
462 }
463
464 // NestedHit is a nested innerhit
465 type NestedHit struct {
466 Field string `json:"field"`
467 Offset int `json:"offset,omitempty"`
468 Child *NestedHit `json:"_nested,omitempty"`
469 }
470
471 // SearchHit is a single hit.
472 type SearchHit struct {
473 Score *float64 `json:"_score"` // computed score
474 Shard string `json:"_shard"` // shard name
475 Node string `json:"_node"` // node name
476 Index string `json:"_index"` // index name
477 Type string `json:"_type"` // type meta field
478 Id string `json:"_id"` // external or internal
479 Uid string `json:"_uid"` // uid meta field (see MapperService.java for all meta fields)
480 Routing string `json:"_routing"` // routing meta field
481 Parent string `json:"_parent"` // parent meta field
482 Version *int64 `json:"_version"` // version number, when Version is set to true in SearchService
483 Sort []interface{} `json:"sort"` // sort information
484 Highlight SearchHitHighlight `json:"highlight"` // highlighter information
485 Source *json.RawMessage `json:"_source"` // stored document source
486 Fields map[string]interface{} `json:"fields"` // returned (stored) fields
487 Explanation *SearchExplanation `json:"_explanation"` // explains how the score was computed
488 MatchedQueries []string `json:"matched_queries"` // matched queries
489 InnerHits map[string]*SearchHitInnerHits `json:"inner_hits"` // inner hits with ES >= 1.5.0
490 Nested *NestedHit `json:"_nested"` // for nested inner hits
491
492 // Shard
493 // HighlightFields
494 // SortValues
495 // MatchedFilters
496 }
497
498 type SearchHitInnerHits struct {
499 Hits *SearchHits `json:"hits"`
500 }
501
502 // SearchExplanation explains how the score for a hit was computed.
503 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-explain.html.
504 type SearchExplanation struct {
505 Value float64 `json:"value"` // e.g. 1.0
506 Description string `json:"description"` // e.g. "boost" or "ConstantScore(*:*), product of:"
507 Details []SearchExplanation `json:"details,omitempty"` // recursive details
508 }
509
510 // Suggest
511
512 // SearchSuggest is a map of suggestions.
513 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-suggesters.html.
514 type SearchSuggest map[string][]SearchSuggestion
515
516 // SearchSuggestion is a single search suggestion.
517 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-suggesters.html.
518 type SearchSuggestion struct {
519 Text string `json:"text"`
520 Offset int `json:"offset"`
521 Length int `json:"length"`
522 Options []SearchSuggestionOption `json:"options"`
523 }
524
525 // SearchSuggestionOption is an option of a SearchSuggestion.
526 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-suggesters.html.
527 type SearchSuggestionOption struct {
528 Text string `json:"text"`
529 Index string `json:"_index"`
530 Type string `json:"_type"`
531 Id string `json:"_id"`
532 Score float64 `json:"score"`
533 Highlighted string `json:"highlighted"`
534 CollateMatch bool `json:"collate_match"`
535 Freq int `json:"freq"` // from TermSuggestion.Option in Java API
536 Source *json.RawMessage `json:"_source"`
537 }
538
539 // SearchProfile is a list of shard profiling data collected during
540 // query execution in the "profile" section of a SearchResult
541 type SearchProfile struct {
542 Shards []SearchProfileShardResult `json:"shards"`
543 }
544
545 // SearchProfileShardResult returns the profiling data for a single shard
546 // accessed during the search query or aggregation.
547 type SearchProfileShardResult struct {
548 ID string `json:"id"`
549 Searches []QueryProfileShardResult `json:"searches"`
550 Aggregations []ProfileResult `json:"aggregations"`
551 }
552
553 // QueryProfileShardResult is a container class to hold the profile results
554 // for a single shard in the request. It comtains a list of query profiles,
555 // a collector tree and a total rewrite tree.
556 type QueryProfileShardResult struct {
557 Query []ProfileResult `json:"query,omitempty"`
558 RewriteTime int64 `json:"rewrite_time,omitempty"`
559 Collector []interface{} `json:"collector,omitempty"`
560 }
561
562 // CollectorResult holds the profile timings of the collectors used in the
563 // search. Children's CollectorResults may be embedded inside of a parent
564 // CollectorResult.
565 type CollectorResult struct {
566 Name string `json:"name,omitempty"`
567 Reason string `json:"reason,omitempty"`
568 Time string `json:"time,omitempty"`
569 TimeNanos int64 `json:"time_in_nanos,omitempty"`
570 Children []CollectorResult `json:"children,omitempty"`
571 }
572
573 // ProfileResult is the internal representation of a profiled query,
574 // corresponding to a single node in the query tree.
575 type ProfileResult struct {
576 Type string `json:"type"`
577 Description string `json:"description,omitempty"`
578 NodeTime string `json:"time,omitempty"`
579 NodeTimeNanos int64 `json:"time_in_nanos,omitempty"`
580 Breakdown map[string]int64 `json:"breakdown,omitempty"`
581 Children []ProfileResult `json:"children,omitempty"`
582 }
583
584 // Aggregations (see search_aggs.go)
585
586 // Highlighting
587
588 // SearchHitHighlight is the highlight information of a search hit.
589 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-highlighting.html
590 // for a general discussion of highlighting.
591 type SearchHitHighlight map[string][]string