GuidesChangelogData Inspector Library API Reference
Guides
  1. Data Client Library
  2. Get started with the Data Client Library

RSQL

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:

OperatorAlternative SyntaxMeaningExample
==Equal totileId==91717
!=Not equal totileId!=91717
<=lt=Less thanlimit<100 or limit=lt=100
<==le=Less than or equallimit<=100 or limit=le=100
>=gt=Greater than operatorlimit>100 or limit=gt=100
>==ge=Greater than or equal tolimit>=100 or limit=ge=100
=in==IN=IntileId=in=(91717,91718)
=out=Not intileId=out=(91717,91718)

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

OperatorMeaningExample
orLogical ORtileId==91717 or limit<100
andLogical ANDtileId!=91717 and limit<100

Additionally, Data Client Library supports the following custom operators:

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

OperatorAlternative SyntaxMeaningExample
=inboundingbox==INBOUNDINGBOX=In area described by bounding box=inboundingbox=(northLatitude, southLatitude, eastLongitude, westLongitude)
e.g. for Munich =inboundingbox=(48.2292, 48.0417, 11.7490, 11.3771)
coordinates are in decimal degrees
=incircle==INCIRCLE=In area described by circle=circle=(centerLatitude, centerLongitude, radiusInMeters)
e.g. circle covering Munich Airport =circle=(48.3536621, 11.7750279, 5000)
coordinates are in decimal degrees
=inpolygon==INPOLYGON=In area described by polygon=inpolygon=(long1,lat1,long2,lat2,...)
coordinates are in decimal degrees
=changes==CHANGES=Version range from min. version to max. version=changes=(minVer,maxVer)
e.g. =changes=(100,200)
=contains==CONTAINS=Checks if field contains a string=contains=(string)
e.g. =contains=(food)

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)

Updated 22 days ago