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, listUnitTransactions).
Using searchFilter objects
A 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 QueryLimit.
A 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.
Each 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 field, the condition, and the value.
The 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.
The condition is an enum value, of type condition, which specifies how the match takes place, for instance IS_EQUAL_TO, or STARTS_WITH. The full list of available conditions are described under the simple type condition.
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.
FQL Subscripts
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:
resourcekey.name IS_EQUAL_TO "State" resourcekey.value IS_EQUAL_TO "Virginia" resourcekey.name IS_EQUAL_TO "Type" resourcekey.value IS_EQUAL_TO "Large"
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:
resourcekey.name[0] IS_EQUAL_TO "State" resourcekey.value[0] IS_EQUAL_TO "Virginia" resourcekey.name[1] IS_EQUAL_TO "Type" resourcekey.value[1] IS_EQUAL_TO "Large"
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.