README.md
1# Elastic
2
3Elastic is an [Elasticsearch](http://www.elasticsearch.org/) client for the
4[Go](http://www.golang.org/) programming language.
5
6[![Build Status](https://travis-ci.org/olivere/elastic.svg?branch=master)](https://travis-ci.org/olivere/elastic)
7[![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/olivere/elastic)
8[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/olivere/elastic/master/LICENSE)
9
10See the [wiki](https://github.com/olivere/elastic/wiki) for additional information about Elastic.
11
12
13## Releases
14
15**Notice that the master branch always refers to the latest version of Elastic. If you want to use stable versions of Elastic, you should use the packages released via [gopkg.in](https://gopkg.in).**
16
17Here's the version matrix:
18
19Elasticsearch version | Elastic version -| Package URL
20----------------------|------------------|------------
212.x | 3.0 **beta** | [`gopkg.in/olivere/elastic.v3-unstable`](https://gopkg.in/olivere/elastic.v3-unstable) ([source](https://github.com/olivere/elastic/tree/release-branch.v3) [doc](http://godoc.org/gopkg.in/olivere/elastic.v3-unstable))
221.x | 2.0 | [`gopkg.in/olivere/elastic.v2`](https://gopkg.in/olivere/elastic.v2) ([source](https://github.com/olivere/elastic/tree/release-branch.v2) [doc](http://godoc.org/gopkg.in/olivere/elastic.v2))
230.9-1.3 | 1.0 | [`gopkg.in/olivere/elastic.v1`](https://gopkg.in/olivere/elastic.v1) ([source](https://github.com/olivere/elastic/tree/release-branch.v1) [doc](http://godoc.org/gopkg.in/olivere/elastic.v1))
24
25**Example:**
26
27You have Elasticsearch 1.6.0 installed and want to use Elastic. As listed above, you should use Elastic 2.0. So you first install Elastic 2.0.
28
29```sh
30$ go get gopkg.in/olivere/elastic.v2
31```
32
33Then you use it via the following import path:
34
35```go
36import "gopkg.in/olivere/elastic.v2"
37```
38
39### Elastic 3.0
40
41Elastic 3.0 targets Elasticsearch 2.x and is currently under [active development](https://github.com/olivere/elastic/tree/release-branch.v3). It is not published to gokpg yet.
42
43There are a lot of [breaking changes in Elasticsearch 2.0](https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking-changes-2.0.html) and we will use this as an opportunity to [clean up and refactor Elastic as well](https://github.com/olivere/elastic/blob/release-branch.v3/CHANGELOG-3.0.md).
44
45### Elastic 2.0
46
47Elastic 2.0 targets Elasticsearch 1.x and published via [`gopkg.in/olivere/elastic.v2`](https://gopkg.in/olivere/elastic.v2).
48
49### Elastic 1.0
50
51Elastic 1.0 is deprecated. You should really update Elasticsearch and Elastic
52to a recent version.
53
54However, if you cannot update for some reason, don't worry. Version 1.0 is
55still available. All you need to do is go-get it and change your import path
56as described above.
57
58
59## Status
60
61We use Elastic in production since 2012. Although Elastic is quite stable
62from our experience, we don't have a stable API yet. The reason for this
63is that Elasticsearch changes quite often and at a fast pace.
64At this moment we focus on features, not on a stable API.
65
66Having said that, there have been no big API changes that required you
67to rewrite your application big time.
68More often than not it's renaming APIs and adding/removing features
69so that we are in sync with the Elasticsearch API.
70
71Elastic has been used in production with the following Elasticsearch versions:
720.90, 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5.
73Furthermore, we use [Travis CI](https://travis-ci.org/)
74to test Elastic with the most recent versions of Elasticsearch and Go.
75See the [.travis.yml](https://github.com/olivere/elastic/blob/master/.travis.yml)
76file for the exact matrix and [Travis](https://travis-ci.org/olivere/elastic)
77for the results.
78
79Elasticsearch has quite a few features. A lot of them are
80not yet implemented in Elastic (see below for details).
81I add features and APIs as required. It's straightforward
82to implement missing pieces. I'm accepting pull requests :-)
83
84Having said that, I hope you find the project useful.
85
86
87## Usage
88
89The first thing you do is to create a Client. The client connects to
90Elasticsearch on http://127.0.0.1:9200 by default.
91
92You typically create one client for your app. Here's a complete example.
93
94```go
95// Create a client
96client, err := elastic.NewClient()
97if err != nil {
98 // Handle error
99}
100
101// Create an index
102_, err = client.CreateIndex("twitter").Do()
103if err != nil {
104 // Handle error
105 panic(err)
106}
107
108// Add a document to the index
109tweet := Tweet{User: "olivere", Message: "Take Five"}
110_, err = client.Index().
111 Index("twitter").
112 Type("tweet").
113 Id("1").
114 BodyJson(tweet).
115 Do()
116if err != nil {
117 // Handle error
118 panic(err)
119}
120
121// Search with a term query
122termQuery := elastic.NewTermQuery("user", "olivere")
123searchResult, err := client.Search().
124 Index("twitter"). // search in index "twitter"
125 Query(&termQuery). // specify the query
126 Sort("user", true). // sort by "user" field, ascending
127 From(0).Size(10). // take documents 0-9
128 Pretty(true). // pretty print request and response JSON
129 Do() // execute
130if err != nil {
131 // Handle error
132 panic(err)
133}
134
135// searchResult is of type SearchResult and returns hits, suggestions,
136// and all kinds of other information from Elasticsearch.
137fmt.Printf("Query took %d milliseconds\n", searchResult.TookInMillis)
138
139// Each is a convenience function that iterates over hits in a search result.
140// It makes sure you don't need to check for nil values in the response.
141// However, it ignores errors in serialization. If you want full control
142// over iterating the hits, see below.
143var ttyp Tweet
144for _, item := range searchResult.Each(reflect.TypeOf(ttyp)) {
145 if t, ok := item.(Tweet); ok {
146 fmt.Printf("Tweet by %s: %s\n", t.User, t.Message)
147 }
148}
149// TotalHits is another convenience function that works even when something goes wrong.
150fmt.Printf("Found a total of %d tweets\n", searchResult.TotalHits())
151
152// Here's how you iterate through results with full control over each step.
153if searchResult.Hits != nil {
154 fmt.Printf("Found a total of %d tweets\n", searchResult.Hits.TotalHits)
155
156 // Iterate through results
157 for _, hit := range searchResult.Hits.Hits {
158 // hit.Index contains the name of the index
159
160 // Deserialize hit.Source into a Tweet (could also be just a map[string]interface{}).
161 var t Tweet
162 err := json.Unmarshal(*hit.Source, &t)
163 if err != nil {
164 // Deserialization failed
165 }
166
167 // Work with tweet
168 fmt.Printf("Tweet by %s: %s\n", t.User, t.Message)
169 }
170} else {
171 // No hits
172 fmt.Print("Found no tweets\n")
173}
174
175// Delete the index again
176_, err = client.DeleteIndex("twitter").Do()
177if err != nil {
178 // Handle error
179 panic(err)
180}
181```
182
183See the [wiki](https://github.com/olivere/elastic/wiki) for more details.
184
185
186## API Status
187
188Here's the current API status.
189
190### APIs
191
192- [x] Search (most queries, filters, facets, aggregations etc. are implemented: see below)
193- [x] Index
194- [x] Get
195- [x] Delete
196- [x] Delete By Query
197- [x] Update
198- [x] Multi Get
199- [x] Bulk
200- [ ] Bulk UDP
201- [ ] Term vectors
202- [ ] Multi term vectors
203- [x] Count
204- [ ] Validate
205- [x] Explain
206- [x] Search
207- [ ] Search shards
208- [x] Search template
209- [x] Facets (most are implemented, see below)
210- [x] Aggregates (most are implemented, see below)
211- [x] Multi Search
212- [x] Percolate
213- [ ] More like this
214- [ ] Benchmark
215
216### Indices
217
218- [x] Create index
219- [x] Delete index
220- [x] Get index
221- [x] Indices exists
222- [x] Open/close index
223- [x] Put mapping
224- [x] Get mapping
225- [ ] Get field mapping
226- [x] Types exist
227- [x] Delete mapping
228- [x] Index aliases
229- [ ] Update indices settings
230- [x] Get settings
231- [ ] Analyze
232- [x] Index templates
233- [ ] Warmers
234- [ ] Status
235- [x] Indices stats
236- [ ] Indices segments
237- [ ] Indices recovery
238- [ ] Clear cache
239- [x] Flush
240- [x] Refresh
241- [x] Optimize
242- [ ] Upgrade
243
244### Snapshot and Restore
245
246- [ ] Snapshot
247- [ ] Restore
248- [ ] Snapshot status
249- [ ] Monitoring snapshot/restore progress
250- [ ] Partial restore
251
252### Cat APIs
253
254Not implemented. Those are better suited for operating with Elasticsearch
255on the command line.
256
257### Cluster
258
259- [x] Health
260- [x] State
261- [x] Stats
262- [ ] Pending cluster tasks
263- [ ] Cluster reroute
264- [ ] Cluster update settings
265- [ ] Nodes stats
266- [x] Nodes info
267- [ ] Nodes hot_threads
268- [ ] Nodes shutdown
269
270### Search
271
272- [x] Inner hits (for ES >= 1.5.0; see [docs](www.elastic.co/guide/en/elasticsearch/reference/1.5/search-request-inner-hits.html))
273
274### Query DSL
275
276#### Queries
277
278- [x] `match`
279- [x] `multi_match`
280- [x] `bool`
281- [x] `boosting`
282- [ ] `common_terms`
283- [ ] `constant_score`
284- [x] `dis_max`
285- [x] `filtered`
286- [x] `fuzzy_like_this_query` (`flt`)
287- [x] `fuzzy_like_this_field_query` (`flt_field`)
288- [x] `function_score`
289- [x] `fuzzy`
290- [ ] `geo_shape`
291- [x] `has_child`
292- [x] `has_parent`
293- [x] `ids`
294- [ ] `indices`
295- [x] `match_all`
296- [x] `mlt`
297- [x] `mlt_field`
298- [x] `nested`
299- [x] `prefix`
300- [x] `query_string`
301- [x] `simple_query_string`
302- [x] `range`
303- [x] `regexp`
304- [ ] `span_first`
305- [ ] `span_multi_term`
306- [ ] `span_near`
307- [ ] `span_not`
308- [ ] `span_or`
309- [ ] `span_term`
310- [x] `term`
311- [x] `terms`
312- [ ] `top_children`
313- [x] `wildcard`
314- [x] `minimum_should_match`
315- [ ] `multi_term_query_rewrite`
316- [x] `template_query`
317
318#### Filters
319
320- [x] `and`
321- [x] `bool`
322- [x] `exists`
323- [ ] `geo_bounding_box`
324- [x] `geo_distance`
325- [ ] `geo_distance_range`
326- [x] `geo_polygon`
327- [ ] `geoshape`
328- [ ] `geohash`
329- [x] `has_child`
330- [x] `has_parent`
331- [x] `ids`
332- [ ] `indices`
333- [x] `limit`
334- [x] `match_all`
335- [x] `missing`
336- [x] `nested`
337- [x] `not`
338- [x] `or`
339- [x] `prefix`
340- [x] `query`
341- [x] `range`
342- [x] `regexp`
343- [ ] `script`
344- [x] `term`
345- [x] `terms`
346- [x] `type`
347
348### Facets
349
350- [x] Terms
351- [x] Range
352- [x] Histogram
353- [x] Date Histogram
354- [x] Filter
355- [x] Query
356- [x] Statistical
357- [x] Terms Stats
358- [x] Geo Distance
359
360### Aggregations
361
362- [x] min
363- [x] max
364- [x] sum
365- [x] avg
366- [x] stats
367- [x] extended stats
368- [x] value count
369- [x] percentiles
370- [x] percentile ranks
371- [x] cardinality
372- [x] geo bounds
373- [x] top hits
374- [ ] scripted metric
375- [x] global
376- [x] filter
377- [x] filters
378- [x] missing
379- [x] nested
380- [x] reverse nested
381- [x] children
382- [x] terms
383- [x] significant terms
384- [x] range
385- [x] date range
386- [x] ipv4 range
387- [x] histogram
388- [x] date histogram
389- [x] geo distance
390- [x] geohash grid
391
392### Sorting
393
394- [x] Sort by score
395- [x] Sort by field
396- [x] Sort by geo distance
397- [x] Sort by script
398
399### Scan
400
401Scrolling through documents (e.g. `search_type=scan`) are implemented via
402the `Scroll` and `Scan` services. The `ClearScroll` API is implemented as well.
403
404## How to contribute
405
406Read [the contribution guidelines](https://github.com/olivere/elastic/blob/master/CONTRIBUTING.md).
407
408## Credits
409
410Thanks a lot for the great folks working hard on
411[Elasticsearch](http://www.elasticsearch.org/)
412and
413[Go](http://www.golang.org/).
414
415## LICENSE
416
417MIT-LICENSE. See [LICENSE](http://olivere.mit-license.org/)
418or the LICENSE file provided in the repository for details.
419
420