Skip to main content

StarQL

About these examples

Starhive has no prose StarQL spec anywhere — the grammar file and its test suite are the closest thing to ground truth, so this page is written directly from those. Every example below is a real, working query taken from the parser's test suite.

StarQL is Starhive's own query language — not SQL, not GraphQL — used to filter objects everywhere a query is needed: type filters, views, sites, widgets, and automations, and directly through the public API's search endpoints.

Basic comparisons​

Name = Mathias
Name != Mathias
Name !== "Mathias Edblom"

Quote a value if it contains spaces.

Combining conditions​

Manager = Mathias AND Owner = Tommy
Manager = Mathias OR Owner = Tommy
Manager = Mathias OR (Owner = Tommy AND Product = PIM)

Traversing references​

Dot notation follows a reference attribute to a field on the referenced object:

Owner.Manager = Tommy
Owner.Manager.Admin = Tommy

For more complex traversal, -> (outbound) and <- (inbound) run a nested StarQL query against referenced objects:

Owner -> starQL(Mathias = Tommy AND Product = PIM)
@Objects <- starQL(@Objects <- starQL(Name = "A name")) AND Available = false

Set membership and emptiness​

Owner IN (MATHIAS, Tommy)
Owner NOT IN ("MATHIAS")
Owner IS EMPTY
Owner IS NOT EMPTY
Owner IS ENDSTATE

Ordering results​

Manager = Mathias order by 1
Manager = Mathias order by Manager ASC
order by 1 ASC, 2 DESC

Querying history​

WAS queries a field's past state, optionally restricted to a date window with BETWEEN:

Status was in ("ToDo", "In Progress")
Status was > 100
Status WAS IN ("ToDo") BETWEEN ("2012-01-01", "2012-12-31")

System attributes​

Attributes prefixed with @ refer to built-in system fields rather than your own attributes: @Space, @SpaceId, @Type, @TypeId, @Objects, @ObjectId, @User, @Label, @WorkflowStateId, @WorkflowStateName, @Sequence, among others.

@Space = PIM

Functions​

FunctionPurpose
userEmail(...), userCurrent(), userCurrentEmail(), userGroup(...), userId(...)Reference users
now(...), startOfDay(), endOfDay(), startOfWeek(), endOfWeek(), startOfMonth(), endOfMonth(), startOfYear(), endOfYear()Relative dates and times
dateRangeEqual(...), dateRangeIntersects(...), dateRangeContains(...), dateRangeWithin(...)Date range comparisons
radius(lat, lng, distance), polygon(...)Location queries
CIDR(...)IP address range matching
stateId(...)Workflow state lookup
countStarQL(...)Count objects matching a nested query, usable in a comparison
Owner = userEmail("mathias@starhive.com")
Created >= now(-1h)
Address = radius(59.330397, 8.0559602, 1km)
Doors >= countStarQL("Brand and model" = "Volvo XC90")

Comparison operators​

=, ==, !=, !==, <, >, <=, >=, plus string matching with * (contains), #* (starts with), *# (ends with), and ~ (fuzzy match).

Which operators apply to which attribute type​

Not every operator applies to every attribute type — see that page for full worked examples per type. As a quick reference:

  • Equality (=, ==, !=, !==) — every type except Boolean (only =/!=) and Rich text (neither).
  • Set membership (in/not in) and emptiness (is empty/is not empty) — every type.
  • History (was, was =, was !=, was in, was not in) — every type; ordered types additionally support was <, was <=, was >, was >=.
  • String matching (~, *, !*, #*, *#) — Text, Option, User, Email, URL, Media, Priority, Composite, Location, Workflow, Reference, SLA, Sequence. Rich text only gets */!* (no anchoring or fuzzy). Not available on purely numeric/date/boolean types.
  • Ordering (<, >, <=, >=) — Integer, Decimal, Date, DateTime, Rating, Completeness, Calculated, Depreciation, and Sequence (numeric comparison even with a text prefix).

Errors​

A malformed or semantically invalid query returns HTTP 400 with the message "Provided StarQL query is invalid" (see Public API) — this covers both queries that fail to parse and ones that parse but reference an unknown attribute or an operator that doesn't apply to that attribute's type.