Request Language

Request language

The request language is based upon JSON format. Any request or sub-request is an object. The object fields are either object properties to request or a combination operator (and, or).
A property type field is used to compare the property with the value and is also an object. This object must have only one field (with some exceptions). The field name is corresponding to a comparison operator and its value to the value to be compared with.

Some operators can manage

• void values. In this case the value will be ignored.

  Example:

  { "type": { "empty": null } }

• One value.

  Example:

  { "type": { "eq": 1 } }

• Several values. Then, the field value will be a value table.

  Example:

  { "type": { "in": [1,3,4] } }

  Except for specific cases (cf. hereafter), the comparison between several values is a logical OR:

  is equivalent to

  For negative operators, the comparison between several values is a logical and (not or):

  is equivalent to

Logical operators

• OR

• AND

• NOT 11.21

A combination type operator field type is a table with sub requests, hence an object. Then if an object property bears the same name as a logical operator, you just need to indicate an object as the field value instead of a table.

For NOT operator, the table expression items are combined with the operator OR.

is equivalent to

If the table is doubled, expression items are combined with the operator AND.

is equivalent to

The root object request creates a mandatory ‘and’ between all sub-queries.

is equivalent to

It is also possible to combine several comparisons on a single field in one clause and

11.15.1

is equivalent to

Operators

Operators are not case sensitive. All operators are available in short or long version.

Operators can use any type. The type value is adapted depending on the context.
E.g. all following expressions are equivalent:

11.21 If the operator equals is used with value null, the operator used is empty. If the operator notequals is used with value null, the operator used is notempty.

Type: text, sentence, word, html

Type: number (integer or real)

Type: boolean

Type: timestamp (dates)

The value is automatically converted to the appropriate type according to the type of the compared field (date or datetime). The dates comparison values could be set in JavaScript timestamp (as long) or using simple ISO strings.

Value and format

The dates comparison values could be set in JavaScript timestamp (as long) or using simple ISO strings.

Functions

• Function now allows to compare to now or relative dates. Specify the difference in days between brackets (negative numbers for earlier dates and positive numbers for later dates):

  • now or now(0): means today

  • now(-1): means yesterday

  • now(1) or now(+1): means tomorrow

• Function today allows you compare to today or relative dates. The difference with function now is that for today the generated date is always of type date, while for now the type is date or datetime depending on the type of the property being compared.

• Function ts allows to compare to a timestamp within a string context (like request parameter)

  11.19

  For example: ts(1552405738000).

  The value is automatically converted to the appropriate type according to the type of the compared field (date or datetime).

Type: path (resource)

Path for resources can use slash (/) or backslash (\) indifferently.

Type: object

The test value shall be an object identifier or void for empty or not empty.

Type: array

Type: identity

Type: uuid

It is possible to make queries on the uuid, even though it is not a field per se of an instance. Simply specify $uuid in the property name.

Subqueries

11.12

For types object and array, it is possible to use subquery instead of id. (before 11.25, the subquery must return none or one object).

For example, to look for object with product having code equal to "CD001" :

For multiple object field, use contains operator.

For example, to look for objects with product having ean equal to "3276000338345" :

Subquery operators

Its possible to select the resultset of a subquery with one of these operators:

• $allOf: values in no particular order and no limit of number of values. An error may be raised if the maximum limit of values is not allowed to be exceeded (see tag rest_api_subquery_nolimit)

• $maxOf: values in no particular order

• $oneOf: select a single value. If there is more than one, raise an error

• $anyOf: select a single value, any value.

• $firstOf: returns a single value, the first one created

• $lastOf: returns a single value, the last one created

• $newerOf: returns a single value, the one last modified

• $olderOf: returns a single value, the oldest modified one

For example

Query workflows

11.27

You can directly query a workflow.

For example :

Overlap operator

11.19

It is easy to test range overlap with the overlap operator (or in short version, ovrl). This operator works for date or number ranges.

The syntax is

rangestartproperty and rangeendproperty are respectively the names of the properties that store the lower and higher edges of the range. rangestartvalue and rangeendvalue are respectively the values of the lower and higher edges of the range to compare to the stored range.

The operators can be stricly greater or lower to exclude edges or not to include edges (use gte instead of gt, and lte instead of lt).

Null or empty values are excluded automatically.

Example for a date range:

Similar images

11.21.2

The similarimage operator (or sim in its short version) is used to search for assets that have a similar image (hash comparison algorithm).

Example (searches for assets whose image is similar to the images of assets 1 or 2) :

Example (searches for assets whose image is similar to the images of legacy assets 1 or 2) :

Non static values

Variables

11.12

In some contexts, it is possible to have parts configurable by variables. The variables and their reference depends on the context (see the documentation of the concerned endpoint for more details). Only the value part can be set (neither the operator nor the field name can be set).

The common syntax is ${<variable identifier>}. There is always a default context and other contexts. Usually, the identifier for a variable of the common context is its name. For variables in a context other than the default one, use a prefix of the type <context identifier>:.

For example, ${name} is the value of the property name. For example, ${par:actionname} is the request parameter actionname.

Surfer property

11.18

In all authenticated context, it is possible to refer to surfer property values. Use the variable syntax pattern with the prefix surfer. For example, ${surfer.id} refer to the surfer id. To get a custom property, use ${surfer.props.<name of properties>}.

Example :

with

will be resolved towards

Properties currently available:

Errors codes

Query policies

11.18

It is a set of rules to allow or prohibit the use of fields in a query, in the form of json. This json can be an array of rules, or a single rule.

As soon as a policy is defined and if there are no rules, all fields are excluded by default. If at least one rule is specified, all the field are allowed until an excluding rule match the field. The rules are tested in the order of definition. If a field matches a excluding rule, then the field is prohibited. If a field matches at least one including rule, and it does’nt match any excluding rule, then the field is allowed to be used in a query. A field that does not match any rules is excluded. Any error make all the fields prohibited.

The general form of a rule is:

• type: the type of the rule

• value: (optional) a parameter value for the rule

• exclude: true to exclude field if it matches the rule (default is false).

types

• all

  All fields match the rule.

  1. Attribute:

     • type: all

     • exclude: true or false

  2. Example:

• exported

  All fields the end point configuration exports match the rule

  1. Attributes:

     • type: exported

     • exclude: true or false

  2. Example:

• name

  The rule selects the fields whose name corresponds to the value of the value attribute

  1. Attributes:

     • type: exported

     • value: the name of the field to select

     • exclude: true or false

  2. Example:

• type

  The rule matching is done using the type of the field

  1. Attributes:

     • type: type

     • value: a type selector

     • exclude: true or false

  2. Types

     • boolean: child to nature activated

     • date: any date (types date or dater)

     • datetime: datetime

     • string: string (types data or sentence)

     • binary: types file or image

     • child: type child

     • id: any single id (types identifier or child)

     • collection: type collection

     • number: any number (types integer, decimal or money)

     • relational: any relational type (child, childmulti…​)

     • prelational: any relational type (child, childmulti…​) except boolean

     • plaintext: any plain text (types data, sentence or text)

     • anytext: any text (types data, sentence, text or html)

     • status: a workflow field

     • anytree: a general tree field (tag arbo_field or thesaurus/broaderterm)

     • tree: a tree field (tag arbo_field)

     • thesaurus: a thesaurus field

     • listable: a field configured to be in datalist

     • viewable: a field configured to be in dataview

     • indexed: an indexed field

     • editable: an editable field (to be editable in dataedit)

     • mandatory: a mandatory field

     • groupable: a groupable field

     • i18nfor: a field that is a translation

     • i18n: a field that has translations

     • attachment: a binary or image field that is attachment

     • identifier: id field

     • identity: a field with the type identity

     • data or word: a field with the type data

     • sentence: a field with the type sentence

     • integer: a field with the type integer

     • decimal: a field with the type decimal

     • money : a field with type money

     • html: a field with the type html

     • file: a field with the type file

     • image: a field with the type image

     • text: a field with the type text

  3. Example:

• tag

  The rule selects the fields with the specified tag

  1. Attributes:

     • type: exported

     • value: the tag

     • exclude: true or false

  2. Example:

• nature

  The rule selects the fields with the specified nature (implies, necessarily, a relational field).

  1. Attributes:

     • type: exported

     • value: the nature

     • exclude: true or false

  2. Example:

• naturetag

  The rule selects the fields with a nature that has the specified tag (implies, necessarily, a relational field).

  1. Attributes:

     • type: exported

     • value: the tag of nature

     • exclude: true or false

  2. Example:

• lang

  The rule selects the fields with the specified language (implies, necessarily, a translation field).

  1. Attributes:

     • type: exported

     • value: the code of the language (ISO 639-1)

     • exclude: true or false

  2. Example:

• i18nfor

  The rule selects the fields that are a translation for the specified field

  1. Attributes:

     • type: exported

     • value: name of translated field

     • exclude: true or false

  2. Example:

• and

  Combine several rules with the and operator (all rules must match)

  1. Attributes:

     • type: and

     • value: a rule array

     • exclude: true or false

  2. Example:

• or

  Combine several rules with the or operator (one rule has to match)

  1. Attributes:

     • type: and

     • value: a rule array

     • exclude: true or false

  2. Example:

• not

  Negate the matching function of a rule.

  1. Attributes:

     • type: not

     • value: a rule

     • exclude: true or false

  2. Example:

examples

Not any rules: all fields prohibited

One rule "exported": only the exported fields allowed