Overview

The Alloy Query Syntax (AQS) is a JSON tree based syntax that allows you to query the items stored in Alloy by applying various types of conditions. Conditions can be specified also on connected items making the AQS able to define fairly complex queries to get very specific items. All areas of Alloy that require querying the data will use AQS under the hood and therefore provides a universal way to access data from the system.

Query examples

The following topics contain a list of commented examples to illustrate the main AQS features. All examples follow the structure accepted by the search AQS web API. In fact, they are all a JSON object that contains a single property named aqsNode. The actual AQS is the value of the aqsNode property. Since the query will depend on the modules installed and the data held in the system, the following examples have been written to demonstrate the syntax for each node type and not necessarily usable directly through the web API. More complex queries can be constructed by nesting nodes in a tree like structure.

Base structure

As previously introduced, the AQS is a tree based structure that uses JSON as its language. Each node follows the following structure:

Property Name Type Required Description
type string true The node type, this determines which properties are available as well as whether it contains children.
properties object false An object whose properties are defined by its type
children Node [] false An array of child nodes, order is important. This is only valid for nodes that allow children.

The following is an example of the above definition. A query will always include a root node. A root node can have up to 1 child. The number of children for a node are dependent on the node type.

{
  "type": "Query", // This can be any valid root node type
  "properties": { ... },
  "children": [
      {
        "type": "...", // This can be any supported child node.
        "properties": { ... },
        "children": [ ... ], // if the child node suppports children.
      }
   ]
}

Designs and Design Interfaces

From the data querying point of view, the objects and their structure currently in place in the database can be modelled through 2 types:

designs

The code for a designs code is a string containing its key property name and value separated by an underscore (e.g. design_streetLights).

designInterface

The code for a designInterface is the name itself (e.g. designInterface_jobWorkItems).

A query with no conditions will return all items from a given design, or if an interface is specified, then all the items from all designs that implement the interface are returned.

If conditions are present in a query, these will filter those items using attributes present in the root design (or interface), or by other attributes that belong to linked designs or linked interface via an AQS Path if specified.

Root nodes

The operation that the AQS is going to execute is defined by its root node. The root node also contains the properties necessary to carry out the requested operation. Properties can greatly differ from one root node type to the other, in the same they differ from one AQS node type to the other.

The children that a root node can take are the same across all the root nodes.

There are four types of root node:

Note

The root node can only have one child node.

All root nodes support the children field so they all accept an aqs query. The purpose of this is for root nodes to describe the operation to execute and for the underlying query to tell the items on which such an operation has to be executed.