Initialize the Scala API client

Before you can interact with Algolia’s APIs, for example, to index your data or search your indices, you need to authenticate with Algolia with your Application ID and API key by initializing a client. You can find both in your Algolia account.

Initialize the search client

The search client lets you manage your indices, add data to your indices, and search your indices.

1
2
// The index doesn't need to be initialized
val client = new AlgoliaClient("YourApplicationID", "YourAdminAPIKey")

Replace your_index_name with the name of the index you want to use. You can find your existing indices in the Algolia dashboard, or by using the listIndices method. If the index doesn’t exist, a new, empty index is created locally. It’s created on Algolia’s servers only if you add records to the index.

Don’t use any sensitive or personally identifiable information as your index name, including usernames, IDs, or email addresses. Index names are publicly shared.

Operations, that are scoped to your Algolia application via the client are:

• Manage indices
• Manage dictionaries
• Manage API keys

Operations scoped to an index are:

• Search
• Indexing
• Set and get settings
• Define synonyms
• Define Rules

The Recommend, Personalization, Insights, and A/B testing APIs come with their own clients.

Usage notes

JVM DNS caching

By default, the JVM caches DNS resolutions infinitely. Since Algolia uses multiple IP addresses for load balancing, you should reduce the time to live (TTL) of the cache.

For example, to set the cache to 60 seconds:

1
java.security.Security.setProperty("networkaddress.cache.ttl", "60");

Debug logging

You can enable debug logging in the API client using the slf4j library. The logger is named algoliasearch.

Domain-specific language

The Scala API client lets you use a domain-specific language (DSL). The entry point of the DSL is the algolia.AlgoliaDSL object. This DSL is used in the execute method of algolia.AlgoliaClient.

The DSL is designed to be human-readable. For some tasks there may be more than one way of achieving it. For example, to get an object by its objectID:

1
2
3
client.execute { from index "index" objectId "myId" }
// or
client.execute { get / "index" / "myId" }

Futures

The execute method always returns a scala.concurrent.Future. The Future can be parametrized by a case class:

1
2
3
4
val future: Future[Search] =
    client.execute {
        search into "index" query "a"
    }

JSON as case class

The Scala API client uses json4s to serialize and deserialize objects and API responses and case classes.

For example, to deserialize a search response:

1
2
3
4
5
6
7
8
9
10
11
12
13
case class Contact(firstname: String,
                   lastname: String,
                   followers: Int,
                   company: String)

val future: Future[Seq[Contact]] =
    client
        .execute {
            search into "index" query "a"
        }
        .map { search =>
            search.as[Contact]
        }

To get the full results from the response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
case class EnhanceContact(firstname: String,
                          lastname: String,
                          followers: Int,
                          company: String,
                          objectID: String,
                          _highlightResult: Option[Map[String, HighlightResult]
                          _snippetResult: Option[Map[String, SnippetResult]],
                          _rankingInfo: Option[RankingInfo]) extends Hit

val future: Future[Seq[EnhanceContact]] =
    client
        .execute {
            search into "index" query "a"
        }
        .map { search =>
            search.asHit[EnhanceContact]
        }

When you index your data, pass an instance of your case class to the DSL:

1
2
3
client.execute {
    index into "contacts" `object` Contact("Jimmie", "Barninger", 93, "California Paint")
}