408 lines
13 KiB
Markdown
408 lines
13 KiB
Markdown
# Elastic
|
||
|
||
**This is a development branch that is actively being worked on. DO NOT USE IN PRODUCTION! If you want to use stable versions of Elastic, please use a dependency manager like [dep](https://github.com/golang/dep).**
|
||
|
||
Elastic is an [Elasticsearch](http://www.elasticsearch.org/) client for the
|
||
[Go](http://www.golang.org/) programming language.
|
||
|
||
[](https://travis-ci.org/olivere/elastic)
|
||
[](http://godoc.org/github.com/olivere/elastic)
|
||
[](https://raw.githubusercontent.com/olivere/elastic/master/LICENSE)
|
||
|
||
See the [wiki](https://github.com/olivere/elastic/wiki) for additional information about Elastic.
|
||
|
||
<a href="https://www.buymeacoffee.com/Bjd96U8fm" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
|
||
|
||
|
||
## Releases
|
||
|
||
**The release branches (e.g. [`release-branch.v6`](https://github.com/olivere/elastic/tree/release-branch.v6))
|
||
are actively being worked on and can break at any time.
|
||
If you want to use stable versions of Elastic, please use a dependency manager like [dep](https://github.com/golang/dep).**
|
||
|
||
Here's the version matrix:
|
||
|
||
Elasticsearch version | Elastic version | Package URL | Remarks |
|
||
----------------------|------------------|-------------|---------|
|
||
6.x | 6.0 | [`github.com/olivere/elastic`](https://github.com/olivere/elastic) ([source](https://github.com/olivere/elastic/tree/release-branch.v6) [doc](http://godoc.org/github.com/olivere/elastic)) | Use a dependency manager (see below).
|
||
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)) | Actively maintained.
|
||
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)) | Deprecated. Please update.
|
||
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)) | Deprecated. Please update.
|
||
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)) | Deprecated. Please update.
|
||
|
||
**Example:**
|
||
|
||
You have installed Elasticsearch 6.0.0 and want to use Elastic.
|
||
As listed above, you should use Elastic 6.0.
|
||
|
||
To use the required version of Elastic in your application, it is strongly
|
||
advised to use a tool like
|
||
[dep](https://github.com/golang/dep)
|
||
or
|
||
[Go modules](https://github.com/golang/go/wiki/Modules)
|
||
to manage dependencies. Make sure to use a version such as `^6.0.0`.
|
||
|
||
To use Elastic, import:
|
||
|
||
```go
|
||
import "github.com/olivere/elastic"
|
||
```
|
||
|
||
### Elastic 6.0
|
||
|
||
Elastic 6.0 targets Elasticsearch 6.x which was [released on 14th November 2017](https://www.elastic.co/blog/elasticsearch-6-0-0-released).
|
||
|
||
Notice that there are a lot of [breaking changes in Elasticsearch 6.0](https://www.elastic.co/guide/en/elasticsearch/reference/6.2/breaking-changes-6.0.html)
|
||
and we used this as an opportunity to [clean up and refactor Elastic](https://github.com/olivere/elastic/blob/release-branch.v6/CHANGELOG-6.0.md)
|
||
as we did in the transition from earlier versions of Elastic.
|
||
|
||
### Elastic 5.0
|
||
|
||
Elastic 5.0 targets Elasticsearch 5.0.0 and later. Elasticsearch 5.0.0 was
|
||
[released on 26th October 2016](https://www.elastic.co/blog/elasticsearch-5-0-0-released).
|
||
|
||
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)
|
||
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)
|
||
as we did in the transition from Elastic 2.0 (for Elasticsearch 1.x) to Elastic 3.0 (for Elasticsearch 2.x).
|
||
|
||
Furthermore, the jump in version numbers will give us a chance to be in sync with the Elastic Stack.
|
||
|
||
### Elastic 3.0
|
||
|
||
Elastic 3.0 targets Elasticsearch 2.x and is published via [`gopkg.in/olivere/elastic.v3`](https://gopkg.in/olivere/elastic.v3).
|
||
|
||
Elastic 3.0 will only get critical bug fixes. You should update to a recent version.
|
||
|
||
### Elastic 2.0
|
||
|
||
Elastic 2.0 targets Elasticsearch 1.x and is published via [`gopkg.in/olivere/elastic.v2`](https://gopkg.in/olivere/elastic.v2).
|
||
|
||
Elastic 2.0 will only get critical bug fixes. You should update to a recent version.
|
||
|
||
### Elastic 1.0
|
||
|
||
Elastic 1.0 is deprecated. You should really update Elasticsearch and Elastic
|
||
to a recent version.
|
||
|
||
However, if you cannot update for some reason, don't worry. Version 1.0 is
|
||
still available. All you need to do is go-get it and change your import path
|
||
as described above.
|
||
|
||
|
||
## Status
|
||
|
||
We use Elastic in production since 2012. Elastic is stable but the API changes
|
||
now and then. We strive for API compatibility.
|
||
However, Elasticsearch sometimes introduces [breaking changes](https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking-changes.html)
|
||
and we sometimes have to adapt.
|
||
|
||
Having said that, there have been no big API changes that required you
|
||
to rewrite your application big time. More often than not it's renaming APIs
|
||
and adding/removing features so that Elastic is in sync with Elasticsearch.
|
||
|
||
Elastic has been used in production starting with Elasticsearch 0.90 up to recent 6.x
|
||
versions. Furthermore, we use [Travis CI](https://travis-ci.org/)
|
||
to test Elastic with the most recent versions of Elasticsearch and Go.
|
||
See the [.travis.yml](https://github.com/olivere/elastic/blob/master/.travis.yml)
|
||
file for the exact matrix and [Travis](https://travis-ci.org/olivere/elastic)
|
||
for the results.
|
||
|
||
Elasticsearch has quite a few features. Most of them are implemented
|
||
by Elastic. I add features and APIs as required. It's straightforward
|
||
to implement missing pieces. I'm accepting pull requests :-)
|
||
|
||
Having said that, I hope you find the project useful.
|
||
|
||
|
||
## Getting Started
|
||
|
||
The first thing you do is to create a [Client](https://github.com/olivere/elastic/blob/master/client.go).
|
||
The client connects to Elasticsearch on `http://127.0.0.1:9200` by default.
|
||
|
||
You typically create one client for your app. Here's a complete example of
|
||
creating a client, creating an index, adding a document, executing a search etc.
|
||
|
||
An example is available [here](https://olivere.github.io/elastic/).
|
||
|
||
Here's a [link to a complete working example for v6](https://gist.github.com/olivere/e4a376b4783c0914e44ea4f745ce2ebf).
|
||
|
||
Here are a few tips on how to get used to Elastic:
|
||
|
||
1. Head over to the [Wiki](https://github.com/olivere/elastic/wiki) for detailed information and
|
||
topics like e.g. [how to add a middleware](/olivere/elastic/wiki/HttpTransport)
|
||
or how to [connect to AWS](/olivere/elastic/wiki/Using-with-AWS-Elasticsearch-Service).
|
||
2. If you are unsure how to implement something, read the tests (all `_test.go` files).
|
||
They not only serve as a guard against changes, but also as a reference.
|
||
3. The [recipes](https://github.com/olivere/elastic/tree/release-branch.v6/recipes)
|
||
contains small examples on how to implement something, e.g. bulk indexing, scrolling etc.
|
||
|
||
|
||
## API Status
|
||
|
||
### Document APIs
|
||
|
||
- [x] Index API
|
||
- [x] Get API
|
||
- [x] Delete API
|
||
- [x] Delete By Query API
|
||
- [x] Update API
|
||
- [x] Update By Query API
|
||
- [x] Multi Get API
|
||
- [x] Bulk API
|
||
- [x] Reindex API
|
||
- [x] Term Vectors
|
||
- [x] Multi termvectors API
|
||
|
||
### Search APIs
|
||
|
||
- [x] Search
|
||
- [x] Search Template
|
||
- [ ] Multi Search Template
|
||
- [x] Search Shards API
|
||
- [x] Suggesters
|
||
- [x] Term Suggester
|
||
- [x] Phrase Suggester
|
||
- [x] Completion Suggester
|
||
- [x] Context Suggester
|
||
- [x] Multi Search API
|
||
- [x] Count API
|
||
- [x] Validate API
|
||
- [x] Explain API
|
||
- [x] Profile API
|
||
- [x] Field Capabilities API
|
||
|
||
### Aggregations
|
||
|
||
- Metrics Aggregations
|
||
- [x] Avg
|
||
- [x] Cardinality
|
||
- [x] Extended Stats
|
||
- [x] Geo Bounds
|
||
- [x] Geo Centroid
|
||
- [x] Max
|
||
- [x] Min
|
||
- [x] Percentiles
|
||
- [x] Percentile Ranks
|
||
- [ ] Scripted Metric
|
||
- [x] Stats
|
||
- [x] Sum
|
||
- [x] Top Hits
|
||
- [x] Value Count
|
||
- Bucket Aggregations
|
||
- [x] Adjacency Matrix
|
||
- [x] Children
|
||
- [x] Date Histogram
|
||
- [x] Date Range
|
||
- [x] Diversified Sampler
|
||
- [x] Filter
|
||
- [x] Filters
|
||
- [x] Geo Distance
|
||
- [ ] GeoHash Grid
|
||
- [x] Global
|
||
- [x] Histogram
|
||
- [x] IP Range
|
||
- [x] Missing
|
||
- [x] Nested
|
||
- [x] Range
|
||
- [x] Reverse Nested
|
||
- [x] Sampler
|
||
- [x] Significant Terms
|
||
- [x] Significant Text
|
||
- [x] Terms
|
||
- [x] Composite
|
||
- Pipeline Aggregations
|
||
- [x] Avg Bucket
|
||
- [x] Derivative
|
||
- [x] Max Bucket
|
||
- [x] Min Bucket
|
||
- [x] Sum Bucket
|
||
- [x] Stats Bucket
|
||
- [ ] Extended Stats Bucket
|
||
- [x] Percentiles Bucket
|
||
- [x] Moving Average
|
||
- [x] Cumulative Sum
|
||
- [x] Bucket Script
|
||
- [x] Bucket Selector
|
||
- [x] Bucket Sort
|
||
- [x] Serial Differencing
|
||
- [x] Matrix Aggregations
|
||
- [x] Matrix Stats
|
||
- [x] Aggregation Metadata
|
||
|
||
### Indices APIs
|
||
|
||
- [x] Create Index
|
||
- [x] Delete Index
|
||
- [x] Get Index
|
||
- [x] Indices Exists
|
||
- [x] Open / Close Index
|
||
- [x] Shrink Index
|
||
- [x] Rollover Index
|
||
- [x] Put Mapping
|
||
- [x] Get Mapping
|
||
- [x] Get Field Mapping
|
||
- [x] Types Exists
|
||
- [x] Index Aliases
|
||
- [x] Update Indices Settings
|
||
- [x] Get Settings
|
||
- [x] Analyze
|
||
- [x] Explain Analyze
|
||
- [x] Index Templates
|
||
- [x] Indices Stats
|
||
- [x] Indices Segments
|
||
- [ ] Indices Recovery
|
||
- [ ] Indices Shard Stores
|
||
- [ ] Clear Cache
|
||
- [x] Flush
|
||
- [x] Synced Flush
|
||
- [x] Refresh
|
||
- [x] Force Merge
|
||
|
||
### cat APIs
|
||
|
||
The cat APIs are not implemented as of now. We think they are better suited for operating with Elasticsearch on the command line.
|
||
|
||
- [ ] cat aliases
|
||
- [ ] cat allocation
|
||
- [ ] cat count
|
||
- [ ] cat fielddata
|
||
- [ ] cat health
|
||
- [ ] cat indices
|
||
- [ ] cat master
|
||
- [ ] cat nodeattrs
|
||
- [ ] cat nodes
|
||
- [ ] cat pending tasks
|
||
- [ ] cat plugins
|
||
- [ ] cat recovery
|
||
- [ ] cat repositories
|
||
- [ ] cat thread pool
|
||
- [ ] cat shards
|
||
- [ ] cat segments
|
||
- [ ] cat snapshots
|
||
- [ ] cat templates
|
||
|
||
### Cluster APIs
|
||
|
||
- [x] Cluster Health
|
||
- [x] Cluster State
|
||
- [x] Cluster Stats
|
||
- [ ] Pending Cluster Tasks
|
||
- [x] Cluster Reroute
|
||
- [ ] Cluster Update Settings
|
||
- [x] Nodes Stats
|
||
- [x] Nodes Info
|
||
- [ ] Nodes Feature Usage
|
||
- [ ] Remote Cluster Info
|
||
- [x] Task Management API
|
||
- [ ] Nodes hot_threads
|
||
- [ ] Cluster Allocation Explain API
|
||
|
||
### Query DSL
|
||
|
||
- [x] Match All Query
|
||
- [x] Inner hits
|
||
- Full text queries
|
||
- [x] Match Query
|
||
- [x] Match Phrase Query
|
||
- [x] Match Phrase Prefix Query
|
||
- [x] Multi Match Query
|
||
- [x] Common Terms Query
|
||
- [x] Query String Query
|
||
- [x] Simple Query String Query
|
||
- Term level queries
|
||
- [x] Term Query
|
||
- [x] Terms Query
|
||
- [x] Terms Set Query
|
||
- [x] Range Query
|
||
- [x] Exists Query
|
||
- [x] Prefix Query
|
||
- [x] Wildcard Query
|
||
- [x] Regexp Query
|
||
- [x] Fuzzy Query
|
||
- [x] Type Query
|
||
- [x] Ids Query
|
||
- Compound queries
|
||
- [x] Constant Score Query
|
||
- [x] Bool Query
|
||
- [x] Dis Max Query
|
||
- [x] Function Score Query
|
||
- [x] Boosting Query
|
||
- Joining queries
|
||
- [x] Nested Query
|
||
- [x] Has Child Query
|
||
- [x] Has Parent Query
|
||
- [x] Parent Id Query
|
||
- Geo queries
|
||
- [ ] GeoShape Query
|
||
- [x] Geo Bounding Box Query
|
||
- [x] Geo Distance Query
|
||
- [x] Geo Polygon Query
|
||
- Specialized queries
|
||
- [x] More Like This Query
|
||
- [x] Script Query
|
||
- [x] Percolate Query
|
||
- Span queries
|
||
- [ ] Span Term Query
|
||
- [ ] Span Multi Term Query
|
||
- [ ] Span First Query
|
||
- [ ] Span Near Query
|
||
- [ ] Span Or Query
|
||
- [ ] Span Not Query
|
||
- [ ] Span Containing Query
|
||
- [ ] Span Within Query
|
||
- [ ] Span Field Masking Query
|
||
- [ ] Minimum Should Match
|
||
- [ ] Multi Term Query Rewrite
|
||
|
||
### Modules
|
||
|
||
- Snapshot and Restore
|
||
- [x] Repositories
|
||
- [x] Snapshot
|
||
- [ ] Restore
|
||
- [ ] Snapshot status
|
||
- [ ] Monitoring snapshot/restore status
|
||
- [ ] Stopping currently running snapshot and restore
|
||
- Scripting
|
||
- [x] GetScript
|
||
- [x] PutScript
|
||
- [x] DeleteScript
|
||
|
||
### Sorting
|
||
|
||
- [x] Sort by score
|
||
- [x] Sort by field
|
||
- [x] Sort by geo distance
|
||
- [x] Sort by script
|
||
- [x] Sort by doc
|
||
|
||
### Scrolling
|
||
|
||
Scrolling is supported via a `ScrollService`. It supports an iterator-like interface.
|
||
The `ClearScroll` API is implemented as well.
|
||
|
||
A pattern for [efficiently scrolling in parallel](https://github.com/olivere/elastic/wiki/ScrollParallel)
|
||
is described in the [Wiki](https://github.com/olivere/elastic/wiki).
|
||
|
||
## How to contribute
|
||
|
||
Read [the contribution guidelines](https://github.com/olivere/elastic/blob/master/CONTRIBUTING.md).
|
||
|
||
## Credits
|
||
|
||
Thanks a lot for the great folks working hard on
|
||
[Elasticsearch](https://www.elastic.co/products/elasticsearch)
|
||
and
|
||
[Go](https://golang.org/).
|
||
|
||
Elastic uses portions of the
|
||
[uritemplates](https://github.com/jtacoma/uritemplates) library
|
||
by Joshua Tacoma,
|
||
[backoff](https://github.com/cenkalti/backoff) by Cenk Altı and
|
||
[leaktest](https://github.com/fortytw2/leaktest) by Ian Chiles.
|
||
|
||
## LICENSE
|
||
|
||
MIT-LICENSE. See [LICENSE](http://olivere.mit-license.org/)
|
||
or the LICENSE file provided in the repository for details.
|