elastic

Deprecated: Use the official Elasticsearch client for Go at https://github.com/elastic/go-elasticsearch

7,399

1,147

7,399

111

View on GitHub

Top Related Projects

go-elasticsearch

5,626

The official Go client for Elasticsearch

bleve

9,971

A modern text/numeric/geo-spatial/vector indexing library for go

elasticsql

1,162

convert sql to elasticsearch DSL in golang(go)

cuckoofilter

1,108

Cuckoo Filter: Practically Better Than Bloom

Quick Overview

Olivere/elastic is a robust and feature-rich Go client for Elasticsearch. It provides a comprehensive set of APIs to interact with Elasticsearch, allowing developers to perform various operations such as indexing, searching, and managing documents and indices in Elasticsearch clusters.

Pros

Extensive API coverage for Elasticsearch operations
Well-documented with numerous examples and use cases
Actively maintained and regularly updated
Supports multiple versions of Elasticsearch

Cons

Learning curve can be steep for beginners
Large codebase may lead to longer compilation times
Some advanced features may require in-depth knowledge of Elasticsearch

Code Examples

Creating a new client:

client, err := elastic.NewClient(elastic.SetURL("http://localhost:9200"))
if err != nil {
    log.Fatalf("Error creating client: %s", err)
}

Indexing a document:

doc := map[string]interface{}{
    "title":   "Test Document",
    "content": "This is a test document.",
}
_, err = client.Index().
    Index("my_index").
    Id("1").
    BodyJson(doc).
    Do(context.Background())

Performing a search:

searchResult, err := client.Search().
    Index("my_index").
    Query(elastic.NewMatchQuery("content", "test")).
    Do(context.Background())

Aggregating data:

aggs := elastic.NewTermsAggregation().Field("category")
searchResult, err := client.Search().
    Index("my_index").
    Aggregation("categories", aggs).
    Do(context.Background())

Getting Started

To start using olivere/elastic in your Go project:

Install the package:
```
go get github.com/olivere/elastic/v7
```
Import the package in your Go code:
```
import "github.com/olivere/elastic/v7"
```

Create a new client and start using the API:

client, err := elastic.NewClient(elastic.SetURL("http://localhost:9200"))
if err != nil {
    log.Fatalf("Error creating client: %s", err)
}

// Use the client to interact with Elasticsearch
// For example, ping the cluster
info, code, err := client.Ping("http://localhost:9200").Do(context.Background())
if err != nil {
    log.Fatalf("Error pinging Elasticsearch: %s", err)
}
fmt.Printf("Elasticsearch returned with code %d and version %s\n", code, info.Version.Number)

Remember to handle errors appropriately and refer to the official documentation for more detailed usage instructions and advanced features.

Competitor Comparisons

go-elasticsearch

5,626

The official Go client for Elasticsearch

Pros of go-elasticsearch

Official Elasticsearch client, ensuring better compatibility and support
More lightweight and flexible, allowing for lower-level control
Supports all Elasticsearch API endpoints

Cons of go-elasticsearch

Less abstraction, requiring more manual work for complex operations
Steeper learning curve for developers new to Elasticsearch

Code Comparison

elastic:

client, err := elastic.NewClient()
searchResult, err := client.Search().
    Index("tweets").
    Query(elastic.NewMatchQuery("message", "elasticsearch")).
    Do(context.Background())

go-elasticsearch:

es, err := elasticsearch.NewDefaultClient()
res, err := es.Search(
    es.Search.WithIndex("tweets"),
    es.Search.WithBody(strings.NewReader(`{"query":{"match":{"message":"elasticsearch"}}}`)),
)

Summary

go-elasticsearch offers official support and comprehensive API coverage but requires more manual work. elastic provides higher-level abstractions, making it easier to use for common operations but potentially limiting flexibility for advanced use cases. The choice between the two depends on the specific project requirements and developer preferences.

bleve

9,971

A modern text/numeric/geo-spatial/vector indexing library for go

Pros of Bleve

Pure Go implementation, making it easier to integrate into Go projects
Supports multiple storage engines, including in-memory and disk-based options
Offers full-text search capabilities without external dependencies

Cons of Bleve

Less mature and potentially less feature-rich compared to Elasticsearch
Smaller community and ecosystem than Elastic
May require more manual configuration for advanced use cases

Code Comparison

Bleve:

index, _ := bleve.New("example.bleve", mapping)
doc := struct{ Name string }{"John Doe"}
index.Index("1", doc)
query := bleve.NewMatchQuery("john")
searchRequest := bleve.NewSearchRequest(query)
searchResults, _ := index.Search(searchRequest)

Elastic:

client, _ := elastic.NewClient()
doc := struct{ Name string }{"John Doe"}
_, _ = client.Index().Index("example").Id("1").BodyJson(doc).Do(context.Background())
query := elastic.NewMatchQuery("name", "john")
searchResult, _ := client.Search().Index("example").Query(query).Do(context.Background())

Both libraries provide similar functionality for indexing and searching documents, but Elastic is more tightly coupled with Elasticsearch, while Bleve offers a standalone solution with more flexibility in storage options.

elasticsql

1,162

convert sql to elasticsearch DSL in golang(go)

Pros of elasticsql

Focuses specifically on converting SQL to Elasticsearch DSL, making it easier for SQL-familiar developers to work with Elasticsearch
Lightweight and focused on a single task, potentially easier to integrate into existing projects
Supports a variety of SQL operations, including SELECT, WHERE, ORDER BY, and LIMIT

Cons of elasticsql

Limited to SQL-to-Elasticsearch conversion, lacking broader Elasticsearch client functionality
May not support all complex Elasticsearch query types or advanced features
Less actively maintained compared to elastic, with fewer contributors and updates

Code Comparison

elasticsql:

sql := "SELECT * FROM test WHERE a=1 and b = 2 ORDER BY c DESC LIMIT 100"
esQuery, esType, _ := elasticsql.Convert(sql)

elastic:

query := elastic.NewBoolQuery().
    Must(elastic.NewTermQuery("a", 1)).
    Must(elastic.NewTermQuery("b", 2))
result, err := client.Search().
    Index("test").
    Query(query).
    Sort("c", false).
    Size(100).
    Do(context.Background())

The elasticsql example shows a simple SQL-to-Elasticsearch conversion, while the elastic example demonstrates direct query construction using the client library.

cuckoofilter

1,108

Cuckoo Filter: Practically Better Than Bloom

Pros of cuckoofilter

Lightweight and focused on a single data structure (Cuckoo filter)
Efficient space usage and fast lookups for approximate set membership
Simple API for adding, deleting, and checking membership

Cons of cuckoofilter

Limited functionality compared to elastic's full-featured Elasticsearch client
Not suitable for complex search and analytics operations
Lacks built-in support for distributed systems and clustering

Code comparison

cuckoofilter:

cf := cuckoo.NewFilter(1000)
cf.Insert([]byte("item"))
cf.Lookup([]byte("item"))
cf.Delete([]byte("item"))

elastic:

client, _ := elastic.NewClient()
result, _ := client.Index().
    Index("tweets").
    Type("tweet").
    Id("1").
    BodyJson(tweet).
    Do(context.Background())

Summary

cuckoofilter is a specialized library for implementing Cuckoo filters, offering efficient set membership operations. elastic is a comprehensive Elasticsearch client with a wide range of features for search and analytics. While cuckoofilter excels in its specific use case, elastic provides broader functionality for complex data operations and distributed systems.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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 Go modules for the 7.x release (or later) or a dependency manager like dep for earlier releases.

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.v7) are actively being worked on and can break at any time. If you want to use stable versions of Elastic, please use Go modules.

Here's the version matrix:

Elasticsearch version	Elastic version	Package URL	Remarks
7.x Â Â Â Â Â Â Â Â Â	7.0 Â Â Â Â Â Â	`github.com/olivere/elastic/v7` (source doc)	Use Go modules.
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 7.0.0 and want to use Elastic. As listed above, you should use Elastic 7.0 (code is in release-branch.v7).

To use the required version of Elastic in your application, you should use Go modules to manage dependencies. Make sure to use a version such as 7.0.0 or later.

To use Elastic, import:

import "github.com/olivere/elastic/v7"

Elastic 7.0

Elastic 7.0 targets Elasticsearch 7.x which was released on April 10th 2019.

As always with major version, there are a lot of breaking changes. We will use this as an opportunity to clean up and refactor Elastic, as we already did in earlier (major) releases.

Elastic 6.0

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

Notice that there are 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 starting with Elasticsearch 0.90 up to recent 7.x versions. We recently switched to GitHub Actions for testing. Before that, we used Travis CI successfully for years).

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 v6.

Here are a few tips on how to get used to Elastic:

Head over to the Wiki for detailed information and topics like e.g. how to add a middleware or how to connect to AWS.
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.
The recipes contains small examples on how to implement something, e.g. bulk indexing, scrolling etc.

API Status

Document APIs

Search APIs

Aggregations

Indices APIs

Index Lifecycle Management APIs

cat APIs

Cluster APIs

Rollup APIs (XPack)

Query DSL

Modules

Snapshot and Restore
- Repositories
- Snapshot get
- Snapshot create
- Snapshot delete
- Restore
- Snapshot status
- Monitoring snapshot/restore status
- Stopping currently running snapshot and restore
Scripting
- GetScript
- PutScript
- DeleteScript

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.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot