Skip to content
HamstikHamstik Docs

SqueakQL syntax and precedence

Shape of a query

[expression] [ORDER BY field [ASC|DESC], ...]

The expression is optional, so an empty predicate can be useful with an order in an integration. The web editor and API request still expect a non-empty query string so accidental full-organization searches are visible.

SqueakQL accepts PostgreSQL-inspired expressions only. It does not accept SELECT, FROM, JOIN, WITH, UNION, LIMIT, OFFSET, comments, or multiple statements.

Boolean precedence

From highest to lowest:

  1. Parentheses and predicates
  2. NOT
  3. AND
  4. OR

This query:

status = 'todo'
OR status = 'in_progress'
AND priority = 'urgent'

means:

status = 'todo'
OR (status = 'in_progress' AND priority = 'urgent')

Use parentheses when the grouping matters:

(status = 'todo' OR status = 'in_progress')
AND priority = 'urgent'

Case behavior

Keywords such as and, AND, and And are equivalent. Canonical field names are lowercase and field lookup is case-insensitive, but lowercase names are recommended for readable shared queries.

Function names are also case-insensitive. Enum values must use the exact lowercase values listed under fields. Text equality and LIKE are case-sensitive; ILIKE and has_label() are case-insensitive. Project and Work Item keys use their stored uppercase form for equality, unlike the public API’s case-normalized Project path lookup. Use ILIKE when case-insensitive key matching is wanted. Sprint names are ordinary text.

Strings

Strings use single quotes. A single quote inside a string is doubled:

title = 'Sam''s webhook fix'

Semicolons and comments are not string escapes. A semicolon outside a quoted string is rejected as syntax.

String data supports Unicode, including emoji. Null bytes and unpaired UTF-16 surrogates are rejected. Diagnostic offsets and columns count UTF-16 code units; tabs count as one column, and LF and CRLF both advance to the next line.

Limits

Queries allow at most 4,096 UTF-16 code units, 256 tokens, 200 parser nodes, 32 nested parentheses/NOT levels, 100 unique IN values, and 5 ORDER BY entries. Function arguments are values, so nested function calls are not supported. Request strings must contain non-whitespace text; ORDER BY key is an explicit way to search all authorized active Work Items.