Resource Query Language¶

Resource Query Language (RQL) is a query language designed for use in URLs to request object-style data structures. In the platform, the requested objects are called APS resources, from which the name of the query language was derived.

In this document:

Introduction
Functions
Logical Operators
Relational Operators
Values
Examples

Introduction ¶

Using RQL, APS bus actors can request the APS controller to select and return a list of APS resources and their properties.

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 .

Reserved Characters¶

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 also include characters that may be used as delimiters. In addition, some other characters such as the space character must also be percent-encoded. For example, the 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.

Implementations¶

The following are examples of RQL implementations:

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

Language Components¶

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

Functions
Logical operators
Relational operators

Functions ¶

RQL functions can operate values of certain types.

List of Functions¶

FUNCTION	Description	Examples
`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 with the /types endpoint (refer to Type API).	composing(http://aps-standard.org/samples/user-mgmt/offer/1.0)
`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 required resources from the start position limited up to the specified number of the resources.	`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).	sort(+hardware.memory,-hardware.diskspace)
like (<property>, <pattern>)	Search for the specified pattern in the specified property.	like(firstName,oh) like(firstName,Joh?)
select (<list of attributes>)	The function specifies the properties and related resources to be returned by the APS controller.	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.	linkedWith(220aa29a-4ff4-460b-963d-f4a3ba093a0a)
contains (<array>,<expression>)	Indicate if the content of the input array matches the input expression.	contains(attributes,and(eq(attributeID,CreatedBy),eq(value,ERPsystem)))

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 implementing, composing, limit, sort, and contains cannot be used in definition of the visible attribute in UI navigation.

The first argument in the in() and out() functions cannot be an array.

4. 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.

Warning

If the APS controller cannot find a specified property, its response will be as in the following example:

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

`limit`¶

The function selects the resources by their position in the list selected by the other functions.

Syntax: limit(position,limit)

The first input number specifies the position of the first resource to be returned.
The second input number is optional and it specifies the maximum number of returned resources. By default, it is 1000.

For example:

limit(0,2) returns the two resources in positions 0 and 1.
limit(10) returns up to 1000 resources starting from position 10.
limit(0,0) returns an empty list, but the Content-Range header in the response will still contain the total number of resources, which is the purpose of such a request.

Note

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

`sort`¶

The function sorts a list of resources by one or more properties with an unlimited number of those properties.

Syntax: sort((+|-<property1>,+|-<property2>,...)

It sorts the list by the first property, then by the second, and so on. Use the + (default value) or - sign as a prefix to require respectively ascending or descending sorting, for example:

sort(+hardware.memory,-hardware.diskspace)

`like`¶

The function selects the resources where the specified property matches the specified pattern.

Syntax: like(<property>,<pattern>)

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 *. In addition, it is possible to use the ? wildcard in the pattern to specify that any symbol will be valid in this position. The following example illustrates the use of both wildcards:

like(firstName,Jo*)
like(firstName,*ohn)
like(firstName,*oh*)
like(firstName,Joh?)

Note

The pattern argument in the like() function is not case-sensitive.

`select`¶

The function specifies a list of properties and linked resources to be included in the response.

Syntax: select(<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 the related resources.

The output is a list of resources with the selected properties and related (linked) resources. Normally, when relations are selected, the base resource properties are also present in the output. As an exclusive case, 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`¶

The function returns a list of resources linked with the resource whose APS ID is specified as the input argument.

Syntax: linkedWith(<resource_APS_ID>)

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. For example:

linkedWith(220aa29a-4ff4-460b-963d-f4a3ba093a0a)

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

`contains`¶

The function selects resources by the content of an array specified as the first input argument.

Syntax: contains(<array>,<expression>)

The function verifies if the content of the input array complies with the input expression. Typically, it is used to select all resources by an attribute.

The platform allows the assignment of a set of custom attributes to a kind of resources, for example, to accounts. Every custom attribute is a pair of attributeID and value. For example, a BSS-Account-Info resource contains the following list of attributes:

"attributes": [
   {
      "attributeID": "CreatedBy",
      "value": "ERPsystem"
   },
   {
      "attributeID": "ClientType",
      "value": "VIP"
   }
]

The following example selects those resources whose “createdBy” attribute is “ERPsystem”:

contains(attributes,and(eq(attributeID,CreatedBy),eq(value,ERPsystem)))

Note

In the input expression, the function allows only one attribute to be analyzed.

Logical Operators ¶

Logical operators join two or more query functions and 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 to 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.

Keep in mind the following specifics of different JSON types:

String types are compared as follows:
- Version strings are compared as described in the Version String Comparison section.
- All other strings are compared following the lexicographical order .

A 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, 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, an 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

Within relation requirement expressions, RQL supports white spaces and 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

The ‘,’ 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 must 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 →

CloudBlue Commerce API

Previous topic

Next topic

Resource Query Language¶

Introduction ¶

Reserved Characters¶

Implementations¶

Language Components¶

Functions ¶

List of Functions¶

`limit`¶

`sort`¶

`like`¶

`select`¶

`linkedWith`¶

`contains`¶

Logical Operators ¶

Relational Operators ¶

Values ¶

Value Types¶

Value Functions¶

Applicable Operators and Value Functions¶

Specifics of Reverse Match¶

Examples ¶

Requirements in Type Relations¶

REST Queries¶

Update Match Statements¶

CloudBlue Commerce API

Previous topic

Next topic

Resource Query Language¶

Introduction¶

Reserved Characters¶

Implementations¶

Language Components¶

Functions¶

List of Functions¶

limit¶

sort¶

like¶

select¶

linkedWith¶

contains¶

Logical Operators¶

Relational Operators¶

Values¶

Value Types¶

Value Functions¶

Applicable Operators and Value Functions¶

Specifics of Reverse Match¶

Examples¶

Requirements in Type Relations¶

REST Queries¶

Update Match Statements¶

Introduction ¶

Functions ¶

`limit`¶

`sort`¶

`like`¶

`select`¶

`linkedWith`¶

`contains`¶

Logical Operators ¶

Relational Operators ¶

Values ¶

Examples ¶