kt-search

Multi platform kotlin client for Elasticsearch & Opensearch with easily extendable Kotlin DSLs for queries, mappings, bulk, and more.

Project maintained by jillesvangurp Hosted on GitHub Pages — Theme by mattgraham

Getting Started

KT Search Manual Previous: What is Kt-Search Next: Client Configuration
Github © Jilles van Gurp  

To get started, simply add the dependency to your project and create a client. The process is the same for both jvm and kotlin-js.

Gradle

Kt-search is published to the FORMATION maven repository.

Add the maven.tryformation.com repository:

repositories {
    mavenCentral()
    maven("https://maven.tryformation.com/releases") {
        content {
            includeGroup("com.jillesvangurp")
        }
    }
}

And then add the dependency like this:

    // check the latest release tag for the latest version
    implementation("com.jillesvangurp:search-client:2.x.y")

Note, several of the search-client dependencies for ktor client are marked as implementation. This means you have to explicitly add those on your side. This is intentional as some people may want to use their own rest client with the kt-search search client.

If you use the KtorRestClient that comes with kt-search you need to add the relevant ktor dependencies for the lates ktor-client 3.x:

implementation("io.ktor:ktor-client-core:3.x.y")
implementation("io.ktor:ktor-client-auth:3.x.y")
implementation("io.ktor:ktor-client-logging:3.x.y")
implementation("io.ktor:ktor-client-serialization:3.x.y")
implementation("io.ktor:ktor-client-json:3.x.y")

Maven

If you have maven based kotlin project targeting jvm and can’t use kotlin multiplatform dependency, you will need to append ‘-jvm’ to the artifacts.

Add the maven.tryformation.com repository:

<repositories>
    <repository>
        <id>try-formation</id>
        <name>kt search repository</name>
        <url>https://maven.tryformation.com/releases</url>
    </repository>
</repositories>

And then add dependencies for jvm targets:

<dependencies>
    <dependency>
        <groupId>com.jillesvangurp</groupId>
        <artifactId>search-client-jvm</artifactId>
        <version>2.x.y</version>
    </dependency>
    <dependency>
        <groupId>com.jillesvangurp</groupId>
        <artifactId>search-dsls-jvm</artifactId>
        <version>2.x.y</version>
    </dependency>
    <dependency>
        <groupId>com.jillesvangurp</groupId>
        <artifactId>json-dsl-jvm</artifactId>
        <version>3.x.y</version>
    </dependency>
</dependencies>

Note: The json-dsl is moved to separate repository. To find the latest version number, check releases: https://github.com/jillesvangurp/json-dsl/releases

Create a Client

To use kt-search you need a SearchClient instance. Similar to what the Elastic and Opensearch Java client do, there is a simple RestClient interface that currently has a default implementation based on ktor-client. This client takes care of sending HTTP calls to your search cluster.

// creates a client with the default RestClient
val client = SearchClient()

Using the client

After creating the client, you can use it. Since kt-search uses non blocking IO via ktor client, all calls are suspending and have to be inside a co-routine.

// use a simple runBlocking
// normally you would get a co-routine via e.g. Spring's flux async framework.
runBlocking {
  // call the root API with some version information
  client.root().let { resp ->
    println("${resp.variantInfo.variant}: ${resp.version.number}")
  }
  // get the cluster health
  client.clusterHealth().let { resp ->
    println(resp.clusterName + " is " + resp.status)
  }

}

The main purpose of kt-search is of course searching. This is how you do a simple search and work with data classes:


// define a model for your indexed json documents
data class MyModelClass(val title: String, )

// a simple search
val results = client.search("myindex") {
  query = matchPhrase(
    field = "title",
    query = "lorum ipsum")
}

// returns a list of MyModelClass
val parsedHits = results.parseHits<MyModelClass>()

// if you don't have a model class, you can just use a JsonObject
val jsonObjects = results
  .hits
  ?.hits
  // extract the source from the hits (JsonObject)
  ?.map { it.source }
  // fall back to empty list
  ?: listOf()

Next steps

KT Search Manual Previous: What is Kt-Search Next: Client Configuration
Github © Jilles van Gurp