luqum

library1.0.0pypypi✓ verified 24d ago

Luqum (LUcene QUery Manipolator) is a Python library that parses Lucene Query DSL strings, building an abstract syntax tree (AST) for inspection, analysis, and manipulation. It enables transforming Lucene DSL queries into native Elasticsearch JSON DSL. The library is currently at version 1.0.0 and sees releases as new features and maintenance updates are introduced, typically every few months. [1, 7, 11]

http-networking data serialization

pip install luqum

github ↗package ↗

INSTALL

IMPORT

SIG · LUQUM

luqum

http-networkingpythonv1.0.0

Install

1.6s avg

Import

54ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.054s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.054s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ from luqum.parser import parser

ElasticsearchQueryBuilder

✓ from luqum.elasticsearch import ElasticsearchQueryBuilder

UnknownOperationResolver

✓ from luqum.utils import UnknownOperationResolver

Used to resolve implicit operators (e.g., 'foo bar') in parsed queries.

parse

✓ from luqum.thread import parse as thread_safe_parse

Use this for thread-safe parsing instead of luqum.parser.parser.parse().

AndOperation, Term, SearchField, Word

✓ from luqum.tree import AndOperation, Term, SearchField, Word

Common AST node types for programmatic tree construction/manipulation.

This quickstart demonstrates parsing a Lucene query string into an Abstract Syntax Tree (AST), resolving implicit operators, and converting the AST into an Elasticsearch Query DSL dictionary. It highlights core functionalities of `luqum` for query manipulation and transformation. [2, 3, 8]

from luqum.parser import parser from luqum.elasticsearch import ElasticsearchQueryBuilder from luqum.utils import UnknownOperationResolver # 1. Parse a Lucene query string query_string = '(title:"foo bar" AND body:"quick fox") OR title:fox' tree = parser.parse(query_string) print(f"Parsed AST: {repr(tree)}") print(f"String representation: {str(tree)}\n") # 2. Resolve unknown operations (e.g., implicit AND/OR) # For a query like 'foo bar', it's parsed as UnknownOperation(Word('foo'), Word('bar')) # Use a resolver to make it explicit, e.g., 'foo AND bar' resolver = UnknownOperationResolver(default_operation=AndOperation) # AndOperation needs to be imported from luqum.tree resolved_tree = resolver(parser.parse('foo bar')) print(f"Resolved 'foo bar' to: {str(resolved_tree)}\n") # 3. Transform to Elasticsearch Query DSL # For complex schemas, pass nested_fields and object_fields arguments es_builder = ElasticsearchQueryBuilder() es_query = es_builder(tree) print(f"Elasticsearch DSL:\n{es_query}")

Debug

Known issues

gotchaLucene queries with implicit operators (e.g., 'foo bar' instead of 'foo AND bar') are parsed as `UnknownOperation`. Users need to apply a transformer like `UnknownOperationResolver` to explicitly define the operator (e.g., AND, OR) for correct interpretation.

fix

Import `UnknownOperationResolver` from `luqum.utils` and apply it to your parsed AST, optionally specifying a `default_operation` (e.g., `AndOperation` from `luqum.tree`). [3, 8]

affects: All versions

gotchaWhen constructing or modifying ASTs programmatically (rather than parsing a string), the `head` and `tail` properties (representing non-meaningful text like spaces around elements) must be set manually if preserving the original query's formatting or position information is critical. These properties are computed automatically during parsing.

fix

Manually set `node.head` and `node.tail` attributes on AST nodes when building trees programmatically to retain formatting information. The `auto_head_tail` utility can assist. [3, 8, 7]

affects: All versions

gotchaThe underlying PLY library, used by luqum for parsing, is not inherently thread-safe. For concurrent parsing operations in a multi-threaded environment, `luqum.thread.parse()` should be used instead of `luqum.parser.parser.parse()` to ensure thread-safe execution by cloning the lexer state.

fix

Replace direct calls to `luqum.parser.parser.parse()` with `from luqum.thread import parse as thread_safe_parse` and then use `thread_safe_parse(query_string)` for thread-safe parsing. [6, 8]

affects: All versions

breakingVersion 0.14.0 removed official support for Python 3.6, 3.7, 3.8, and 3.9. Users on these older Python versions should use `luqum < 0.14.0` or upgrade their Python environment.

fix

Upgrade Python to 3.10+ or pin `luqum` to a version less than 0.14.0. [7]

affects: >=0.14.0

breakingIn version 0.11.0, the `naming` module and its `auto_name` function were completely modified, leading to API incompatibility for any code using these features.

fix

Review and adapt code interacting with `luqum.naming` and `auto_name` according to the 0.11.0 release notes and updated documentation. [7]

affects: >=0.11.0

breakingPrior to version 0.7.0, the `ElasticsearchQueryBuilder` transformed single-word matches into `match_phrase` queries. From 0.7.0 onwards, if the field is analyzed, it now uses a `match` query, which aligns more closely with Elasticsearch's `query_string` behavior. This might alter the resulting Elasticsearch query structure for some inputs.

fix

Audit existing Elasticsearch queries generated by `luqum` for single-word matches and adjust expectations or logic if `match_phrase` behavior is strictly required (e.g., by explicitly modifying the AST before transformation). [7]

affects: >=0.7.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'luqum'

The `luqum` library is not installed in your Python environment.

fix

Run `pip install luqum` in your terminal to install the library.

luqum.exceptions.ParseSyntaxError: Syntax error in input : unexpected end of expression (maybe due to unmatched parenthesis) at the end!

This error occurs when the input Lucene query string is syntactically incomplete or malformed, often due to unclosed parentheses or an incomplete expression at the end.

fix

Correct the Lucene query string to ensure all parentheses are matched and the expression is complete and valid.

luqum.exceptions.ParseSyntaxError: Syntax error in input : unexpected '%s' at position %d!

This is a general syntax error indicating that the parser encountered an unexpected token or character at a specific position within the Lucene query string.

fix

Review the Lucene query string around the indicated position (`%d`) and correct any invalid characters, operators, or syntax.

Upgrade

Version history

1.0.0latest on PyPI · released Feb 18, 2025

Audit

Dependencies

PLYrequiredUsed for parsing Lucene Query DSL.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/jurismarches/luqum ↗

packagehttps://pypi.org/project/luqum/ ↗