RSQL

Syntax

RSQL is a query language for RESTful APIs. It uses an URI-friendly syntax, there
are no unsafe characters, so URL encoding is not required. It supports some
logical and comparison operators and can be easily extended by custom operators.

You find more detailed information on RSQL at
https://github.com/jirutka/rsql-parser.

Available Operators

Data Client Library supports all standard RSQL operators as there are:

Data Client Library supports standard or and and RSQL operators depending on
layer type (see below):

Additionally, Data Client Library supports the following custom operators:

Note: You can use uppercase custom operators but the RSQL guide suggests
to lowercase operators.

Supported Operators per Layer Type

Data Client Library uses RSQL to query or select specific data. As the data
which is stored in different layer types has a different structure it supports
different operators per layer type.

The following chapters show all available operators and attributes per layer
type. For ease of view the alternatives are not listed here though they are
supported.

Index Layer

Supported Operators:

• all standard operators
• and and or operators
• =inboundingbox=
• =incircle=
• =inpolygon=

Supported Attributes:

• tileId
• timestamp
• timewindow

Note:

• If you use the timeStamp attribute or a field of timewindow type the time
  is in UTC milliseconds since epoch (Jan 1, 1970 00:00:00 AM UTC). If you run
  your application in another timezone, make sure that the timestamp is
  converted into UTC before you query or upload data. In Java or Scala you can
  do the conversion by using this function call:
  Calendar.getInstance(TimeZone.getTimeZone("UTC")).getTimeInMillis()

Limitations:

• The maximum number of tiles returned by a spatial query cannot exceed 2000.
• For optimal query performance, use the timewindow indexing attribute.
• The timestamp and timewindow indexing attributes cannot be used in the
  same query.
  Note: The timewindow attribute cannot be used directly in a
  query as it consists of a name and a duration, for example, the name could be
  ingestionTime and the duration 60 (minutes). In this case the query would
  use ingestionTime.

Examples:

• tileId==91717
• tileId=in=(91717,91718) (returns these two partitions)
• tileId=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) (returns all
  partitions of Munich for zoom level as defined in layer config)
• tileId=in=(FOO,BAR) (returns two partitions from a layer which does not use
  HERE tiling schema but generic tiling schema and has partitions named FOO
  and BAR)
• timestamp==1552383031000 (milliseconds since epoch; March 12, 2019 09:30:31
  AM GMT)
• ingestionTime>1552382100000;ingestionTime<1552385700000 (greater than March
  12, 2019 9:15:00 AM and less than March 12, 2019 10:15:00 AM)

For more details on queries for index layer data, see
Get Data from an Index Layer
section of the Data API Developer Guide.

Versioned Layer

Supported Attributes:

• mt_partition
• mt_version

Supported Operators per Attribute:

• mt_partition
  • ==
  • =in=
  • =inboundingbox=
• mt_version
  • ==
  • =changes=
• and operator

Limitations:

• Attributes mt_partition and mt_version criteria can be combined with and
  operator. Combining them with OR operator is not supported.
• There can be max. 2 comparison operators.
• =changes= operator applies for mt_version only.
• For =changes= operator min. version must be less than or equal to max.
  version. Min. version is exclusive. If the version specified has been deleted,
  the lowest existing version is assumed. Max. version is inclusive. It must be
  greater than min. version.
• == operator with mt_version can use special keyword LATEST which queries
  for the latest version without explicitly defining it.

Examples:

• mt_version==100
• mt_version==LATEST
• mt_version=changes=(100,200)
• mt_partition==91717 (implicitly uses latest version)
• mt_partition==91717 and mt_version==100
• mt_partition=in=(91717,91718) (returns latest versions of these two
  partitions)
• mt_partition=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) (returns
  latest versions of all partitions of Munich)
• mt_partition=in=(FOO,BAR) (returns latest versions of these two partitions
  from a layer which does not use HERE tiling schema but generic tiling schema
  and has partitions named FOO and BAR)

Volatile Layer

Supported Attributes:

• mt_partition
• mt_timestamp

Supported Operators per Attribute:

• mt_partition
  • ==
  • =in=
  • =inboundingbox=
• mt_timestamp
  • =ge= (translates to since attribute for volatile partitions filter)
• and operator

Limitations:

• Attributes mt_partition and mt_timestamp criteria can be combined with
  and operator. Combining them with OR operator is not supported.
• There can be max. 2 comparison operators.
• =ge= operator applies for mt_timestamp only.

Examples:

• mt_partition==91717 (implicitly ignores partition if partition is expired)
• mt_partition==91717 and mt_timestamp=ge=1552383031000 (milliseconds since
  epoch; March 12, 2019 09:30:31 AM GMT)
• mt_partition=in=(91717,91718) (returns these two partitions if not expired)
• mt_partition=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) (returns all
  partitions of Munich if not expired)
• mt_timestamp=ge=1552383031000 (returns all partitions which were updated
  since milliseconds since epoch; March 12, 2019 09:30:31 AM GMT)

Interactive Map Layer

Supported Attributes:

• mt_quadkeys
• mt_geometry
• mt_id
• mt_property
• mt_selection

Supported Operators per Attribute:

• mt_quadkeys
  • ==
  • =in=
• mt_id
  • ==
  • =in=
• mt_geometry
  • =inboundingbox=
  • =inpolygon=
• mt_selection this attribute will create a projection of the properties in
  the object, e.g. mt_selection==p.foo will return only the property foo
  • ==
  • =in=
• f|p.* any attribute starting with f. or p.. p. is for selecting fields
  in the feature's properties, and f. is for selecting fields in the feature's
  root level
  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • =contains= this operation will check if a string is in the field
• and operator

Limitations:

• Query must be either empty or must contain at most one mt_quadkey, mt_id
  or mt_geometry.
• Bounding box or polygon must be inside the bounds:
  • Longitude: [-180, 180]
  • Latitude: [-85.05112878, 85.05112878]
• For bounding box north latitude must be greater than south latitude.
• Delete Queries only support mt_id. This means you can only delete objects by
  its ID.
  NOTE: empty RSQL delete query will delete everything.

Examples:

• mt_quadkeys==012313
• mt_quadkeys==012313 and f.timestamp>1552383031000 (returns all objects in
  QuadKey 012313 having a property timestamp with milliseconds since epoch;
  March 12, 2019 09:30:31 AM GMT)
• mt_quadkeys=in=(012313,012312) (returns these two QuadKeys)
• mt_geometry=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) (returns all
  objects in Munich)
• mt_geometry=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) and mt.selection==p.foo
  (returns only the property foo of all objects in Munich)
• mt_geometry=inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771) and p.foo=contains=bar
  (returns all objects in Munich having a field foo in properties and this field
  contains the string bar, for example, bar, 123bar, mybarfirst)