Resource Query Language

Resource Query Language (RQL) is a query language designed for use in URIs with object-style data structures.

Introduction

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:

• Resource Query Language at the GitHub site.
• RFC-3986: Uniform Resource Identifier (URI): Generic Syntax .

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
!	21	Exclamation mark
#	23	Pound or hash
%	25	Percent
&	26	Ampersand
'	27	Quotation mark
(	28	Opening parenthesis
)	29	Closing parenthesis
,	2C	Comma
=	2D	Equal sign
;	3B	Semicolon
[	5B	Opening square bracket
]	5D	Closing square bracket

Note

* and ? are not reserved, but they have special meaning in the like() function.

The following are examples of RQL implementations:

• Resource filtering
• Getting list of linked resources
• Declaration of UI navigation trees.

Query Components

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

• Functions
• Logical operators
• Relational 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. The second parameter is optional, by default the <number> is 1000 elements.	limit(0,2) returns the two elements in positions 0 and 1. limit(10) returns up to 1000 elements starting from position 10.
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. It works only against /types endpoint (refer to Type API).	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 (for example, fullName) of linked resources (for example, user relation name), use the <relation name>.<property> input argument, for example, 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, for example, 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.

3. The pattern argument in the like() function is case-insensitive.
4. The first argument in the in() and out() functions cannot be an array.

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

• Join that 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.

6. If the limit function is not specified, the APS controller returns up to 1000 entries. It is equivalent to limit(0,1000).

Warning

1. If the APS controller cannot find a specified property, its response will be as follows:

{
   "error": "APS::Util::Exception",
   "message": "Property `hardware.memory` is not found."
}

2. The total number of requested objects specified in the limit function must not exceed 65535.

Logical Operators

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

OPERATOR	Alias	Examples	Meaning
and (<query>,<query>,…)	& ,	- and(implementing(http://aps-standard.org/samples/user-mgmt/offer),like(name,*L*)) - implementing(http://aps-standard.org/samples/user-mgmt/offer)&like(name,*L*) - implementing(http://aps-standard.org/samples/user-mgmt/offer),like(name,*L*)	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, for example, 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	Aliases	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.

Mind the following specifics of different JSON types:

• String types are compared as follows:

  • Version strings are compared as described in the Version Strings Comparison section.
  • All other strings are compared following the lexicographical order .

• Relational operation applied to an array will search for the required relation through all items in the array. If at least one item meets the relation, it means the array as a whole meets the relation.

  In the following example, we need to get all resources implementing the specified type that in addition have the specified property urls =eq= http://brand.a.vova.apsdemo.org:

  GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/website/1.0),eq(urls,http://brand.a.vova.apsdemo.org)
  

  In its response, the APS controller returns a resource that meets the requirement:

  [{
        "aps": {
                "id": "2f71f9c0-f7ce-4626-bdc2-256b781111d0",
                "modified": "2014-12-09T06:59:01Z",
                "revision": 2,
                "status": "aps:ready",
                "type": "http://parallels.com/aps/types/pa/website/1.0"
        },
        "path": "/var/www/vhosts/1/100000/webspace/httpdocs/brand.a.vova.apsdemo.org",
        "urls": [
                "http://brand.a.vova.apsdemo.org",
                "https://brand.a.vova.apsdemo.org"
        ],
        "websiteId": 2
  }]
  

Values

Value Types

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

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()

Applicable Operators and Value Functions

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())

Specifics of Reverse Match

Reverse match search is based on the ne and not operators. It allows you to return all objects where the specified property does not match the specified pattern. However, it does not return objects where the specified property is not defined, that is equals null. If your reverse match search must also return the objects where the specified property is null, you should combine the ne or not operator with the null() value function. For example, the following combination returns all objects where the name is not “v106” including the objects where the name property is not specified:

GET /aps/2/resources?implementing(<type ID>),or(ne(name,v106),eq(name,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.

← HTTP Responses

User Interface →