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.
//
// List membership (`field in [a, b]`, `field not in [a, b]`) is stare-only
// syntax: the server has no such operator, so the parser expands it into an
// OR of `=` (or an AND of `!=`) before anything is sent.

?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
     | list_condition
     | "(" expression ")"
condition: field OP value              -> condition
list_condition: field LIST_OP "[" list_value ("," list_value)* "]"

field: IDENT | STRING
value: VALUE | STRING
list_value: LIST_VALUE | STRING

OP: "=" | "!=" | "contain"i | "not-contain"i
LIST_OP: /(not\s+)?in/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()"]+/
// Unlike VALUE, a bare list item stops at commas and square brackets; quote
// an item that contains them.
LIST_VALUE: /[^\s()",\[\]]+/
STRING: /"[^"\n\r\t\f\v]*"/

%import common.WS
%ignore WS

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

Operators

# Analyses tagged with the "5.02 TeV" keyword, among others
stare analysis search -q 'metadata.keywords.name contain "5.02 TeV"'

# 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.name, 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 = ANA-HION-2018-01'
stare analysis search -q '"referenceCode" = ANA-HION-2018-01'
stare analysis search -q 'referenceCode = "ANA-HION-2018-01"'

# Multi-word values require quotes:
stare analysis search -q 'shortTitle = "Low-mass single diffraction"'
stare paper search -q '"phase2.state" = "Phase 2 Finished"'

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 Closed 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.name contain jets'

# space in value — quotes required
stare analysis search -q 'shortTitle = "Low-mass single diffraction"'

# quoted field, bare value — both forms mix freely
stare analysis search -q '"status" = Closed'

Date fields only match a YYYY-MM-DD value. The API returns full ISO datetimes (e.g. 2017-12-20T00:00:00+01:00), but filtering on that string matches nothing (ATGLANCE-8334), so use only the date part:

# the API returns 2017-12-20T00:00:00+01:00 for this field
stare analysis search -q 'phase0.eoiMeetings.date = 2017-12-20'

Combining conditions

# AND (both must match)
stare analysis search -q 'status = "Phase 0 Active" and groups.leadingGroup.name = HMBS'

# OR (either may match)
stare analysis search -q 'status = "Phase 0 Active" or status = Created'

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

Use parentheses to group an OR under an AND:

# Not closed, and led by either EGAM or MUON
stare analysis search -q 'status != Closed AND (groups.leadingGroup.name = EGAM OR groups.leadingGroup.name = MUON)'

Only the parentheses that change the meaning are sent (status != Closed AND (… OR …)). Redundant parentheses, such as around the whole query or around an AND inside an OR, are dropped.

Lists

field in [a, b, c] matches any of the listed values, and field not in [a, b, c] matches none of them:

stare analysis search -q 'status != Closed AND groups.leadingGroup.name in [EGAM, MUON, JETM]'
stare analysis search -q 'status not in [Closed, "Phase 0 Finished"]'

The Glance API has no list operator, so stare expands these before sending: in becomes an OR of = (grouped with parentheses when combined with AND), and not in becomes an AND of !=. The first example is sent as:

status != Closed AND (groups.leadingGroup.name = EGAM OR groups.leadingGroup.name = MUON OR groups.leadingGroup.name = JETM)

List items follow the usual value rules, except that a bare item also ends at a comma or square bracket. Quote any item that contains spaces, commas, or brackets: shortTitle in ["Flow in Xe+Xe", "a, b"]. An empty list [] is a syntax error.

Sorting

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

stare analysis search -q 'status = "Phase 0 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

Plot fields

Paper fields

Publication fields

Leading group fields

Subgroup fields

Trigger fields