luqum

What it is and what it does

Luqum is a Lucene Query DSL parser that builds an abstract syntax tree from Lucene query strings, allowing you to inspect, analyze, and programmatically manipulate search queries. It depends only on PLY (Python Lex-Yacc) and runs on Python 3.10+. The primary use case is transforming user-written Lucene queries into Elasticsearch JSON DSL, while also supporting custom transformations and enrichments—for example, adding support for nested object searches or applying field-specific query logic.

The package has been actively developed since 2016, recently reaching version 1.0.0 (2025-02-18) with support for Python 3.11, 3.12, and 3.13. It handles a range of Lucene features including boolean operations, proximity and fuzzy matching, range queries, wildcards, and escape sequences. The dual Apache 2.0 / LGPLv3+ licensing provides flexibility for most projects, though the package metadata does not yet clearly expose which license applies.

Use it for:

• Transform user-facing Lucene query syntax into Elasticsearch JSON DSL for backend execution.
• Validate and analyze Lucene queries before sending them to a search engine.
• Enrich or rewrite Lucene queries programmatically (e.g., add field restrictions, rewrite operators).
• Build query visualization or debugging tools that explain why a query matches certain results.
• Support nested object searches or custom field treatments by intercepting and modifying the query tree.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses Lucene Query DSL syntax into an abstract syntax tree, enabling inspection, analysis, and transformation of search queries for use with Elasticsearch or custom backends.

Yes. Luqum is actively maintained, has low install friction, carries no known vulnerabilities, and solves a specific problem well: parsing and transforming Lucene queries. Install it if you need to accept Lucene syntax from users and convert it to Elasticsearch or apply custom query logic. Verify the dual license terms (Apache 2.0 / LGPLv3+) match your project's requirements before committing.

Install

luqum on PyPI

pip install luqum

uv add luqum

poetry add luqum

Installing luqum

Before you install

Low install friction with a single lightweight dependency (ply >= 3.11). Actively maintained; last commit 2026-04-14 with recent version 1.0.0 released 2025-02-18. Supports Python 3.10+.

License in practice

Dual-licensed under Apache 2.0 and LGPLv3+, but license metadata is unclear in the package record. Verify the actual license terms before use in proprietary or GPL-incompatible projects.

Quickstart

pip install luqum

from luqum.parser import parser

tree = parser.parse('author.last_name:Smith OR author:(age:[25 TO 34])')
print(tree)

Requires Python 3.10 or later; earlier versions no longer supported as of 0.14.0.

Verify before relying

• Whether license metadata (SPDX/raw) will be clarified in future releases to resolve the 'unclear' treatment flag.
• Performance characteristics when parsing very large or deeply nested Lucene queries.
• Completeness of Elasticsearch DSL transformation support for all Lucene operators and edge cases.

Package facts

Evidence: luqum-1.0.0-py3-none-any.whl

Tags

More Text Processing packages