Skip to content

API queries

Queries provide read-only access to schema-defined data through the API.

All queries are evaluated against the active schema and return only data that is visible to the authenticated user. Read rules are enforced automatically and rows that are not visible are excluded from the result.

Queries support both single-row access and collection queries, including traversal of relations where permitted.

Characteristics

Query execution has the following characteristics:

  • Read rules are enforced
  • Classifications may be used as filters
  • Nested relational selection is supported

Queries never bypass read rules.
If a row is hidden by read rules, it will not appear in the query result.

Query scope

The API exposes two primary query scopes.

Single-row queries

Single-row queries return a single record identified by id or _id.

Example:

query {
  person(id: 123) {
    id
    _id
    first_name
    last_name
  }
}

Collection queries

Collection queries return multiple rows from a table.

Example:

query {
  persons {
    id
    _id
    first_name
    last_name
  }
}

Relation traversal

Queries may include nested selections to retrieve related records.

Relations can be traversed freely unless limited by read rules.

Example:

query {
  persons {
    id
    first_name
    addresses {
      id
      city
    }
  }
}

The returned data always reflects the permissions of the authenticated user. Rows that are not visible due to read rules are omitted from the result.

Related concepts