API: query

Search, filter, and extract data from STL documents.

Module: stl_parser.query Import: from stl_parser import find, find_all, filter_statements, select, stl_pointer

find()

find(result: ParseResult, **kwargs: Any) -> Optional[Statement]

Find the first statement matching all conditions (AND logic).

Parameters:

Returns: First matching Statement, or None.

Example:

stmt = find(result, source="Rain", confidence__gte=0.8)

find_all()

find_all(result: ParseResult, **kwargs: Any) -> List[Statement]

Find all statements matching all conditions.

Returns: List of matching Statement objects (empty if none).

Example:

causal = find_all(result, rule="causal")

filter_statements()

filter_statements(result: ParseResult, **kwargs: Any) -> ParseResult

Filter a ParseResult to only matching statements. Returns a new ParseResult; the original is unmodified.

Example:

filtered = filter_statements(result, confidence__gte=0.8)
print(len(filtered.statements))

select()

select(result: ParseResult, field: str) -> List[Any]

Extract a single field value from every statement.

Parameters:

Returns: List of values (includes None for absent fields).

Field Resolution Order:

1. Special fields: source, target, source_namespace, target_namespace, arrow
2. Standard modifier fields: confidence, rule, strength, etc.
3. Custom modifier fields

Example:

names = select(result, field="source")       # ["Rain", "Wind", ...]
confs = select(result, field="confidence")   # [0.85, 0.7, None, ...]

stl_pointer()

stl_pointer(result: ParseResult, path: str) -> Any

Access a nested value by slash-delimited path (inspired by JSON Pointer RFC 6901).

Path format: /<statement_index>/<attribute>[/<sub_attribute>...]

Examples:

Raises: STLQueryError (E450-E453) if path is invalid or index out of range.

Operators

Use double-underscore suffixes on field names:

All conditions are combined with AND logic.