lucene-kmp
10.2.0-alpha14indexedlucene-kmp is a KMP port of Apache Lucene enabling On-device indexing and full text search capabilities in Android, iOS and desktop apps.
8
Stars
—
Used by
dependents
57
Health
/ 100
Lucene Kotlin Multiplatform
Overview
lucene-kmp is a Kotlin Multiplatform port of Apache Lucene enabling On-device indexing and full text search capabilities in KMP/CMP Android, iOS and desktop apps.
Supported platforms
- Kotlin/Jvm
- Kotlin/Android
- Kotlin/Native iOS (iosArm64, iosSimulatorArm64, iosX64)
- Kotlin/Native macOS (macosArm64, macosX64)
- Kotlin/Native Linux (linuxArm64, linuxX64)
- Kotlin/Native Windows (mingwX64)
Features
Getting started
lucene-kmp is published to Maven Central. Add the core and queryparser module to your build.gradle.kts:
implementation("org.gnit.lucene-kmp:lucene-kmp-core:10.2.0-alpha14")
implementation("org.gnit.lucene-kmp:lucene-kmp-queryparser:10.2.0-alpha14")
Build a small index and search it (imports are omitted; class names live under org.gnit.lucenekmp.*):
For indexed field types, filters, sort, phrase/fuzzy/wildcard queries, geo and IP queries, see docs/USAGE.md.
Java Lucene and lucene-kmp
- lucene-kmp prioritizes the core indexing and search APIs, then adds common analyzers and codecs.
coreandqueryparserclasses ported so far get the index and search jobs done.- Some optionals classes left not ported yet.
- Languages with large speaker population not covered by Java Lucene got extra analyzers in lucene-kmp.
- See LANGUAGE_COVERAGE.md for language coverage comparison table.
Lucene or SQL
If you wonder you need to use lucene-kmp, consider the difference between a search engine library and a database. In KMP development, SQL libraries such as SQLDelight and Room KMP are the right choice for structured app data: tables, rows, primary keys, relations, transactions, migrations, and exact queries like "all notes updated after this date" or "all messages in this conversation." Use lucene-kmp when the user experience is a search box over text: ranked results, tokenization, stemming, phrase queries, typo-tolerant search, and fast lookup across document fields. Many apps should use both: keep SQLDelight or Room KMP as the source of truth, then build a lucene-kmp index from the searchable fields for high-quality local search.
Porting Progress
- PROGRESS.md tracks the porting progress by class counts, generated by progress.main.kts.
- PROGRESS2.md tracks the porting progress by semantic completion of core methods and classes, generated by progress2.main.kts.
- TODO.md tracks the dependency depth aware porting order suggestion, generated by .
Currently the port is based on Java Lucene commit ec75fcad5a4208c7b9e35e870229d9b703cda8f3 on Mar 7, 2025 which is some commits ahead of lucene 10.2.0 release.
No specific reason why I chose this. This is the day I decided to port Lucene to KMP and just ran git clone.
jdkport package
Lucene is heavily dependent on JDK classes which drop in replacement is not available in Kotlin/Common standard library.
The org.gnit.lucenekmp.jdkport package lives inside the core module and provides
Kotlin Multiplatform replacements for JDK classes and interfaces that the Java Lucene code base
depends on but that are not part of the Kotlin standard library, such as , ,
, , , , , and .
Porting those jdk source doe into kmp consumes a lot of time, effort and tokens, but I thought it worth doing it to behave as close as possible to the Java Lucene and side by side easy review.
The jdkport classes are mostly ported from openjdk 24 fully. In some case, partial methods/functions are ported. And in case such as concurrency utilities, Kotlin Coroutines are as alternative to Java Threads and locks. java.util.Date is replaced by kotlin.time.Instant
3rd-party dependencies
lucene-kmp try not to depend on other libraries as much as possible but exceptionally depends on following kmp libs:
io.github.oshai:kotlin-loggingfor loggingdev.scottpierce:kotlin-env-varfor environment variable access in tests
About Apache Lucene
Apache Lucene is a high-performance search engine library. It is not a search server or database by itself; it is the indexing and query engine that applications embed when they need fast full-text search, relevance ranking, fielded search, filters, sorting, faceting-style building blocks, and specialized query types over local or server-side data.
Lucene started as an open source Java project created by Doug Cutting @cutting and later became an Apache Software Foundation project. Over time it became one of the foundational libraries for information retrieval on the JVM, with a long history of production use, careful index-format evolution, and deep engineering around analyzers, inverted indexes, scoring, segment merging, and low-level search performance.
Many well-known search platforms are built on Apache Lucene. Apache Solr is the long-running Lucene search server in the Apache ecosystem. Elasticsearch and OpenSearch also use Lucene as their core search engine underneath distributed indexing, clustering, REST APIs, replication, and operational tooling. In that sense, Lucene is the lower-level engine that powers many higher-level search systems.
Disclaimer: I am not affiliated with the Apache Software Foundation or the official Lucene project. lucene-kmp is an independent port of the Java Lucene source code to Kotlin Multiplatform, and it is not an official Apache project. I'm hoping in one day it will be listed as 14th entry of the list of other language ports of Lucene.
Motivation
I built and was using bbl command line bible to read and search the bible on my machine. I used Apache Lucene and Kotlin/JVM for the full text search capability. Then I also built bbl-android without the search feature, because Java Lucene does not run on Android. I knoew Lucene was already ported to 13 languages/platforms but it was too large codebase for me alone to port. Then AI coding assistants/agents start to emerge and I started bbl-kmp to read and search bible in cli and mobile porting and dogfooding lucene-kmp!
AI Usage
- I started to port Lucene using JetBrains' Covert Java to Kotlin feature. At that time, one line suggestion of GitHub Copilot was only AI assistant I used.
- Then when it gets time and effort consuming to rewrite such as "Java threading to Kotlin coroutines", I used ChatGPT on the web to draft the ported code.
Documentation
The project website lives under docs/ and is built with Doks / Thulite.
Build the combined website and generated Dokka API docs locally:
scripts/build-docs-site.sh
Generated outputs are intentionally not committed:
docs/public/contains the Hugo site artifact.docs/api/contains generated Dokka API docs for local preview and deployment.
License
Apache License 2.0, see LICENSE file.