| 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 |
[](https://travis-ci.org/olivere/elastic) |
| 7 |
[](http://godoc.org/gopkg.in/olivere/elastic.v5) |
| 8 |
[](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. |