Debian Codegraph @

explain.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 "fmt"
10 "net/url"
11 "strings"
12
13 "gopkg.in/olivere/elastic.v5/uritemplates"
14 )
15
16 // ExplainService computes a score explanation for a query and
17 // a specific document.
18 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.2/search-explain.html.
19 type ExplainService struct {
20 client *Client
21 pretty bool
22 id string
23 index string
24 typ string
25 q string
26 routing string
27 lenient *bool
28 analyzer string
29 df string
30 fields []string
31 lowercaseExpandedTerms *bool
32 xSourceInclude []string
33 analyzeWildcard *bool
34 parent string
35 preference string
36 xSource []string
37 defaultOperator string
38 xSourceExclude []string
39 source string
40 bodyJson interface{}
41 bodyString string
42 }
43
44 // NewExplainService creates a new ExplainService.
45 func NewExplainService(client *Client) *ExplainService {
46 return &ExplainService{
47 client: client,
48 xSource: make([]string, 0),
49 xSourceExclude: make([]string, 0),
50 fields: make([]string, 0),
51 xSourceInclude: make([]string, 0),
52 }
53 }
54
55 // Id is the document ID.
56 func (s *ExplainService) Id(id string) *ExplainService {
57 s.id = id
58 return s
59 }
60
61 // Index is the name of the index.
62 func (s *ExplainService) Index(index string) *ExplainService {
63 s.index = index
64 return s
65 }
66
67 // Type is the type of the document.
68 func (s *ExplainService) Type(typ string) *ExplainService {
69 s.typ = typ
70 return s
71 }
72
73 // Source is the URL-encoded query definition (instead of using the request body).
74 func (s *ExplainService) Source(source string) *ExplainService {
75 s.source = source
76 return s
77 }
78
79 // XSourceExclude is a list of fields to exclude from the returned _source field.
80 func (s *ExplainService) XSourceExclude(xSourceExclude ...string) *ExplainService {
81 s.xSourceExclude = append(s.xSourceExclude, xSourceExclude...)
82 return s
83 }
84
85 // Lenient specifies whether format-based query failures
86 // (such as providing text to a numeric field) should be ignored.
87 func (s *ExplainService) Lenient(lenient bool) *ExplainService {
88 s.lenient = &lenient
89 return s
90 }
91
92 // Query in the Lucene query string syntax.
93 func (s *ExplainService) Q(q string) *ExplainService {
94 s.q = q
95 return s
96 }
97
98 // Routing sets a specific routing value.
99 func (s *ExplainService) Routing(routing string) *ExplainService {
100 s.routing = routing
101 return s
102 }
103
104 // AnalyzeWildcard specifies whether wildcards and prefix queries
105 // in the query string query should be analyzed (default: false).
106 func (s *ExplainService) AnalyzeWildcard(analyzeWildcard bool) *ExplainService {
107 s.analyzeWildcard = &analyzeWildcard
108 return s
109 }
110
111 // Analyzer is the analyzer for the query string query.
112 func (s *ExplainService) Analyzer(analyzer string) *ExplainService {
113 s.analyzer = analyzer
114 return s
115 }
116
117 // Df is the default field for query string query (default: _all).
118 func (s *ExplainService) Df(df string) *ExplainService {
119 s.df = df
120 return s
121 }
122
123 // Fields is a list of fields to return in the response.
124 func (s *ExplainService) Fields(fields ...string) *ExplainService {
125 s.fields = append(s.fields, fields...)
126 return s
127 }
128
129 // LowercaseExpandedTerms specifies whether query terms should be lowercased.
130 func (s *ExplainService) LowercaseExpandedTerms(lowercaseExpandedTerms bool) *ExplainService {
131 s.lowercaseExpandedTerms = &lowercaseExpandedTerms
132 return s
133 }
134
135 // XSourceInclude is a list of fields to extract and return from the _source field.
136 func (s *ExplainService) XSourceInclude(xSourceInclude ...string) *ExplainService {
137 s.xSourceInclude = append(s.xSourceInclude, xSourceInclude...)
138 return s
139 }
140
141 // DefaultOperator is the default operator for query string query (AND or OR).
142 func (s *ExplainService) DefaultOperator(defaultOperator string) *ExplainService {
143 s.defaultOperator = defaultOperator
144 return s
145 }
146
147 // Parent is the ID of the parent document.
148 func (s *ExplainService) Parent(parent string) *ExplainService {
149 s.parent = parent
150 return s
151 }
152
153 // Preference specifies the node or shard the operation should be performed on (default: random).
154 func (s *ExplainService) Preference(preference string) *ExplainService {
155 s.preference = preference
156 return s
157 }
158
159 // XSource is true or false to return the _source field or not, or a list of fields to return.
160 func (s *ExplainService) XSource(xSource ...string) *ExplainService {
161 s.xSource = append(s.xSource, xSource...)
162 return s
163 }
164
165 // Pretty indicates that the JSON response be indented and human readable.
166 func (s *ExplainService) Pretty(pretty bool) *ExplainService {
167 s.pretty = pretty
168 return s
169 }
170
171 // Query sets a query definition using the Query DSL.
172 func (s *ExplainService) Query(query Query) *ExplainService {
173 src, err := query.Source()
174 if err != nil {
175 // Do nothing in case of an error
176 return s
177 }
178 body := make(map[string]interface{})
179 body["query"] = src
180 s.bodyJson = body
181 return s
182 }
183
184 // BodyJson sets the query definition using the Query DSL.
185 func (s *ExplainService) BodyJson(body interface{}) *ExplainService {
186 s.bodyJson = body
187 return s
188 }
189
190 // BodyString sets the query definition using the Query DSL as a string.
191 func (s *ExplainService) BodyString(body string) *ExplainService {
192 s.bodyString = body
193 return s
194 }
195
196 // buildURL builds the URL for the operation.
197 func (s *ExplainService) buildURL() (string, url.Values, error) {
198 // Build URL
199 path, err := uritemplates.Expand("/{index}/{type}/{id}/_explain", map[string]string{
200 "id": s.id,
201 "index": s.index,
202 "type": s.typ,
203 })
204 if err != nil {
205 return "", url.Values{}, err
206 }
207
208 // Add query string parameters
209 params := url.Values{}
210 if s.pretty {
211 params.Set("pretty", "1")
212 }
213 if len(s.xSource) > 0 {
214 params.Set("_source", strings.Join(s.xSource, ","))
215 }
216 if s.defaultOperator != "" {
217 params.Set("default_operator", s.defaultOperator)
218 }
219 if s.parent != "" {
220 params.Set("parent", s.parent)
221 }
222 if s.preference != "" {
223 params.Set("preference", s.preference)
224 }
225 if s.source != "" {
226 params.Set("source", s.source)
227 }
228 if len(s.xSourceExclude) > 0 {
229 params.Set("_source_exclude", strings.Join(s.xSourceExclude, ","))
230 }
231 if s.lenient != nil {
232 params.Set("lenient", fmt.Sprintf("%v", *s.lenient))
233 }
234 if s.q != "" {
235 params.Set("q", s.q)
236 }
237 if s.routing != "" {
238 params.Set("routing", s.routing)
239 }
240 if len(s.fields) > 0 {
241 params.Set("fields", strings.Join(s.fields, ","))
242 }
243 if s.lowercaseExpandedTerms != nil {
244 params.Set("lowercase_expanded_terms", fmt.Sprintf("%v", *s.lowercaseExpandedTerms))
245 }
246 if len(s.xSourceInclude) > 0 {
247 params.Set("_source_include", strings.Join(s.xSourceInclude, ","))
248 }
249 if s.analyzeWildcard != nil {
250 params.Set("analyze_wildcard", fmt.Sprintf("%v", *s.analyzeWildcard))
251 }
252 if s.analyzer != "" {
253 params.Set("analyzer", s.analyzer)
254 }
255 if s.df != "" {
256 params.Set("df", s.df)
257 }
258 return path, params, nil
259 }
260
261 // Validate checks if the operation is valid.
262 func (s *ExplainService) Validate() error {
263 var invalid []string
264 if s.index == "" {
265 invalid = append(invalid, "Index")
266 }
267 if s.typ == "" {
268 invalid = append(invalid, "Type")
269 }
270 if s.id == "" {
271 invalid = append(invalid, "Id")
272 }
273 if len(invalid) > 0 {
274 return fmt.Errorf("missing required fields: %v", invalid)
275 }
276 return nil
277 }
278
279 // Do executes the operation.
280 func (s *ExplainService) Do(ctx context.Context) (*ExplainResponse, error) {
281 // Check pre-conditions
282 if err := s.Validate(); err != nil {
283 return nil, err
284 }
285
286 // Get URL for request
287 path, params, err := s.buildURL()
288 if err != nil {
289 return nil, err
290 }
291
292 // Setup HTTP request body
293 var body interface{}
294 if s.bodyJson != nil {
295 body = s.bodyJson
296 } else {
297 body = s.bodyString
298 }
299
300 // Get HTTP response
301 res, err := s.client.PerformRequest(ctx, "GET", path, params, body)
302 if err != nil {
303 return nil, err
304 }
305
306 // Return operation response
307 ret := new(ExplainResponse)
308 if err := s.client.decoder.Decode(res.Body, ret); err != nil {
309 return nil, err
310 }
311 return ret, nil
312 }
313
314 // ExplainResponse is the response of ExplainService.Do.
315 type ExplainResponse struct {
316 Index string `json:"_index"`
317 Type string `json:"_type"`
318 Id string `json:"_id"`
319 Matched bool `json:"matched"`
320 Explanation map[string]interface{} `json:"explanation"`
321 }