Debian Codegraph @

README.md

raw
1 # Elastic
2
3 Elastic 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=release-branch.v5)](https://travis-ci.org/olivere/elastic)
7 [![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](http://godoc.org/gopkg.in/olivere/elastic.v5)
8 [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/olivere/elastic/master/LICENSE)
9
10 See the [wiki](https://github.com/olivere/elastic/wiki) for additional information about Elastic.
11
12
13 ## Releases
14
15 **The release branches (e.g. [`release-branch.v5`](https://github.com/olivere/elastic/tree/release-branch.v5))
16 are actively being worked on and can break at any time.
17 If you want to use stable versions of Elastic, please use the packages released via [gopkg.in](https://gopkg.in).**
18
19 Here's the version matrix:
20
21 Elasticsearch version | Elastic version -| Package URL
22 ----------------------|------------------|------------
23 5.x | 5.0 | [`gopkg.in/olivere/elastic.v5`](https://gopkg.in/olivere/elastic.v5) ([source](https://github.com/olivere/elastic/tree/release-branch.v5) [doc](http://godoc.org/gopkg.in/olivere/elastic.v5))
24 2.x | 3.0 | [`gopkg.in/olivere/elastic.v3`](https://gopkg.in/olivere/elastic.v3) ([source](https://github.com/olivere/elastic/tree/release-branch.v3) [doc](http://godoc.org/gopkg.in/olivere/elastic.v3))
25 1.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))
26 0.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))
27
28 **Example:**
29
30 You have installed Elasticsearch 5.0.0 and want to use Elastic.
31 As listed above, you should use Elastic 5.0.
32 So you first install the stable release of Elastic 5.0 from gopkg.in.
33
34 ```sh
35 $ go get gopkg.in/olivere/elastic.v5
36 ```
37
38 You then import it with this import path:
39
40 ```go
41 import elastic "gopkg.in/olivere/elastic.v5"
42 ```
43
44 ### Elastic 5.0
45
46 Elastic 5.0 targets Elasticsearch 5.0.0 and later. Elasticsearch 5.0.0 was
47 [released on 26th October 2016](https://www.elastic.co/blog/elasticsearch-5-0-0-released).
48
49 Notice that there are will be a lot of [breaking changes in Elasticsearch 5.0](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/breaking-changes-5.0.html)
50 and we used this as an opportunity to [clean up and refactor Elastic](https://github.com/olivere/elastic/blob/release-branch.v5/CHANGELOG-5.0.md)
51 as we did in the transition from Elastic 2.0 (for Elasticsearch 1.x) to Elastic 3.0 (for Elasticsearch 2.x).
52
53 Furthermore, the jump in version numbers will give us a chance to be in sync with the Elastic Stack.
54
55 ### Elastic 3.0
56
57 Elastic 3.0 targets Elasticsearch 2.x and is published via [`gopkg.in/olivere/elastic.v3`](https://gopkg.in/olivere/elastic.v3).
58
59 Elastic 3.0 will only get critical bug fixes. You should update to a recent version.
60
61 ### Elastic 2.0
62
63 Elastic 2.0 targets Elasticsearch 1.x and is published via [`gopkg.in/olivere/elastic.v2`](https://gopkg.in/olivere/elastic.v2).
64
65 Elastic 2.0 will only get critical bug fixes. You should update to a recent version.
66
67 ### Elastic 1.0
68
69 Elastic 1.0 is deprecated. You should really update Elasticsearch and Elastic
70 to a recent version.
71
72 However, if you cannot update for some reason, don't worry. Version 1.0 is
73 still available. All you need to do is go-get it and change your import path
74 as described above.
75
76
77 ## Status
78
79 We use Elastic in production since 2012. Elastic is stable but the API changes
80 now and then. We strive for API compatibility.
81 However, Elasticsearch sometimes introduces [breaking changes](https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking-changes.html)
82 and we sometimes have to adapt.
83
84 Having said that, there have been no big API changes that required you
85 to rewrite your application big time. More often than not it's renaming APIs
86 and adding/removing features so that Elastic is in sync with Elasticsearch.
87
88 Elastic has been used in production with the following Elasticsearch versions:
89 0.90, 1.0-1.7, and 2.0-2.4.1. Furthermore, we use [Travis CI](https://travis-ci.org/)
90 to test Elastic with the most recent versions of Elasticsearch and Go.
91 See the [.travis.yml](https://github.com/olivere/elastic/blob/master/.travis.yml)
92 file for the exact matrix and [Travis](https://travis-ci.org/olivere/elastic)
93 for the results.
94
95 Elasticsearch has quite a few features. Most of them are implemented
96 by Elastic. I add features and APIs as required. It's straightforward
97 to implement missing pieces. I'm accepting pull requests :-)
98
99 Having said that, I hope you find the project useful.
100
101
102 ## Getting Started
103
104 The first thing you do is to create a [Client](https://github.com/olivere/elastic/blob/master/client.go).
105 The client connects to Elasticsearch on `http://127.0.0.1:9200` by default.
106
107 You typically create one client for your app. Here's a complete example of
108 creating a client, creating an index, adding a document, executing a search etc.
109
110 An example is available [here](https://olivere.github.io/elastic/)
111
112 Here's a [link to a complete working example for v3](https://gist.github.com/olivere/114347ff9d9cfdca7bdc0ecea8b82263).
113
114 See the [wiki](https://github.com/olivere/elastic/wiki) for more details.
115
116
117 ## API Status
118
119 ### Document APIs
120
121 - [x] Index API
122 - [x] Get API
123 - [x] Delete API
124 - [x] Delete By Query API
125 - [x] Update API
126 - [x] Update By Query API
127 - [x] Multi Get API
128 - [x] Bulk API
129 - [x] Reindex API
130 - [x] Term Vectors
131 - [x] Multi termvectors API
132
133 ### Search APIs
134
135 - [x] Search
136 - [x] Search Template
137 - [ ] Multi Search Template
138 - [x] Search Shards API
139 - [x] Suggesters
140 - [x] Term Suggester
141 - [x] Phrase Suggester
142 - [x] Completion Suggester
143 - [x] Context Suggester
144 - [x] Multi Search API
145 - [x] Count API
146 - [ ] Search Exists API
147 - [x] Validate API
148 - [x] Explain API
149 - [x] Profile API
150 - [x] Field Capabilities API
151 - [x] Field Stats API
152
153 ### Aggregations
154
155 - Metrics Aggregations
156 - [x] Avg
157 - [x] Cardinality
158 - [x] Extended Stats
159 - [x] Geo Bounds
160 - [x] Geo Centroid
161 - [x] Max
162 - [x] Min
163 - [x] Percentiles
164 - [x] Percentile Ranks
165 - [ ] Scripted Metric
166 - [x] Stats
167 - [x] Sum
168 - [x] Top Hits
169 - [x] Value Count
170 - Bucket Aggregations
171 - [x] Adjacency Matrix
172 - [x] Children
173 - [x] Date Histogram
174 - [x] Date Range
175 - [x] Diversified Sampler
176 - [x] Filter
177 - [x] Filters
178 - [x] Geo Distance
179 - [ ] GeoHash Grid
180 - [x] Global
181 - [x] Histogram
182 - [x] IP Range
183 - [x] Missing
184 - [x] Nested
185 - [x] Range
186 - [x] Reverse Nested
187 - [x] Sampler
188 - [x] Significant Terms
189 - [x] Terms
190 - Pipeline Aggregations
191 - [x] Avg Bucket
192 - [x] Derivative
193 - [x] Max Bucket
194 - [x] Min Bucket
195 - [x] Sum Bucket
196 - [x] Stats Bucket
197 - [ ] Extended Stats Bucket
198 - [x] Percentiles Bucket
199 - [x] Moving Average
200 - [x] Cumulative Sum
201 - [x] Bucket Script
202 - [x] Bucket Selector
203 - [x] Serial Differencing
204 - [x] Matrix Aggregations
205 - [x] Matrix Stats
206 - [x] Aggregation Metadata
207
208 ### Indices APIs
209
210 - [x] Create Index
211 - [x] Delete Index
212 - [x] Get Index
213 - [x] Indices Exists
214 - [x] Open / Close Index
215 - [x] Shrink Index
216 - [x] Rollover Index
217 - [x] Put Mapping
218 - [x] Get Mapping
219 - [x] Get Field Mapping
220 - [x] Types Exists
221 - [x] Index Aliases
222 - [x] Update Indices Settings
223 - [x] Get Settings
224 - [x] Analyze
225 - [x] Index Templates
226 - [ ] Shadow Replica Indices
227 - [x] Indices Stats
228 - [x] Indices Segments
229 - [ ] Indices Recovery
230 - [ ] Indices Shard Stores
231 - [ ] Clear Cache
232 - [x] Flush
233 - [x] Refresh
234 - [x] Force Merge
235 - [ ] Upgrade
236
237 ### cat APIs
238
239 The cat APIs are not implemented as of now. We think they are better suited for operating with Elasticsearch on the command line.
240
241 - [ ] cat aliases
242 - [ ] cat allocation
243 - [ ] cat count
244 - [ ] cat fielddata
245 - [ ] cat health
246 - [ ] cat indices
247 - [ ] cat master
248 - [ ] cat nodeattrs
249 - [ ] cat nodes
250 - [ ] cat pending tasks
251 - [ ] cat plugins
252 - [ ] cat recovery
253 - [ ] cat repositories
254 - [ ] cat thread pool
255 - [ ] cat shards
256 - [ ] cat segments
257 - [ ] cat snapshots
258
259 ### Cluster APIs
260
261 - [x] Cluster Health
262 - [x] Cluster State
263 - [x] Cluster Stats
264 - [ ] Pending Cluster Tasks
265 - [ ] Cluster Reroute
266 - [ ] Cluster Update Settings
267 - [x] Nodes Stats
268 - [x] Nodes Info
269 - [x] Task Management API
270 - [ ] Nodes hot_threads
271 - [ ] Cluster Allocation Explain API
272
273 ### Query DSL
274
275 - [x] Match All Query
276 - [x] Inner hits
277 - Full text queries
278 - [x] Match Query
279 - [x] Match Phrase Query
280 - [x] Match Phrase Prefix Query
281 - [x] Multi Match Query
282 - [x] Common Terms Query
283 - [x] Query String Query
284 - [x] Simple Query String Query
285 - Term level queries
286 - [x] Term Query
287 - [x] Terms Query
288 - [x] Range Query
289 - [x] Exists Query
290 - [x] Prefix Query
291 - [x] Wildcard Query
292 - [x] Regexp Query
293 - [x] Fuzzy Query
294 - [x] Type Query
295 - [x] Ids Query
296 - Compound queries
297 - [x] Constant Score Query
298 - [x] Bool Query
299 - [x] Dis Max Query
300 - [x] Function Score Query
301 - [x] Boosting Query
302 - [x] Indices Query
303 - Joining queries
304 - [x] Nested Query
305 - [x] Has Child Query
306 - [x] Has Parent Query
307 - [x] Parent Id Query
308 - Geo queries
309 - [ ] GeoShape Query
310 - [x] Geo Bounding Box Query
311 - [x] Geo Distance Query
312 - [ ] Geo Distance Range Query
313 - [x] Geo Polygon Query
314 - [ ] Geohash Cell Query
315 - Specialized queries
316 - [x] More Like This Query
317 - [x] Template Query
318 - [x] Script Query
319 - [x] Percolate Query
320 - Span queries
321 - [ ] Span Term Query
322 - [ ] Span Multi Term Query
323 - [ ] Span First Query
324 - [ ] Span Near Query
325 - [ ] Span Or Query
326 - [ ] Span Not Query
327 - [ ] Span Containing Query
328 - [ ] Span Within Query
329 - [ ] Span Field Masking Query
330 - [ ] Minimum Should Match
331 - [ ] Multi Term Query Rewrite
332
333 ### Modules
334
335 - Snapshot and Restore
336 - [x] Repositories
337 - [ ] Snapshot
338 - [ ] Restore
339 - [ ] Snapshot status
340 - [ ] Monitoring snapshot/restore status
341 - [ ] Stopping currently running snapshot and restore
342
343 ### Sorting
344
345 - [x] Sort by score
346 - [x] Sort by field
347 - [x] Sort by geo distance
348 - [x] Sort by script
349 - [x] Sort by doc
350
351 ### Scrolling
352
353 Scrolling is supported via a `ScrollService`. It supports an iterator-like interface.
354 The `ClearScroll` API is implemented as well.
355
356 A pattern for [efficiently scrolling in parallel](https://github.com/olivere/elastic/wiki/ScrollParallel)
357 is described in the [Wiki](https://github.com/olivere/elastic/wiki).
358
359 ## How to contribute
360
361 Read [the contribution guidelines](https://github.com/olivere/elastic/blob/master/CONTRIBUTING.md).
362
363 ## Credits
364
365 Thanks a lot for the great folks working hard on
366 [Elasticsearch](https://www.elastic.co/products/elasticsearch)
367 and
368 [Go](https://golang.org/).
369
370 Elastic uses portions of the
371 [uritemplates](https://github.com/jtacoma/uritemplates) library
372 by Joshua Tacoma,
373 [backoff](https://github.com/cenkalti/backoff) by Cenk Altı and
374 [leaktest](https://github.com/fortytw2/leaktest) by Ian Chiles.
375
376 ## LICENSE
377
378 MIT-LICENSE. See [LICENSE](http://olivere.mit-license.org/)
379 or the LICENSE file provided in the repository for details.