Skip to main content
The API uses type for Database and app for Space. See Terminology.
Install the Cricket template into your own workspace to run every example in the Entities section as-is.

​
Overview

The general shape of an entity query is:
The clauses are directly analogous to SQL’s from, select, where, offset, order by and limit. q/from, q/select and q/limit are required. This section describes a comprehensive example. See the sections below for a more detailed explanation:
  • select Fields
  • filter Entities
  • order Entities
Get info about cricket players born since 1986 ordered by height and age:
Response:
Command parameters Cricket/Player Database used as an example

​
Select Fields

In this example we demonstrate the select form known as “vector select”. It’s general form is:
<field-name> is used for primitive fields (strings, numbers, booleans and the like). For example, to select id and name (both are text fields):
<field-name> won’t work for fields that point to other entities, because it’s not clear what to include as the value. So the query must specify which fields from the referenced entity to include, and that’s what the <vec-dereference> form does. Here, to add the id of the user in created-by, we add the {thisField: [targetFields] selector:
In the example above, fibery/created-by points to at most one user. When we have a field that point to many entities, that is a collection field, we should have a way to filter them. The dereference form is not sufficient and the <vec-subselect> form must be used. The subselect expression is a full query of its own (a subquery). Here we add to each result also a collection of assignees, where for each assignee we select only one field, id:
Note that in some cases empty collections are returned as nulls. In the example below we query entities from the Cricket/Player database and select:
  • a primitive Field Cricket/Full Name of primitive type fibery/text
  • a single-select Cricket/Batting Hand
  • a related entity Cricket/Current Team
  • an entity collection Field Cricket/Former Teams
  • an aggregate (the oldest former team year of foundation).
Response:

​
Select aggregates

select-func is a Lisp-style function call
Available entity collection Field aggregates
  • q/count
  • q/sum
  • q/avg
  • q/min
  • q/max
It doesn’t matter if a Field is populated manually or via a Formula/Lookup — the query stays exactly the same.

​
Select count

Count is the only aggregate which can be used on the top level:
Response:

​
Filter Entities

Filters (where) go into the q/where clause of the query. The general form is inspired by Lisp: it’s a list where the first element is an operator and the remaining elements are the values to check using the operator:
In these examples we filter by:
  • a primitive Field (height)
  • two primitive Fields (birth date and retirement status)
  • a single-select (batting hand)
  • an entity Field (current team)
  • an entity collection Field (former teams)
We don’t compare Entity’s Field to a value directly, but use a $param instead. Cricket/Player Database used as an example Filter operators by field type Filter combinators q/and and q/or take multiple filter clauses as operands:
Examples Get players taller than 1.75 meters — primitive Field:
Response:
Filters can be nested and combined using q/and and q/or. Here we are querying players who started their youth career before 2004 and haven’t retired yet:
Response:
Get right-handed players — single-select:
Response:
Get players whose current team was founded before 2000 — entity Field:
Response:
Get players who previously played for Yorkshire or Derbyshire — entity collection Field:
Response:

​
Filter by current user

$my-id is a special parameter that resolves to the id of the authenticated user. Use it to filter by the caller without hardcoding a user id — for example, to fetch entities assigned to or created by the current user. No params entry is needed. Get info about the current user:
The same parameter works inside any filter that references a user — for example, ["=", ["Tasks/Assignee", "fibery/id"], "$my-id"] to get tasks assigned to the current user.

​
Order Entities

Sort Entities by multiple primitive and entity Fields. The default sorting is by creation date and UUID: [ [["fibery/creation-date"], "q/asc"], [["fibery/id"], "q/asc"] ] Sorting by fibery/id guarantees that Entities order won’t change on different executions of the same query. It is also the basis of cursor pagination. Cricket/Player Database used as an example
Response: