https://github.com/breakroom/snap
An Elasticsearch/OpenSearch client for Elixir
https://github.com/breakroom/snap
elasticsearch elasticsearch-client elixir opensearch opensearch-client search
Last synced: 10 months ago
JSON representation
An Elasticsearch/OpenSearch client for Elixir
- Host: GitHub
- URL: https://github.com/breakroom/snap
- Owner: breakroom
- License: mit
- Created: 2020-12-31T11:20:27.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-30T10:17:23.000Z (over 1 year ago)
- Last Synced: 2024-10-30T03:44:25.601Z (about 1 year ago)
- Topics: elasticsearch, elasticsearch-client, elixir, opensearch, opensearch-client, search
- Language: Elixir
- Homepage:
- Size: 313 KB
- Stars: 74
- Watchers: 7
- Forks: 28
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Snap
[](https://hex.pm/packages/snap)
Snap is an Elasticsearch/OpenSearch client. It provides a flexible, performant API on
top of your Elasticsearch cluster, supporting high level features like
versioned index management, while also providing a convenient interface into
low level operations.
See the full [API docs](https://hexdocs.pm/snap).
## Features
- Versioned index management with zero-downtime hotswapping (compatible with [`elasticsearch`](https://github.com/danielberkompas/elasticsearch-elixir))
- Streaming bulk operations
- Connection pooling
- Telemetry events
- High level interface over the [Multi Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html)
## Installation
The package can be installed by adding `snap` to your list of dependencies in
`mix.exs`:
```elixir
def deps do
[
{:snap, "~> 0.12"},
{:finch, "~> 0.16"}, # By default, Snap uses Finch to make HTTP requests
]
end
```
Snap supports Elixir 1.16 or later.
## Usage
Implement your own cluster module, similar to an `Ecto.Repo`:
```elixir
defmodule MyApp.Cluster do
use Snap.Cluster, otp_app: :my_app
end
```
Configure it:
```elixir
config :my_app, MyApp.Cluster,
url: "http://localhost:9200",
username: "my_username",
password: "my_password"
```
Then wire it into your application supervisor:
```elixir
def start(_type, _args) do
children = [
{MyApp.Cluster, []}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
```
Now you can perform operations on your cluster:
```elixir
{:ok, %{"count" => count}} = MyApp.Cluster.get("/my-index/_count")
```
## Testing
If you want to test your app that uses this library, but don't want to have integration tests
with a Elasticsearch instance running in you local dev environment,
you can mock the responses using a custom HTTP client adapter.
Supposing you are using [mox](https://github.com/dashbitco/mox), you can do something like this:
```elixir
# in test_helper.exs
Mox.defmock(HTTPClientMock, for: Snap.HTTPClient)
Mox.stub(HTTPClientMock, :child_spec, fn _config -> :skip end)
# in config/test.exs
config :my_app, MyApp.Cluster, http_client_adapter: HTTPClientMock
# in a test file
Mox.expect(HTTPClientMock, :request, fn _cluster, _method, _url, _headers, _body, _opts
body = "{}" # valid json
{:ok, %Snap.HTTPClient.Response{status: 200, headers: [], body: body}}
end)
```
See the [API documentation](https://hexdocs.pm/snap) for more advanced features.