Query API

Find elements in a snapshot using semantic queries. The Query API provides two functions: find() for single matches and query() for multiple matches.

find() - Single Best Match

Finds the single best matching element (by importance score).

from sentience import find

button = find(snap, "role=button text~'Submit'")
if button:
    print(f"Found: {button.text} (importance: {button.importance})")

Returns: Element object or None / null if not found

query() - All Matches

Finds all matching elements (returns list/array).

from sentience import query

all_buttons = query(snap, "role=button")
print(f"Found {len(all_buttons)} buttons")

Returns: List/array of Element objects

Query DSL Operators

The query selector uses a simple DSL (Domain-Specific Language) with the following operators:

• = - Exact match: "role=button"
• != - Not equal: "role!=link"
• ~ - Contains (case-insensitive): "text~'sign in'"
• ^= - Starts with: "text^='Add'"
• $= - Ends with: "text$='Cart'"
• >, >=, <, <= - Numeric comparisons: "importance>500"

Query Examples

# Find by role
button = find(snap, "role=button")

# Find by text (contains)
link = find(snap, "role=link text~'more info'")

# Multiple conditions (AND)
primary_btn = find(snap, "role=button clickable=true importance>800")

# Spatial filtering
top_left = find(snap, "bbox.x<=100 bbox.y<=200")

# Visibility checks
visible_link = find(snap, "role=link visible=true in_viewport=true")

Common Patterns

Find primary buttons:

primary_button = find(snap, "role=button is_primary=true")

Find all clickable elements:

clickable = query(snap, "clickable=true")

Find elements with high importance:

important = query(snap, "importance>700")

Find visible elements in viewport:

visible = query(snap, "in_viewport=true visible=true")