The Variable System

The Variable System#

EQL variables are more than just placeholders; they are active components of the execution graph that know how to resolve data from object instances.

CanBehaveLikeAVariable#

The CanBehaveLikeAVariable mixin is what makes EQL so “pythonic.” It overrides standard Python dunder methods to capture operations and turn them into symbolic expressions.

  • __getattr__: Captures attribute access and returns an Attribute.

  • __getitem__: Captures indexing and returns an Index.

  • __call__: Captures method calls and returns a Call.

Hint

This is why you can write robot.name == "R2D2". The robot variable captures the .name access and returns a symbolic Attribute node.

Mapped Variables#

A MappedVariable is a UnaryExpression that transforms the value of its child.

1. Attribute#

Represents access to a Python attribute. During evaluation, it uses getattr(value, name).

2. Index#

Represents access to a dictionary key or list index. It uses value[key].

3. Call#

Represents a symbolic method call. It stores the arguments and keyword arguments, and executes the call during evaluation.

Note

Mapped variables are cached internally to ensure that the same symbolic path (e.g., robot.name) always resolves to the same expression object within a query context.

Flattening with FlatVariable#

The FlatVariable is a special mapped variable used when an attribute returns an iterable, but you want to treat its elements as individual bindings in the result stream.

Note

Use flat_variable() explicitly when you want to iterate over elements of attributes that are iterable. Standard attribute access on an iterable valued attribute will return the iterables as values, not their elements.

API Reference#