Usage

• :index_name: specificy the index or a list of indexes where the object will be added on. Required
• :object_id: specify the attribute used to as algolia objectID. Default :id.
• :repo: Specify an Ecto repo to be use to fecth records. Default nil
• :cursor_field: specify the column to be used to order and go through a given table. Default :id
• :schemas: Specify which schemas used to populate index, Default: [__CALLER__]
• :default_filters: Specify default filters to be used when reindex without providing a query. Must be a map or a function name (that returns a map). Default: %{}.
• :algolia: Any valid Algolia settings (using snake case or camel case, ie attributeForFaceting can be configured with :attribute_for_faceting) or the name of 0-arity function that returns those settings.
• :synonyms: Custom configuration for the synonym API, allowing you to register your synonyms. Can be nil, a keyword list, or an arity-1 function that returns either. Default: nil

On first call to Algolia, we check that the settings on Algolia are up to date.

Example

defmodule People do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]

  defstruct reference: nil, last_name: nil, first_name: nil, age: nil
end

Customize object

By default the object contains only algolia objectID. To add more attributes to objects, override build_object/1 functions to return a Map (objectID is automatically set by Algoliax)

defmodule People do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]

  defstruct reference: nil, last_name: nil, first_name: nil, age: nil

  @impl Algoliax.Indexer
  def build_object(person) do
    %{
      age: person.age,
      last_name: person.last_name,
      first_name: person.first_name
    }
  end
end

Schemas

:schemas options allows to define a list of module you want to index into the current index. By default only the module defining the indexer.

defmodule Global do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    schemas: [People, Animal],
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]

end

The example above will introduce a compile-time dependency on People and Animal, so it is preferable to provide the name of a function that will return the list of modules.

defmodule Global do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    schemas: :index_schemas,
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]

  def index_schemas, do: [People, Animal]
end

This option allows to define also the preloads use during reindex/reindex_atomic (preload on save_object and save_objects have to be done manually)

  defmodule People do
    use Algoliax.Indexer,
      index_name: :people,
      object_id: :reference,
      schemas: [
        {__MODULE__, [:animals]}
      ]
      algolia: [
        attribute_for_faceting: ["age"],
        custom_ranking: ["desc(updated_at)"]
      ]

  end

Default filters

:default_filters allows you to define a list of filters that will be automatically applied when performing reindex without query, or reindex_atomic. If not provided, it defaults to %{}, meaning it will not apply any filter and fetch the entire repo for all schemas. You can provide either a map or a function name that returns a map.

defmodule Global do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    schemas: [People, Animal],
    default_filters: %{where: [age: 18]},
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]
end

The map must be a valid Ecto query but can be customized/nested by schema:

defmodule Global do
  use Algoliax.Indexer,
    index_name: :people,
    object_id: :reference,
    schemas: [People, Animal],
    default_filters: :get_filters,
    algolia: [
      attribute_for_faceting: ["age"],
      custom_ranking: ["desc(updated_at)"]
    ]

  def get_filters do
    %{
      People => where: [age: 18], # <-- Custom filter for People
      :where => [kind: "cat"]  # <-- Default filter for other schemas
  end
end

Configure index name and algolia settings at runtime

To support code for multiple environments, you can also define things like index_name or algolia settings at runtime. To achieve this, create a function within your indexer module and reference it using its atom in the Indexer configuration.

defmodule People do
  use Algoliax.Indexer,
    index_name: :runtime_index_name,
    #....
    algolia: :runtime_algolia

  def runtime_index_name do
    System.get_env("INDEX_NAME")
  end

  def runtime_algolia do
    [attribute_for_faceting: ["age"]]
  end
end

### Configure synonyms

To automatically setup synonyms, you can provide a configuration under the `:synonyms` key.
When calling `configure_index`, the synonyms will be set up in Algolia.
It will be performed on both the main index and its replicas.

If not specified or set to `nil`, the synonyms will not be configured.
Otherwise, the following keywords are expected, with each key having a default value:
- `synonyms`: a list of synonym groups. Default `[]`
- `replace_existing_synonyms`: Whether to replace existing synonyms. Default `true`
- `forward_to_replicas`: Whether to forward synonyms to replicas. Default `true`
You can also provide an arity-1 function (that takes the index_name) that returns the same keyword list.

If using `forward_to_replicas: true`, make sure not to specify synonyms on the replicas themselves
to avoid conflicts/overwrites.

defmodule Global do use Algoliax.Indexer,

index_name: :people,
object_id: :reference,
schemas: People,
algolia: [
  attribute_for_faceting: ["age"],
  custom_ranking: ["desc(updated_at)"]
]
synonyms: [
  synonyms: [
    %{
      objectID: "synonym1",
      type: "synonym",
      synonyms: ["pants", "trousers", "slacks"],
      ...
    },
    %{
      objectID: "synonym2",
      ...
    }
  ],
  forward_to_replicas: false,
  replace_existing_synonyms: false
]

end

See https://www.algolia.com/doc/rest-api/search/#tag/Synonyms/operation/saveSynonyms