One important aspect of the Jade APIs is the ability to query the platform for objects. Flexiant Query Language (FQL) allows a user with administrative privileges to query the platform in a flexible and extensible manner. FQL uses two key object types to achieve this: the
searchFilter and the
queryLimit. These are passed as parameters to all calls starting with the word 'list' (for instance,
Using searchFilter objects
searchFilter specifies search criteria that are applied when performing the query. Objects not matching the
searchFilter will be ignored. Objects matching the
searchFilter will be returned, subject to falling within the applied
searchFilter consists of zero or more
filterConditions, and the object concerned must match each
filterCondition in order to match the
searchFilter itself. In other words, all
filterConditions must be met for the object concerned to match.
For example, if the
listCustomers call is used, then
customerDetails objects are searched. Only those objects that meet the criteria supplied in the
searchFilter supplied will be returned. The
customerDetails object contains a status field and a
billingEntUUID field. By setting
filterConditions for each of these, it is possible to search on both status and billing entity UUID simultaneously.
Note, that each
filterCondition object must refer to a different field; it is not possible to have two
filterConditions which refer to the same field. In order to search records where one field falls between a range, use a single filterCondition with the
BETWEEN condition selected. There is no restriction on having multiple
filterConditions provided each refers to a distinct field. Only records that match all the filter conditions supplied are returned by the relevant list call.
filterCondition represents a criterion against which a given record searched by the
searchFilter in a 'list' call is matched. The complex type consists of three parts: the
condition, and the value.
field identifies the name of the field within the complex type to be searched; this is a case-insensitive version of the member name, as set out in this document. However, it is possible, by the using FQL dot notation (see below) to query fields outside of the complex type concerned.
condition is an enum value, of type condition, which specifies how the match takes place, for instance
STARTS_WITH. The full list of available conditions are described under the simple type
The value specifies the value the field is to be matched against. Where a
BETWEEN condition is specified, the value should be a two element array specifying the lower and upper bounds of acceptable values.
FQL Dot notation
FQL dot notation can be used to specify queries against fields outside the object itself. For instance, if listResources is used with a resourceType of 'SERVER', then the field disks.size could be used to query all servers with disks of a given size.
The full list of available fields to query depends upon the objects being searched. A full list is available under FQL Dot Notation Reference.
Subscripts can be used where keys are multivalued. For instance, let us suppose you wish to match servers with the key
state equal to
Virginia, and the key
Type equal to
Large, when calling
listServers. The following code would be problematic:
The above will not work, because the system has no way of knowing which key is to matched to which value. This problem can be eliminated by using subscripts, as follows:
Note that the keys do not need to be applied in the order above (indeed keys do not have ordering). The subscripts are merely labels that tie together conditions referring to the same multivalued elements.