Previous topic

Security Model

Next topic

Internationalization and Localization

DOCUMENTATION
Last updated 28-Jun-2016

Resource Query Language

Introduction

Resource Query Language (RQL) is a query language designed for use in URIs with object-style data structures. Using RQL, applications can request the APS controller to select and return a list of APS objects and/or their attributes.

RQL grammar used in this document is based on the following rules:

APS uses a subset of the RQL operators and adds some APS-specific functions. In particular, there are reserved characters that must be percent-encoded (%HH) when used in RQL expressions. The reserved characters include characters that may be used as delimiters. In addition some other characters such as the space character should also be percent-encoded. So, for example, expression prop1=eq=value with space is incorrect and the correct one will be prop1=eq=value%20with%20space.

At present, APS uses the following set of reserved characters.

SYMBOL ASCII Hex Code Name
  20 Space
& 26 Ampersand
( 28 Opening parenthesis
) 29 Closing parenthesis
* 2A Asterisk
, 2C Comma
= 2D Equal sign
/ 2F Slash
; 3B Semicolon
? 3F Question mark
@ 40 At symbol
| 7C Vertical bar

The following are examples of RQL implementations:

Query Components

RQL statement contains one or several query functions joined by operators:

RQL functions can operate values of certain types.

Functions

FUNCTION Description Examples
in (<property>,<array-of-values>) Select objects where the specified property value is in the provided array in(name,(Silver,Gold))
out (<property>,<array-of-values>) Select objects where the specified property value is not in the provided array out(name,(Platinum,Gold))
limit (<start>,<number>) Return the given number of objects from the start position limit(0,2)
sort (<list of properties with + or - prefix>) Sort a list of objects by the given properties (unlimited number of properties). The list is sorted first by the first specified property, then by the second, and so on. The sort order is specified by the prefix: + - ascending order, - - descending. sort(+hardware.memory,-hardware.diskspace)
implementing (<base-type>) Return the list of objects (resources and types) implementing the base type and including the base type itself implementing(http://aps-standard.org/samples/user-mgmt/offer/1.0)
composing (<derived-type>) Return the list of types that are implemented by the derived type, including the derived type itself composing(http://aps-standard.org/samples/user-mgmt/offer/1.0)
like (<property>, <pattern>) Search for the specified pattern in the specified property. The function is similar to the SQL LIKE operator, though it uses the * wildcard instead of %. To specify in a pattern the * symbol itself, it must be percent-encoded, that is, you need to specify %2A instead of *, see the usage examples below. In addition, it is possible to use the ? wildcard in the pattern to specify that any symbol will be valid in this position.
like(firstName,Jo*)
like(firstName,*ohn)
like(firstName,*oh*)
like(firstName,Joh?)
select (<list of attributes>) The function is applicable to a list of resources (hereafter base resources). It receives the list of attributes (up to 100 attributes) that can be primitive properties of the base resources, relation names, and relation names combined with properties of related resources. The output is the list of objects presenting the selected properties and related (linked) resources. Normally, when relations are selected, the base resource properties are also presented in the output. For example, the {aps} structure will always show up. To get a property (e.g., fullName) of linked resources (e.g., user relation name), use the <relation name>.<property> input argument, e.g. user.fullName.
select(name,hardware.memory,user)
select(name,hardware.memory,user.fullName)
linkedWith (<resource ID>) Return the list of resources linked with the resource whose ID is specified as the argument. The APS controller searches for all resource links including internal system links. For example, an admin/owner/referrer actor that has access to the resource is also considered as a “linked” resource.
linkedWith(220aa29a-4ff4-460b-963d-f4a3ba093a0a)

implementing(http://aps-standard.org/types/core/user/service/1.0), linkedWith(220aa29a-4ff4-460b-963d-f4a3ba093a0a)

Note

1. If an APS type is used as an argument in a function, e.g. in implementing() or composing(), and its version is omitted, then version 1.0 is implied. See also version compatibility.

2. Functions limit, sort, implementing, and composing cannot be used in definition of the visible attribute in UI navigation.

  1. The pattern argument in the like() function is case-insensitive.

4. When using a function with an object property as an argument (in, out, sort, and like) make sure every object in the queried list has the specified property. For example, every resource has the aps.ready property, but not all resources have the hardware.memory property. Use the following ways to prepare the list of objects that all have the required property:

  • Join the function with another function returning such a list (implementing or composing) by means of the logical operator and.
  • Apply the function to the collection of resources linked with a selected resource by a certain relation.

Warning

  1. In Odin Service Automation, the select function is supported since version 6.0.
  2. If the APS controller cannot find the specified property, its response will be as follows:
{
   "error": "APS::Util::Exception",
   "message": "Property `hardware.memory` is not found."
}

Logical Operators

Logical operators join two or more query functions using the boolean logic.

OPERATOR Alias Examples Meaning
and (<query>,<query>,...)
&
,
Select all offers whose name matches the case-insensitive *L* pattern
or (<query>,<query>,...)
|
;
implementing(http://aps-standard.org/samples/user-mgmt/offer/1.0)&or(like(description,*free*),in(name,(Silver,Gold))) Select all offers whose description matches the *free* pattern as well as those whose name is either Silver or Gold.
not (<query>)   implementing(http://aps-standard.org/samples/user-mgmt/offer),not(like(name,*free*)) Select all offers except for those whose name matches the *free* pattern.

Note

1. The and operator is the implicit top level RQL operator. For example, statement http://hosting.com?and(arg1,arg2,arg3) is equivalent to http://hosting.com?arg1,arg2,arg3.

2. The and operator is prioritized higher than or. That is why, when using aliases, enclose the joined queries in parenthesis to set the needed processing order, e.g. implementing(<type>),(prop1=eq=1|prop2=ge=2).

Relational Operators

A relational operator is used to filter objects by comparing one of their properties against a specified value.

OPERATOR Alias Examples Meaning
eq (<property>,<value>) =eq=
- eq(aps.status,aps:ready)
- aps.status=eq=aps:ready
Select all objects whose aps.status is aps:ready.
ne (<property>,<value>) =ne=
- ne(aps.status,aps:ready)
- aps.status=ne=aps:ready
Select all objects whose aps.status is not aps:ready.
gt (<property>,<value>) =gt= implementing(http://aps-standard.org/samples/user-mgmt/offer),hardware.memory=gt=1024 Select all offers that provide hardware.memory higher than 1024.
ge (<property>,<value>) =ge= implementing(http://aps-standard.org/samples/user-mgmt/offer),hardware.memory=ge=1024 Select all offers that provide hardware.memory equal or higher than 1024.
lt (<property>,<value>) =lt= implementing(http://aps-standard.org/samples/user-mgmt/offer),hardware.CPU.number=lt=16 Select all offers that provide hardware.CPU.number less than 16.
le (<property>,<value>) =le= implementing(http://aps-standard.org/samples/user-mgmt/offer),hardware.CPU.number=le=16 Select all offers that provide hardware.CPU.number equal or less than 16.

String types are compared as follows:

Values

Values in query functions and relational operators can be:

  • Strings (using URL encoding)
  • Numbers
  • Dates (in ISO UTC format without colon encoding)
  • Booleans
  • Value functions

Value functions are functions that return special values like null, true, false, or empty string. Each of them is applicable to certain data types.

VALUE FUNCTION Applicable types Description Example
null() Any type Define if the value is null name=eq=null()
true()
false()
Boolean Define if the value is true or false disabled=eq=false()
empty() Strings Define if the string is empty (not null, but doesn’t contain any symbols) addressPostal.extendedAddress=eq=empty()

The following table summarizes the value types as well as applicable operators and value functions.

VALUE TYPE Operators Value functions Examples
string eq,ne,lt,le,gt,ge null(),empty()
apphost=eq=empty()
eq(apphost,empty())
number eq,ne,lt,le,gt,ge null()
aps.revision=ge=4
ge(aps.revision,4)
date eq,ne,lt,le,gt,ge null()
aps.modified=ge=2014-07-14T11:14:24Z
ge(aps.modified,2014-07-14T11:14:24Z)
boolean eq,ne
true()
false()
null()
addressPostal.postOfficeBox=eq=null()
eq(addressPostal.postOfficeBox,null())

Examples

Requirements in Type Relations

When setting a type relation in a type definition, RQL statement is used to specify requirements to related resources.

{
     "relations": {
         "environment": {
             "type": "http://www.aps-standard.org/core/resource/1.0",
             "link": "strong",
             "requirement":
                 "in(php,engines) & in(xslt, php.extensions) &
                 php.version > 4.1.0 & php.version < 5.0 &
                 (os.Type = Linux | os.type = FeeBSD) &
                 disk.space >= 20000 & memory >= 40960",
             "defaults": {
                 "php.safe_mode": "yes"
             }
         }
     }
}

Note

RQL supports white spaces in expressions within the requirements definition. In addition, it supports there the usage of the following relational operator aliases: >, <, >=, and <=.

REST Queries

Return the list of types inherited by the specified type, including the type itself:

GET /aps/2/types/?composing(http://aps-standard.org/samples/user-mgmt/cloud)

Return the first 100 resources, without ordering:

GET /aps/2/resources?limit(0,100)

Order VPSes first by memory, then by disk space, and return the first 10 resources:

GET /aps/2/resources/?implementing(http://aps-standard.org/samples/user-mgmt/vps),sort(+hardware.memory,+hardware.diskspace),limit(0,10)

Note

‘,’ delimiter without an explicit predicate is possible because the implicit top level RQL operator is ‘and’.

Get a list of service users linked with VPSes:

GET /aps/2/resources/?implementing(http://aps-standard.org/samples/user-mgmt/vps),select(user)

Get full names of service users linked with VPSes:

GET /aps/2/resources/?implementing(http://aps-standard.org/samples/user-mgmt/vps),select(user.fullName)

Update Match Statements

In APP-META.xml, a package developer should specify the set of previous package versions that this package can update. For example, to match all package versions starting with 1.0.0, use:

<upgrade match="version =ge= 1, release=ge=0"/>

As demonstrated above, you may add space around operators if needed.