Query DSL

The --query / -q flag on stare search commands accepts a simple filter expression validated and normalized client-side before being sent to the server. Each search command validates against the field catalogue for its own record type. See the endpoint status table for which commands currently accept --query.

Grammar

// Generic DSL grammar — no field names hard-coded.
// Syntax only; field/operator semantics validated downstream.
//
// NULL sentinel: the API-defined token __EMPTY__ (quoted or bare) is used to
// compare a field against NULL, e.g.  "publicShortTitle" = "__EMPTY__".
// It is matched as an ordinary VALUE (bare) or STRING (quoted) — no special rule.

?expression: or_expr
?or_expr: and_expr
        | or_expr _OR and_expr          -> or_expr
?and_expr: term
         | and_expr _AND term           -> and_expr
?term: condition
     | "(" expression ")"
condition: field OP value              -> condition

field: IDENT | STRING
value: VALUE | STRING

OP: "=" | "!=" | "contain"i | "not-contain"i
_AND: /[Aa][Nn][Dd]/
_OR:  /[Oo][Rr]/

IDENT: /[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*/
VALUE: /[^\s()"]+/
STRING: /"[^"\n\r\t\f\v]*"/

%import common.WS
%ignore WS

and / or are case-insensitive at parse time; canonical output is uppercase (AND, OR).

Operators

# Find analyses with no public short title set
stare analysis search -q 'publicShortTitle = "__EMPTY__"'

# Find papers where shortTitle is not NULL
stare paper search -q 'shortTitle != "__EMPTY__"'

Field names

Fields accept either camelCase or snake_case — both are normalized to camelCase before being sent to the server:

# These are equivalent:
stare analysis search -q 'referenceCode = ANA-HION-2018-01'
stare analysis search -q 'reference_code = ANA-HION-2018-01'

Nested fields use a dot separator: metadata.keywords, phase0.state.

Quoting

Both the field name and the value may optionally be wrapped in double quotes. Quotes are required on the value when it is empty or contains spaces, parentheses, or square brackets; for everything else they are optional.

The grammar's string token (STRING: /"[^"\n\r\t\f\v]*"/) restricts quoted values to printable characters plus spaces — it excludes embedded double-quotes and all non-space whitespace (tabs, newlines, carriage returns, form feeds, and vertical tabs). Values containing any of those characters are rejected at parse time. If your value contains a literal ", use contain with a non-quote substring instead; escaped-quote support is not yet implemented.

# These are equivalent:
stare analysis search -q 'referenceCode = HION'
stare analysis search -q '"referenceCode" = HION'
stare analysis search -q 'referenceCode = "HION"'

# Multi-word values require quotes:
stare analysis search -q 'shortTitle = "Phase Closed"'
stare paper search -q '"phase2.state" = "Phase Closed"'

Canonical output (to_dsl()) emits quotes on the value only when they are required; bare single-token values are always emitted unquoted. Fields are always emitted bare after normalization.

Only " (double quotes) are accepted — single quotes are not special.

Values

Values are bare tokens or double-quoted strings. A bare value like ANA-HION-2018-01 or Active works without quotes. Double quotes are required when the value is empty or contains spaces, parentheses, or square brackets:

# bare value — no quotes needed
stare analysis search -q 'metadata.keywords contain jets'

# space in value — quotes required
stare analysis search -q 'shortTitle = "Phase Closed"'

# quoted field, bare value — both forms mix freely
stare analysis search -q '"phase0.state" = Active'

Combining conditions

# AND (both must match)
stare analysis search -q 'status = Active and groups.leadingGroup = HDBS'

# OR (either may match)
stare analysis search -q 'status = Active or status = Approved'

AND binds tighter than OR: a = 1 AND b = 2 OR c = 3 is parsed as (a = 1 AND b = 2) OR c = 3.

Sorting

--sort-by and --sort-desc are independent of the query string and work with any search command:

stare analysis search -q 'status = Active' --sort-by creationDate --sort-desc
stare paper search --sort-by referenceCode

Skipping validation

Use --no-validate to bypass client-side field checking and send the raw string directly to the server. This is useful for experimental server fields or when you know the DSL is already in canonical form:

stare analysis search -q 'someNewField = value' --no-validate

Analysis fields

CONF note fields

PUB note fields

Paper fields

Publication fields

Leading group fields

Subgroup fields

Trigger fields