Algolia

This is an Elixir implementation of the Algolia search API.

To use it, add the following to your dependencies:

defp deps do
  [{:algolia, "~> 0.9.0", hex: :algolia_ex}]
end

Configuration

Using environment variables:

ALGOLIA_APPLICATION_ID=YOUR_APPLICATION_ID
ALGOLIA_API_KEY=YOUR_API_KEY

Using config:

config :algolia,
  application_id: "YOUR_APPLICATION_ID",
  api_key: "YOUR_API_KEY"

Note: You must use admin API key rather than a search API key to enable write access.

Return values

All responses are deserialized into maps before returning one of these responses:

• {:ok, response}
• {:error, error_code, response}
• {:error, "Cannot connect to Algolia"}: The client implements retry strategy on all Algolia hosts with increasing timeout. It should only return this error when it has tried all 4 hosts. More details here.

Examples

Creating a client

All API function that make requests require a client.

client = Algolia.new()

Searching

Searching an index

Algolia.search(client, "my_index", "some query")

With options:

Algolia.search(client, "my_index", "some query", attributesToRetrieve: "firstname", hitsPerPage: 20)

See all available search options here.

Browsing an index

Browsing is like search but skips most ranking and allows fetching more results at once.

Algolia.browse(client, "my_index", query: "some query", filter: "color:red")

Multiple queries at once

Algolia.multi(client, [
  %{index_name: "my_index1", query: "search query"},
  %{index_name: "my_index2", query: "another query", hitsPerPage: 3},
  %{index_name: "my_index3", query: "3rd query", tagFilters: "promotion"}
])

You can specify a strategy to optimize your multiple queries:

• :none: Execute the sequence of queries until the end.
• stop_if_enough_matches: Execute the sequence of queries until the number of hits is reached by the sum of hits.

Algolia.multi(client, [query1, query2], strategy: :stop_if_enough_matches)

Saving

All save_* operations will overwrite the object at the objectID.

Save a single object to index without specifying objectID. You must have objectID inside object, or use the id_attribute option (see below).

Algolia.save_object(client, "my_index", %{objectID: "1"})

Save a single object with a given objectID:

Algolia.save_object(client, "my_index", %{title: "hello"}, "12345")

Save multiple objects to an index:

Algolia.save_objects(client, "my_index", [%{objectID: "1"}, %{objectID: "2"}])

Updating

Partially update a single object:

Algolia.partial_update_object(client, "my_index", %{title: "hello"}, "12345")

Update multiple objects. You must have objectID in each object, or use the id_attribute option (see below).

Algolia.partial_update_objects(client, "my_index", [%{objectID: "1"}, %{objectID: "2"}])

Partial update by default creates a new object if an object does not exist at the objectID. You can turn this off by passing false to the :upsert? option.

Algolia.partial_update_object(client, "my_index", %{title: "hello"}, "12345", upsert?: false)
Algolia.partial_update_objects(client, "my_index", [%{id: "1"}, %{id: "2"}], id_attribute: :id, upsert?: false)

id_attribute option

All write functions such as save_object and partial_update_object come with an id_attribute option that lets you specify the objectID from an existing field in the object, so you do not have to generate it yourself.

Algolia.save_object(client, "my_index", %{id: "2"}, id_attribute: :id)

It also works for batch operations, such as save_objects and partial_update_objects:

Algolia.save_objects(client, "my_index", [%{id: "1"}, %{id: "2"}], id_attribute: :id)

Wait for task

All write operations can be waited on by simply piping the response into wait/1:

client
|> Algolia.save_object("my_index", %{id: "123"})
|> Algolia.wait(client)

The client polls the server to check the status of the task. You can specify a time (in milliseconds) between each tick of the poll; the default is 1000ms (1 second).

client
|> Algolia.save_object("my_index", %{id: "123"})
|> Algolia.wait(client, retry_delay: 2_000)

You can also explicitly pass a taskID to wait_task:

{:ok, %{"taskID" => task_id, "indexName" => index}}
  = Algolia.save_object(client, "my_index", %{id: "123"})

Algolia.wait_task(client, index, task_id)

Optionally including the poll interval:

Algolia.wait(client, index, task_id, retry_delay: 2_000)

Index related operations

Listing all indexes

Algolia.list_indexes(client)

Move an index

Algolia.move_index(client, source_index, destination_index)

Copy an index

Algolia.copy_index(client, source_index, destination_index)

Clear an index

Algolia.clear_index(client, index)

Settings

Get index settings

Algolia.get_settings(client, index)

Example response:

{:ok,
  %{"minWordSizefor1Typo" => 4,
    "minWordSizefor2Typos" => 8,
    "hitsPerPage" => 20,
    "attributesToIndex" => nil,
    "attributesToRetrieve" => nil,
    "attributesToSnippet" => nil,
    "attributesToHighlight" => nil,
    "ranking" => [
        "typo",
        "geo",
        "words",
        "proximity",
        "attribute",
        "exact",
        "custom"
    ],
    "customRanking" => nil,
    "separatorsToIndex" => "",
    "queryType" => "prefixAll"}}

Update index settings

Algolia.set_settings(client, index, %{"hitsPerPage" => 20})

> {:ok, %{"updatedAt" => "2013-08-21T13:20:18.960Z",
          "taskID" => 10210332.
          "indexName" => "my_index"}}

Insights

Push events

Algolia.push_events(client, [
  %{
    "eventType" => "click",
    "eventName" => "Product Clicked",
    "index" => "products",
    "userToken" => "user-123456",
    "objectIDs" => ["9780545139700", "9780439784542"],
    "queryID" => "43b15df305339e827f0ac0bdc5ebcaa7",
    "positions" => [7, 6]
  }
])