Initialize the Scala API client
This is documentation for v1 of the Scala API clients, which is not the latest version. To see the documentation for the latest version, see Scala v2.
Before you can index your data or search your Algolia indices, you must initialize a search client with your application ID and API key. You can find both in your Algolia account.
Initialize the search client
The search client handles authentication and lets you manage your indices, for example, add data to them, or search them.
1
2
// The index doesn't need to be initialized
val client = new AlgoliaClient("YourApplicationID", "YourWriteAPIKey")
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 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 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 through the client
are:
Operations scoped to an index
are:
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")
}