Skip to main content

Relations, Nesting, and Recursion

This page explains how a query follows relations: what To, From, and Both mean, how multi-step paths work, how related queries nest, and how to walk a self-referential relation such as "all sub-tasks of a task".

Parent filters and relation filters​

A relation filter describes one step through a relation type. It is used in two places:

WhereNamePurpose
In an Instance QueryParent filtersRestrict the returned instances to those connected to given parent instances. The direction is fixed: the filter's type is the parent of the returned instances, and a direction value, if sent, is ignored. A query accepts at most 20 parent filters by default.
In a Relation Query or a related queryRelation filtersDefine the path from a source instance to the related instances to return.

Each relation filter contains:

FieldDescription
Type (typeName)The type of the instances at this step. Required.
Relation type (relationTypeName)The relation type to follow. Required.
Direction (relationDirection)To, From, or Both. If omitted it defaults to From, so always set it explicitly.
Instance (instanceId, instanceIds)Optional. Pins the step to one or more specific instances.
State filters (stateFilters)Optional. State names for the instances at this step (any of).
Attribute filters (attributeFilterExpressions)Optional. Conditions on the instances at this step.

Parent filters in detail​

Parent filters narrow an Instance Query to instances that sit under given parent instances. They behave as follows.

Several parent filters form a chain, not a set of independent conditions. Filters are applied in their listed order, and each one leads to the next:

OrderRoleExample
First filterThe topmost ancestorType Program, relation ProgramToProject
Next filtersThe following level downType Project, relation ProjectToTask
Last filterThe direct parent of the returned instancesThe returned type is Task

Each filter's relation type connects its type to the type of the next filter, and the last filter's relation connects to the returned type. To require two unrelated parents, run two queries.

Parent filter chain in Design Studio Two parent filters on a ProjectAllocation query. Read top to bottom: ProjectAccount (relation ProjectAccountToProject), then Project (relation ProjectToProjectAllocation), then the returned ProjectAllocation records.

How a single filter selects its parent instances:

What you set on the filterEffect
instanceIdOnly that parent. If the user cannot access it, the query fails with 403.
instanceIdsAny of these parents. Parents the user cannot access are left out.
stateFilters and/or attributeFilterExpressionsThe parents are first looked up by those conditions (on the filter's type), and only instances under those parents are returned.
Instance ids together with conditionsOnly parents that satisfy both.
Nothing (no instance, no conditions)Instances that have any parent of that type through that relation.
  • If the conditions match no parent, the query returns no instances.
  • A query accepts at most 20 parent filters by default; more fails the request.
  • The relation direction of a parent filter is fixed, and a direction value is ignored.
  • Attribute conditions on a parent filter use the same value formats as any other condition, and are evaluated against the parent's type.
  • In a saved query, a parent filter can be dynamic: its parameter resolves to parent instance identifiers. See Query Parameters.
  • Parent filters are evaluated with the caller's permissions, so inaccessible instances never contribute.

Direction​

In a relation query, the source is the instance that the query starts from (the current instance, or the instance returned by the parent level). The filter's type is the type of instance you want back. A relation type has a From end and a To end, as defined on the relation type.

DirectionWalkThe source is at the relation'sThe result is at the relation's
ToAlong the relation, for example ProjectToTask: from a Project to its TasksFrom endTo end
FromAgainst the relation, for example from a Task back to its ProjectTo endFrom end
BothNot supported. As the first (or only) step the request fails. In a later step it is silently skipped, which gives wrong results. Never send it; use one To query and one From query.
Choose the direction from the relation type

Look at the relation type's From and To ends in the schema before choosing a direction. Using the wrong direction returns no related instances instead of an error.

Multi-step paths​

A relation query can contain several relation filters. They are applied in order: the result of each step is the source of the next one, and the last filter's type is the type that is returned.

Example (relation names are illustrative): documents of a project.

StepTypeRelation typeDirection
1DeliverableProjectToDeliverableTo
2DocumentDeliverableToDocumentTo
  • Each step can add state and attribute criteria, so unrelated records do not enter the result.
  • An intermediate step pinned to a specific instance must really be related to the previous step; otherwise the query fails.
  • State and attribute filters of the query itself apply to the last step (the returned instances).

An Instance Query (or a Structured Query) can carry related query definitions that attach related instances to every returned instance. Each related query definition can itself carry further related query definitions.

Instance Query (Task)
└─ Related query: Task → sub-Task (level 1)
└─ Related query: sub-Task → sub-Task (level 2)
└─ ...
TopicBehavior
DepthAny depth. No depth limit is enforced.
ExecutionEach level runs once for all instances found by the level above, then its own nested queries run for the instances it found. A level with no results stops the descent.
Which instancesRelated items are attached only to the instances in the returned page.
Result shapeRelated instances appear under relatedItems of each instance, keyed by the type name of the last relation filter. Each related instance can have its own relatedItems.
Siblings with the same target typeTwo related queries at the same level that return the same type are merged under one key: their items are combined, and the total count is the larger of the two. Use one related query per target type per level.
Pagingskip, take, and the total count of a related level count relation rows across all source instances, not per source instance. Allow a generous take when there are many source instances.
SortingUse the related query's sortBy. A separate sortOrders list is ignored when a query is sent to the API.
PermissionsRelated instances the user cannot access are left out. See Query Builder API.

Recursion: walking a self-referential relation​

A relation that connects a type to itself, such as Task to sub-Task, can be followed, but not recursively to unlimited depth. A query follows exactly as many levels as it contains. There is no "until the end of the hierarchy" option.

To answer "all sub-tasks of T-72-191":

  1. Nest a fixed depth. Repeat the same related query at each level, for example 5 to 10 levels deep. The levels beyond the real depth return nothing and stop the descent.
  2. Or query level by level. Run a query for the sub-tasks of the task, then another for the sub-tasks of the instances found, and stop when a level returns no instances.
Be explicit about depth

If the data can be deeper than the levels you query, say so in any answer built from the result, because deeper levels are not returned. Cost grows with both depth and the number of instances per level, so keep the depth purposeful.

In a self-referential walk, the key under relatedItems is the same type name at every level (for example Task).

See the worked example in Query Builder API for a two-level sub-task query.