Elastic

This is a development branch that is actively being worked on. DO NOT USE IN PRODUCTION!

Elastic is an Elasticsearch client for the Go programming language.

See the wiki for additional information about Elastic.

Releases

The release branches (e.g. 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.

Here's the version matrix:

Elasticsearch version	Elastic version	Package URL	Remarks
6.x	6.0	`github.com/olivere/elastic` (source doc)	Use a dependency manager (see below).
5.x	5.0	`gopkg.in/olivere/elastic.v5` (source doc)	Actively maintained.
2.x	3.0	`gopkg.in/olivere/elastic.v3` (source doc)	Deprecated. Please update.
1.x	2.0	`gopkg.in/olivere/elastic.v2` (source doc)	Deprecated. Please update.
0.9-1.3	1.0	`gopkg.in/olivere/elastic.v1` (source doc)	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 or Glide to manage that dependency. Make sure to use a version such as ^6.0.0.

To use Elastic, simply import:

import "github.com/olivere/elastic"

Elastic 6.0

Elastic 6.0 targets Elasticsearch 6.x which was released on 14th November 2017.

Notice that there are will be a lot of breaking changes in Elasticsearch 6.0 and we used this as an opportunity to clean up and refactor Elastic 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.

Notice that there are will be a lot of breaking changes in Elasticsearch 5.0 and we used this as an opportunity to clean up and refactor Elastic 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.

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.

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 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 with the following Elasticsearch versions: 0.90, 1.0-1.7, and 2.0-2.4.1. Furthermore, we use Travis CI to test Elastic with the most recent versions of Elasticsearch and Go. See the .travis.yml file for the exact matrix and Travis 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. 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.

Here's a link to a complete working example for v3.

See the wiki for more details.

API Status

Document APIs

Search APIs

Aggregations

Indices APIs

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.

Cluster APIs

Query DSL

Modules

Snapshot and Restore
- Repositories
- Snapshot
- Restore
- Snapshot status
- Monitoring snapshot/restore status
- Stopping currently running snapshot and restore

Sorting

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 is described in the Wiki.

How to contribute

Read the contribution guidelines.

Credits

Thanks a lot for the great folks working hard on Elasticsearch and Go.

Elastic uses portions of the uritemplates library by Joshua Tacoma, backoff by Cenk Altı and leaktest by Ian Chiles.

LICENSE

MIT-LICENSE. See LICENSE or the LICENSE file provided in the repository for details.

semafor/elastic