sikanhe / algolia-elixir

Elixir implementation of Algolia search API

Algolia

This is the elixir implementation of Algolia search API, it is purely functional

Add to your dependencies

  defp deps do
    [{:algolia, "~> 0.8.0"}]
  end

(Pre-Elixir-1.4) Add :algolia to your applications

  def application do
    [applications: [:algolia]]
  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 instead of SEARCH API_KEY to enable write access

The Client

You don't need to initiate an index with this client unlike other OO Algolia clients. However, Most of the client search/write functions all use the syntax

operation(index, args....)

So you can easy emulate the index.function() syntax using piping

"my_index" |> operation(args)

Return values

All functions are serialized into maps before returning 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

Searching

Searching an index

    "my_index" |> search("some query")

With Options

    "my_index" |> search("some query", [attributesToRetrieve: "firstname", hitsPerPage: 20])

See all available search options here

Multiple queries at once

    multi([%{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.

    multi([query1, query2], strategy: :stop_if_enough_matches)

Saving

All save_* operations will overrides the object at the objectID

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

    "my_index" |> save_object(%{objectID: "1"})

Save a single object with a given objectID

    "my_index" |> save_object(%{title: "hello"}, "12345")

Save multiple objects to an index

    "my_index" |> save_objects([%{objectID: "1"}, %{objectID: "2"}])

Updating

Partially updates a single object

    "my_index" |> partial_update_object(%{title: "hello"}, "12345")

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

    "my_index" |> partial_update_objects([%{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

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

Bonus for this Elixir client only: id_attribute option

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

    "my_index" |> save_object(%{id: "2"}, id_attribute: :id)

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

    "my_index" |> save_objects([%{id: "1"}, %{id: "2"}], id_attribute: :id)

However, this cannot be used together with an ID specifying argument together

    "my_index" |> save_object(%{id: "1234"}, "1234", id_attribute: :id)
    > Error

Wait for task

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

    "my_index" |> save_object(%{id: "123"}) |> wait

Since the client polls the server to check for publishing status, You can specify a time between each tick of the poll, the default is 1000 ms

    "my_index" |> save_object(%{id: "123"}) |> wait(2_000)

You can also use the underlying wait_task function explicitly

    {:ok, %{"taskID" => task_id, "indexName" => index}}
      = "my_index" |> save_object(%{id: "123"}

    wait(index, task_id)

or with option

    wait(index, task_id, 2_000)

Index related operations

Listing all indexes

   list_indexes()

move_index/2

Moves an index to a new one

   move_index(source_index, destination_index)

copy_index/2

Copies an index to a new one

    copy_index(source_index, destination_index)

Clear an index

    clear_index(index)

Settings

get_settings/1

    get_settings(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"}
}

set_settings/2

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

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

TODOS:

• get_object
• save_object
• save_objects
• update_object
• partial_update_object
• partial_update_objects
• delete_object
• delete_objects
• list_indexes
• clear_index
• wait_task
• wait (convenience function for piping response into wait_task)
• set_settings
• get_settings
• list_user_keys
• get_user_key
• add_user_key
• update_user_key
• delete_user_key

algolia-elixir's Issues

Trying to use this package, without luck, any help?

Hi there, we got a customer request trying to use this package and it was failing for some reason.

Trying to use this package myself I also failed at it. I made an example GitHub repository here: https://github.com/algolia/elixir-test

Could you have a look and tell me what's wrong?

Thanks!

Implementing replace_all_objects

This feature seems vital to swap indices in production without incurring downtime. Any plan on implementing it?

Reference: https://www.algolia.com/doc/api-reference/api-methods/replace-all-objects/

delete_object with empty string deletes the index

An object id of an empty string deletes the entire index due to the way strings are concatenated.

Algolia.delete_object(index_name, "")

This probably shouldn't be allowed.

It'd be nice to get #5 merged in during a fix for this also.

Update Poison dependency

Hi, Phoenix 1.3 is almost out and it depends on Poison ~> 2.2 or ~> 3.0. It seems updating poison dependency to ~> 1.5 or ~> 2.2 or ~> 3.0 will not break anything in the project but will bring happiness to those who is using Phoenix 1.3 with Algolia :)

[Meta] Willing to accept updates?

Hi @sikanhe, thanks for the work on this so far.

I'm evaluating using this library for a project of mine, but I'm going to need to invest some work to fill out some of the missing API calls and expand on what's already here.

Are you open to contributions and are you open to overall code structure improvements?

If so, let me know ASAP and please add a license file to this project (preferably Apache, the same license as Elixir).

New release

Would be great to see a new release pushed to Hex.

Also, any plans on starting to publish releases to GitHub as well?

Example how to use with UI

Wanted to know if you had an example on how to integrate this using some of algolia UI components like autocomplete and load more, I'm fully sure how to set up everything within my app?

Save an Object without OBJECT ID

It is undoubtedly best Elixir Algolia Client API Library. However, I figure out that the library missed a functionalities that is to save an object without passing object-ID .

I figure out some feature is missing.
They are

1. Batch File Save
2. Batch File Save in Multiple Indexes

Thanks for the plugin

Hello,

Sorry to contact you through your issues, but I could not find another way from your profile page.

I wanted to thank you for the work you put into this plugin. I work at Algolia, and it is always a joy to see people from the community building stuff with our API, so thank you.

Feel free to send me an email at tim at algolia dot com for a real thank you gift :)