PartiQL Lang Kotlin: an implementation of the PartiQL query language

What PartiQL is, and why it exists

This is a Kotlin and JVM implementation of the PartiQL specification. PartiQL is based on SQL:1999 and has added support for working with schemaless hierarchical data.

The design claim in the README is that PartiQL's extensions to SQL are easy to understand, treat nested data as first class citizens, and compose with SQL. That is the whole motivation for the language. SQL:1999 predates JSON, and the awkwardness of querying document data with SQL is that you either flatten it into joins or write a different query language entirely. PartiQL takes the second route while keeping the syntax familiar, so a query that walks into a nested structure reads much like a query that filters a table.

The status section is unusually reassuring for a specification implementation. Users of PartiQL should consider the PartiQL library to be stable, it has been used inside a number of Amazon internal systems and AWS products for multiple years, and the behavior of the language itself is mostly stable.

That last claim is the useful one to note carefully. The library is stable and the language behaviour is mostly stable, which is two different claims and the second one carries the qualifier.

The project is Apache-2.0 licensed, the primary language is Kotlin, the default branch is main, and the homepage is partiql.org. The last push was on 2026-10-14, and the release history is regular: v1.6.1 on 2026-09-03, v1.6.0 on 2026-09-01 and v1.5.1 on 2026-08-18.

Adding it to a Gradle project is one dependency line

All releases are published to Maven Central, under the org.partiql namespace, and the README gives the dependency block for the most up to date version:

dependencies {
    implementation("org.partiql:partiql-lang:1.+")
}

The version specifier is worth a second look, because it is not what a careful project would usually write. A dynamic version with a plus resolves to the newest published release at build time, which means two builds of the same commit can pull different artifacts. For a library that describes itself as stable that is a defensible choice, since the API is not expected to move, and it also means you pick up fixes without changing your build file.

The other option is to depend on a specific subproject rather than on partiql-lang, which is the top-level project that depends on all the subprojects. The README points at the partiql-lang-kotlin documentation site under the PartiQL website for how to integrate the library, or a specific subproject, into your project.

That distinction is the one that matters for sizing the dependency. The top-level artifact brings the parser, the planner, the evaluator, the IR and the SPI with it. If you only want to parse a PartiQL document and inspect the AST, partiql-ast is a much smaller thing to depend on.

The build needs a recursive clone and a Gradle assemble

Building this project requires Java 11 or newer, and the repository pulls in its conformance test data as a git submodule.

The easiest way to pull everything in is to clone the repository recursively:

$ git clone --recursive https://github.com/partiql/partiql-lang-kotlin.git

You can also initialize the submodules separately:

$ git submodule update --init --recursive

Then, from the root directory, the build is:

./gradlew assemble

And this will build the reference interpreter and test framework, then run all unit and integration tests. That last part is unusual and worth pausing on. A single assemble invocation runs the whole test suite, including the conformance tests against the partiql-tests repository, so a build is also a compliance check.

The submodule is why the recursive clone matters. Without it the test data is simply absent, and the failure mode is a missing directory rather than a clear message about the submodule, which is the usual reason to use the recursive form from the start.

The Maven Central badge, the CI build badge labelled Build and Report Generation, and a codecov badge sit at the top of the README, so the build and the coverage report are both public signals of the project's health.

Twelve subprojects, and the pipeline they implement

The Directory Structure section is a tree of the subprojects, and it maps a query language implementation onto the stages every such implementation has.

The parsing side is partiql-parser for the PartiQL parser and partiql-ast for the AST data structures and utilities. The planning side is partiql-planner for the planner and partiql-plan for the plan data structures and utilities, with partiql-spi holding the common interfaces, types, values, catalogs and functions.

The evaluation side is partiql-eval, described as the PartiQL compiler, which is where the plan becomes executable. lib/sprout is the IR codegen, and it is the piece that produces the intermediate representation the evaluator runs.

Then there are the tools. partiql-cli is the CLI and Shell application, and partiql-coverage is a code coverage library. partiql-function-extensions holds optional reusable function extensions, which is the extension point for adding functions beyond the specification.

The build side has buildSrc for the Gradle multi-project build, and there is a top-level partiql-lang project that depends on all subprojects, which is the artifact you add to your build file.

The test tree is separate from the others. The partiql-tests directory holds conformance test data and the partiql-tests-runner holds the conformance test runner, and both come from the partiql-tests repository through the submodule, which means the test suite is shared with the other PartiQL implementations rather than being Kotlin specific.

Who this is for

The project is aimed at two fairly different groups, and the README supports both.

For query users, the PartiQL website is the place to start, with documentation and usage guides, and the PartiQL specification document is linked for the normative detail. The language is a specification with multiple implementations, and this is the Kotlin one, so anything that is about the language rather than about the implementation lives elsewhere.

For people working on the implementation itself, the repository carries a full set of engineering conventions. There is a CODE_STYLE.md, a detekt-config.yml for static analysis, a custom-ktlint-rules/ directory for project-specific formatting rules, a .editorconfig, a CHANGELOG.md, a CODE_OF_CONDUCT.md and an AGENTS.md, plus a NOTICE file alongside the LICENSE. The examples/ directory has its own README and its own build.gradle.kts with sources under examples/src, so the examples are a separate Gradle project rather than a folder of loose scripts.

The NOTICE file is worth a mention because the specification itself is a separate document from the implementation. A query language with an open specification has a design process that the implementations then follow, and the conformance test suite in the submodule is how the implementations are held to it. When the library claims the behaviour of the language is mostly stable, that claim is measured against the shared test data rather than asserted.

The releases are listed on GitHub as well as published to Maven Central, and the version numbers follow the usual semantic versioning shape, with a 1.6.0 followed by patch releases.

Editorial conclusion

Adopt partiql-lang-kotlin if you need a PartiQL implementation on the JVM, either to run PartiQL queries in a service or to study how a query language with nested data is compiled and planned. Do not expect a general purpose SQL engine, because the target is the PartiQL specification and its conformance suite rather than a database. Before you build it, note that the build pulls in the partiql-tests repository as a git submodule, so a recursive clone is required, and that the parser, planner, evaluator and IR are separate subprojects you can depend on individually rather than taking the whole thing.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. partiql/partiql-lang-kotlin on GitHub
3. Project website
4. README
5. Releases