Types, attributes, and value-variables can be projected directly into JSON by using their variable in a fetch clause.

Every instance in the JSON output has its type, root type, and value (if applicable).

See the Fetch an attribute and the Fetch a type or a value variable examples below.

Not every type can have a value to fetch. Fetch always needs a value to project into JSON. Hence, entities and relations can be used as variables in a fetch clause only by extracting attributes that they have.

To extract owned attributes, we use a variable followed by a colon and a list of comma-separated attribute-types. Every attribute type mentioned in this way adds a JSON subsection with the list of instances of that attribute type owned by the matched concept from a variable.

See the Fetch all attributes owned example below.

A fetch clause support relabeling of variables and attribute types. You can assign a new label which will be used for JSON output.

To relabel a variable or an attribute type, add the as keyword followed by a new label. By surrounding a new label in double quotes, you can use whitespaces in it.

See the Customize output example below.

A Fetch query can include a subquery in a fetch clause: another Fetch query or a Get query with aggregation (to return a value). A subquery consists of label, colon, and a TypeQL query string surrounded by curly brackets.

The label determines the key that will be used to introduce results of the subquery into the JSON output.

A subquery shares variables with its parent query. At least one variable from a parent query must be used in a subquery.

The number of nested subqueries is not limited, but many nested levels can break technical limitations of gRPC messaging.

For an example of nested subqueries, see the Grouping results section below.

A Fetch query can return fewer results, than it was matched by its match clause. Excluding the usage of modifiers, that can happen due to natural deduplication of results. See an example below.

In the above example match clause matches all person type instances that own a name attribute. The fetch clause then returns values of those name attributes.

What happens if two persons have the same name? In TypeDB database that is stored, as two entities own the same attribute (instance of the name attribute type). The match clause finds all pairs of a person entity and its owned attribute. But fetch clause returns only the values of attributes. Since both persons own the very same attribute, it will be returned only once, reducing the total number of results.

For more examples of filtering matched results, see the Get query page.

Use the sort keyword followed by a variable to sort the results. A second argument is optional and determines the sorting order: asc (ascending, by default) or desc (descending).

This query returns sorted values of all full-name attributes owned by person entities.

To sort by multiple variables, add additional variables with a comma separator.

Use the offset keyword followed by the number to offset the results. This is commonly used with the limit keyword to return a desired range of results for pagination. Don’t forget to use sort the results to ensure more deterministic and predictable results.

The above example sorts the full-name attributes of all person entities in ascending order, skips the first six results, and returns up to the next ten.

Use the limit keyword followed by a positive integer to limit the number of results (answers) returned.

We recommend using the limit with the sorting aggregation to get more deterministic and predictable results.

To fetch an attribute, use the following query:

The above query matches files with their path attributes and then fetches the path attribute.

You can fetch a value of a value variable or a type from a schema of a database:

The above query matches any instance of data ($x) that has name of iopvu.java and any size-kb ($s). The variable $type is assigned to be equal to the type of $x. Finally, we bound the value variable ?size to some value, based on the value of the $s.

Note, that the size has no type because it is a value from a value variable and the type has no value because it is a type of a concept.

To fetch all attributes, owned by any type, we can fetch a variable with a colon followed by the attribute root type:

The above query matches all files (even those that do not have any attributes) and then fetches all attributes for every file.

The above query is equal to the previous one, but it uses relabeling to customize keys of the JSON objects.

Note that instead of f we have file key and instead of attribute — all-attributes.

You can use Get queries as subqueries as long as you use aggregation to get a value.

In the above query, we use Get query with count aggregation to get the number of emails with "kevin" substring owned for every user. Hence, the value in "try-subquery" key has no type.

We can use Fetch query to infer new facts. For example, we can use the add-view-permission rule from the IAM schema to infer view_file action access permissions.

Using the IAM sample data the above query shows any results only if inference is enabled.

Try the same query with disabled inference to see no matched results.

Let’s try a bigger example with a little bit of everything:

The above query matches all users and all objects, that those users can access with view_file action. Then it fetches full-name and email attributes for users, all attributes for objects and name attributes for action. Finally, for every matched result it runs a subquery to convert size-kb to size-mb.

The result is a stream/iterator of JSON objects. See an example of such JSON object below.

Note how we do not match any attributes, except for name for action in the match clause. If we do match instances of a type with has <attribute-type> statement that excludes all instances that do not own any of such attribute type.

For example: $u isa user, has full-name $fn; would exclude all users that do not have any full-name. At the same time, mathing $u usa user; and then fetching $u: full-name; will return even those users that do not own any full-name attributes. The corresponding value would contain an empty list of values in this case.