YAQL - Yet Another Query Language

Common errors

• YaqlEvaluationException: Unable to evaluate expression ''$.data.distinct()''. TypeError: unhashable type: 'dict'

  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.
  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.

• NameError: name 'yaql' is not defined

  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`.
  fix Add `import yaql` at the top of your Python script or `from yaql.factory import YaqlFactory` if directly accessing the factory.

• SyntaxError: invalid syntax (in YAQL expression)

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• pip install yaql Install latest version

Imports

• YaqlFactory
  wrong:

  import yaql.factory.YaqlFactory

  correct:

  from yaql.factory import YaqlFactory

  While `import yaql` is common, `YaqlFactory` is within a submodule and should be imported directly for clarity and explicit access.
• yaql

  import yaql

  This imports the main library, allowing access to functions like `yaql.create_context()`.

Quickstart

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)}")