{"id":8792,"library":"yaql","title":"YAQL - Yet Another Query Language","description":"YAQL (Yet Another Query Language) is an embeddable and extensible Python query language designed to perform complex queries against arbitrary objects. It features a comprehensive standard library of querying functions and supports user-defined extensions. The current version is 3.2.0, actively maintained with infrequent releases, and it is distributed via PyPI.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://yaql.readthedocs.io/en/latest/","tags":["query language","data transformation","json","yaml","expression language"],"install":[{"cmd":"pip install yaql","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"While `import yaql` is common, `YaqlFactory` is within a submodule and should be imported directly for clarity and explicit access.","wrong":"import yaql.factory.YaqlFactory","symbol":"YaqlFactory","correct":"from yaql.factory import YaqlFactory"},{"note":"This imports the main library, allowing access to functions like `yaql.create_context()`.","symbol":"yaql","correct":"import yaql"}],"quickstart":{"code":"import yaql\nfrom yaql.factory import YaqlFactory\n\ndata_source = {\n    'customers': [\n        {'name': 'John Doe', 'age': 30, 'city': 'New York', 'orders': [{'id': 1, 'amount': 100}, {'id': 2, 'amount': 250}]},\n        {'name': 'Jane Smith', 'age': 24, 'city': 'London', 'orders': [{'id': 3, 'amount': 150}]},\n        {'name': 'Peter Jones', 'age': 35, 'city': 'New York', 'orders': []}\n    ]\n}\n\n# Create a YAQL engine\nengine = YaqlFactory().create()\n\n# Evaluate an expression to find customers in New York\nexpression = '$.customers.where($.city = \"New York\")'\nresult = engine(expression)(data=data_source)\nprint(f\"Customers in New York: {list(result)}\")\n\n# Evaluate an expression to get names of customers with orders\nexpression_with_orders = '$.customers.where($.orders.len() >= 1).select($.name)'\nresult_with_orders = engine(expression_with_orders)(data=data_source)\nprint(f\"Customers with orders: {list(result_with_orders)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"YAQL 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Structure 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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade 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.","message":"Older 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.","severity":"breaking","affected_versions":"< 3.2.0 (specifically fixed before or in 3.2.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are using YAQL version 3.2.0 or higher. If the problem persists with custom types, ensure that objects intended for `distinct()` or similar set-like operations implement `__hash__` and `__eq__` methods correctly.","cause":"Attempting to use `distinct()` on a collection containing unhashable types, such as dictionaries, in older versions of YAQL where this was a known bug.","error":"YaqlEvaluationException: Unable to evaluate expression ''$.data.distinct()''. TypeError: unhashable type: 'dict'"},{"fix":"Add `import yaql` at the top of your Python script or `from yaql.factory import YaqlFactory` if directly accessing the factory.","cause":"The `yaql` module was not imported before attempting to use its functions or factory. This commonly happens if trying to use `yaql.factory.YaqlFactory()` without `import yaql` or `from yaql.factory import YaqlFactory`.","error":"NameError: name 'yaql' is not defined"},{"fix":"Carefully review the YAQL expression against the official YAQL language reference documentation. Pay attention to variable access (`$variable` or `$`), string literal quoting (single or double quotes), and correct operator usage. Debug by evaluating smaller parts of the expression or by using the YAQL REPL tool.","cause":"The YAQL expression string contains syntax errors, such as unmatched quotes, incorrect operators, or invalid function calls according to YAQL's grammar. This is particularly common when transitioning from other query languages or not fully understanding YAQL's specific syntax for variable access (`$`), function calls, and operators.","error":"SyntaxError: invalid syntax (in YAQL expression)"}]}