Install & Compatibility
Where this runs
tested against v3.2.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 21.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.000s · 22MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YaqlFactory
✓ from yaql import YaqlFactory
✗ from yaql import YaqlFactory
This quickstart demonstrates how to initialize the YAQL engine, load a data source, and execute simple YAQL expressions to filter and select data. The `data` keyword argument is used to pass the input data to the engine.
import yaql
from yaql.factory import YaqlFactory
data_source = {
'customers': [
{'name': 'John Doe', 'age': 30, 'city': 'New York', 'orders': [{'id': 1, 'amount': 100}, {'id': 2, 'amount': 250}]},
{'name': 'Jane Smith', 'age': 24, 'city': 'London', 'orders': [{'id': 3, 'amount': 150}]},
{'name': 'Peter Jones', 'age': 35, 'city': 'New York', 'orders': []}
]
}
# Create a YAQL engine
engine = YaqlFactory().create()
# Evaluate an expression to find customers in New York
expression = '$.customers.where($.city = "New York")'
result = engine(expression)(data=data_source)
print(f"Customers in New York: {list(result)}")
# Evaluate an expression to get names of customers with orders
expression_with_orders = '$.customers.where($.orders.len() >= 1).select($.name)'
result_with_orders = engine(expression_with_orders)(data=data_source)
print(f"Customers with orders: {list(result_with_orders)}")
Debug
Known issues
gotchaYAQL is designed to keep input data unchanged. Functions that appear to modify data actually return an updated copy, preserving the original data. This design also contributes to its thread-safety. Directly modifying input data structures from within YAQL functions can lead to unexpected behavior.fixAlways treat data passed into YAQL expressions as immutable. If modifications are needed, ensure your custom YAQL functions return new, modified copies of the data instead of altering the originals in-place.
affects: All versions
gotchaThere is no built-in syntax in YAQL to explicitly check if a variable exists versus being set to `null`. If a variable is not provided, it is implicitly assumed to be `null` when accessed. This can lead to ambiguity if you need to differentiate between a variable that doesn't exist and one that explicitly holds a `null` value.fixStructure your data to avoid ambiguity where 'not present' and 'null' have different semantic meanings, or implement custom YAQL functions or a custom context to handle explicit variable existence checks if required.
affects: All versions
breakingOlder versions of YAQL could raise a `YaqlEvaluationException: TypeError: unhashable type: 'dict'` when using methods like `distinct()` on an array of dictionaries. This was a bug related to how YAQL handled dictionary hashing within certain operations.fixUpgrade to YAQL version 3.2.0 or later, as this specific issue was resolved. If upgrading is not immediately possible, consider transforming the array of dicts into a simpler, hashable structure before applying `distinct()` or similar operations, or implement a custom distinct function.
affects: < 3.2.0 (specifically fixed before or in 3.2.0)
Upgrade
Version history
3.2.0latest on PyPI · released Oct 9, 2025
Audit
Dependencies
No dependency data recorded yet.