Lightweight library for querying and transforming JSON data with a fluent, composable API. Enables nested path traversal, property selection, array slicing, filtering, and data aggregation.
A lightweight Kotlin library for querying and transforming JSON data using a fluent, composable API. ✨
implementation("io.github.lexa-diky:json-query:0.6.0")path("a.b.c")
path("a.*.b")
path("arr")[2], path("arr")[0..2], or dot form path("arr.2")
path("a|b") chooses the first existing key.path("a&b") returns only those keys if all exist; otherwise returns JsonNull.
path("a&b.x") applies .x to both a and b and returns an object with results per key.val json = Json.parseToJsonElement(File("dataset.json").readText())
// Accessing a nested property
println(json.query { path("shelter.name") })
// Accessing an array element by index
println(json.query { path("shelter.cats")[0].path("name") })
println(json.query { path("shelter.cats.0.name") })
println(json.query("shelter.cats.0.name"))
// Accessing all names in an array
println(json.query { path("shelter.cats.name") })
// Wildcard path
println(json.query { path("shelter.*.name") })
// Filtering array elements
println(json.query { path("shelter.cats.name").filterT<String> { it.startsWith("M") } })
// Slicing arrays
println(json.query { path("shelter.cats")[0..1].path("name") })You can use queryAs to directly convert the result of a query to a Kotlin type using kotlinx.serialization:
// Get a list of cat names as List<String>
val names = json.queryAs<List<String>> { path("shelter.cats.name") }
// Get a single age as Int
val age = json.queryAs<Int> { path("shelter.cats.1.age") }// Statistical operations
println(json.query { path("shelter.cats.age").max() })
println(json.query { path("shelter.cats.age").min() })
println(json.query { path("shelter.cats.age").average() })
println(json.query { path("shelter.cats.age").sum() })
println(json.query { path("shelter.cats.age").first() })
println(json.query { path("shelter.cats.age").last() })
println(json.query { path("shelter.cats.age").distinct() })
println(json.query { path("shelter.cats.age").filterT<Int> { it >= 2 }.size() })
// Selecting specific fields
println(json.query { path("shelter.cats.0").select("name", "age") })
println(json.query { path("shelter.cats").select("name", "age") })
// Aggregating data into objects
println(json.query {
path("shelter.cats").qmap {
buildJsonObject {
put("names", query { path("name") })
put("ages", query { path("age") })
}
}
})
// Applying a query to each element in an array
println(json.query {
path("shelter.cats.name")
.each { mapT<String, String> { it.uppercase() } }
})json-query-kt is designed to be efficient and fast, it beats standard kotlinx-serialization object mapping in most
cases, especially for large datasets and/or complex serialization logic.
A lightweight Kotlin library for querying and transforming JSON data using a fluent, composable API. ✨
implementation("io.github.lexa-diky:json-query:0.6.0")path("a.b.c")
path("a.*.b")
path("arr")[2], path("arr")[0..2], or dot form path("arr.2")
path("a|b") chooses the first existing key.path("a&b") returns only those keys if all exist; otherwise returns JsonNull.
path("a&b.x") applies .x to both a and b and returns an object with results per key.val json = Json.parseToJsonElement(File("dataset.json").readText())
// Accessing a nested property
println(json.query { path("shelter.name") })
// Accessing an array element by index
println(json.query { path("shelter.cats")[0].path("name") })
println(json.query { path("shelter.cats.0.name") })
println(json.query("shelter.cats.0.name"))
// Accessing all names in an array
println(json.query { path("shelter.cats.name") })
// Wildcard path
println(json.query { path("shelter.*.name") })
// Filtering array elements
println(json.query { path("shelter.cats.name").filterT<String> { it.startsWith("M") } })
// Slicing arrays
println(json.query { path("shelter.cats")[0..1].path("name") })You can use queryAs to directly convert the result of a query to a Kotlin type using kotlinx.serialization:
// Get a list of cat names as List<String>
val names = json.queryAs<List<String>> { path("shelter.cats.name") }
// Get a single age as Int
val age = json.queryAs<Int> { path("shelter.cats.1.age") }// Statistical operations
println(json.query { path("shelter.cats.age").max() })
println(json.query { path("shelter.cats.age").min() })
println(json.query { path("shelter.cats.age").average() })
println(json.query { path("shelter.cats.age").sum() })
println(json.query { path("shelter.cats.age").first() })
println(json.query { path("shelter.cats.age").last() })
println(json.query { path("shelter.cats.age").distinct() })
println(json.query { path("shelter.cats.age").filterT<Int> { it >= 2 }.size() })
// Selecting specific fields
println(json.query { path("shelter.cats.0").select("name", "age") })
println(json.query { path("shelter.cats").select("name", "age") })
// Aggregating data into objects
println(json.query {
path("shelter.cats").qmap {
buildJsonObject {
put("names", query { path("name") })
put("ages", query { path("age") })
}
}
})
// Applying a query to each element in an array
println(json.query {
path("shelter.cats.name")
.each { mapT<String, String> { it.uppercase() } }
})json-query-kt is designed to be efficient and fast, it beats standard kotlinx-serialization object mapping in most
cases, especially for large datasets and/or complex serialization logic.