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:

Operator Alternative Syntax Meaning Example
== Equal to tileId==91717
!= Not equal to tileId!=91717
< =lt= Less than limit<100 or limit=lt=100
<= =le= Less than or equal limit<=100 or limit=le=100
> =gt= Greater than operator limit>100 or limit=gt=100
>= =ge= Greater than or equal to limit>=100 or limit=gt=100
=in= =IN= In tileId=in=(91717,91718)
=out= Not in tileId=out=(91717,91718)

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

Operator Meaning Example
OR Logical OR tileId==91717 OR limit<100
AND Logical AND tileId!=91717 AND limit<100

Additionally, Data Client Library supports the following custom operators:

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

Operator Alternative Syntax Meaning Example
=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)

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 please 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, e.g. 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 please 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 criterias 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 criterias 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)

results matching ""

    No results matching ""