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

Using Kotlin Scripting

KT Search Manual Previous: Extending the Json DSLs Next: Jupyter Notebooks
Github © Jilles van Gurp  

One interesting use of kt-search is to script common operations around Elasticsearch.

For this we have a companion library kt-search-kts that makes integrating kt-search into your .main.kts scripts very easy.

You may find a few example scripts in the scripts directory of that project. To run these scripts, you need to have kotlin installed on your system of course.

Example script

#!/usr/bin/env kotlin

@file:Repository(" https://repo.maven.apache.org/maven2/")

import com.jillesvangurp.ktsearch.ClusterStatus
import com.jillesvangurp.ktsearch.clusterHealth
import com.jillesvangurp.ktsearch.kts.addClientParams
import com.jillesvangurp.ktsearch.kts.searchClient
import com.jillesvangurp.ktsearch.root
import kotlinx.cli.ArgParser
import kotlinx.coroutines.runBlocking

// ArgParser is included by kt-search-kts to allow you to configure the search endpoint
val parser = ArgParser("script")
// this adds the params for configuring search end point
val searchClientParams = parser.addClientParams()

// extension function in kt-search-kts that uses the params
val client = searchClientParams.searchClient

// now use the client as normally in a runBlocking block (creates a co-routine)
runBlocking {
    val clusterStatus=client.clusterHealth()
    client.root().let {
                Cluster name: ${it.clusterName}
                Search Engine distribution: ${it.version.distribution}
                Version: ${it.version.number}

    when(clusterStatus.status) {
        ClusterStatus.Green -> println("Relax, your cluster is green!")
        ClusterStatus.Yellow -> println("WARNING: cluster is yellow")
        ClusterStatus.Red -> error("OMG: cluster is red!!!!!")

The example script above adds the maven dependency and our two maven repositories via @file: directives.

The parser.addClientParams() extension function adds a few parameters to the kotlinx-cli command line argument parser so we can create a SearchClient with the right parameters. You can add more parameters for your script of course. If you call the script with -h it will print all the parameters that we added:

    Usage: script options_list
        --host, -a [localhost] -> Host { String }
        --port, -p [9200] -> Port { Int }
        --user -> Basic authentication user name if using with cloud hosting { String }
        --password -> Basic authentication user name if using with cloud hosting { String }
        --protocol [false] -> Use https if true 
        --help, -h -> Usage info         

After parsing the args, you can get a SearchClient by simply calling searchClientParams.searchClient. Kotlinx-cli’s commandline parser will populate the settings.

You can use then import the client as normally. Because the client uses suspending functions, you have to surround your code with a runBlocking {...}

Note, be sure to use the latest version of kt-search-kts.

Some ideas for using kt-search on the cli

Some ideas for using kts scripting with Kt-Search:

How to run .main.kts scripts

To be able to run the scripts, install kotlin 1.7 via your linux package manager, home-brew, sdkman, snap, etc. There are many ways to do this.

Unfortunately, using kotlin script is a bit under-documented by Jetbrains and still has some issues.

kt-search-kts is there to get you started, of course.


    @file:Repository(" https://repo.maven.apache.org/maven2/")

KT Search Manual Previous: Extending the Json DSLs Next: Jupyter Notebooks
Github © Jilles van Gurp