The LuciadFusion data processing engine consumes data resources with associated metadata. GIS applications can use that metadata information to identify, organize, analyze, store, visualize, and query data resources. This article describes how you can use the REST API to query LuciadFusion Studio for data resources based on the associated metadata.

To get the most out of the filter REST API, it’s recommended to define custom metadata properties by following these steps.

  1. Create an ILfnCustomPropertyDecoder.

  2. Define the custom properties.

  3. Make sure that metadata properties are associated with the data resources that you want to search for.

See Create a custom property decoder for details.

See the REST API Console and REST API documentation for more information on working with custom metadata properties using the REST API. If an instance of LuciadFusion is running, you can find them at http://localhost:8081/api/console and http://localhost:8081/api/documentation respectively.

Introduction to RSQL

To allow you to search for data resources in LuciadFusion, the REST API extensively uses the RSQL specification for the definition of metadata property filters.

An RSQL filter consists of one or more metadata property comparisons. You can combine these comparisons into a single filter by using logical operators.

For example, let’s look at the following RSQL filter: (prop1=gt=10);(lfn.creationTime=gt=2022-11-09T00:00:00+05:30).

  • This filter consists of the two RSQL comparisons prop1=gt=10 and lfn.creationTime=gt=2022-11-09T00:00:00+05:30.

  • The two comparisons are joined by the ; character, which is the logical AND operator.

  • prop1=gt=10 is a comparison using the greater-than operator =gt=. It selects data resources where the custom metadata property prop1 is greater than the literal value 10.

  • Similarly, the expression (lfn.creationTime=gt=2022-11-09T00:00:00+05:30) selects data resources with a creation time after the date of the 9th of September 2022.

  • The complete filter combines these two comparisons with an AND operator, so only those data items that match both comparisons get selected.

LuciadFusion metadata property categories

LuciadFusion can work with two categories of metadata properties :

  • Standard metadata properties: the properties in this category are available out-of-the-box for any data resource processed by LuciadFusion Studio.

  • Custom metadata properties: users define these metadata properties and associate them with data resources managed by LuciadFusion. See Create a custom property decoder and a custom properties definition for details on defining custom properties.

  • Every standard property must have the prefix lfn. in the query string. For example, lfn.id==someId.

  • You don’t have to prepend custom properties with a prefix. If you are using a property defined as customProp in the filter REST API, you can query for customProp=gt=someValue, for example.

Here is a list of standard properties that you can use in the filter REST API:

Table 1. Standard properties
Property Queryable name Type Collection Example RSQL String

ID

lfn.id

String

lfn.id==someId

Creation Time

lfn.creationTime

Date

lfn.creationTime==2022-11-09T00:00:00+05:30

Update Time

lfn.updateTime

Date

lfn.updateTime=gt=2022-11-09T00:00:00+05:30

File Path

lfn.filePath

String

lfn.filePath==someFilePath

Type

lfn.type

String

lfn.type==SHP

Title

lfn.title

String

lfn.title==someTitle

Abstract Text

lfn.abstractText

String

lfn.abstractText==someText

Categories

lfn.categories

String with limited possible values

✔

lfn.categories=contains=Raster

Keywords

lfn.keywords

String

✔

lfn.keywords=contains=someKeyword

Properties have a type that defines what comparisons are valid. For example, it’s impossible to compare a property of the Integer type with a Date value, or to compare two String types using a =gt= (greater-than) operator. For more information on the types supported by each operator, see the section on RSQL operators.

The Categories and Keywords properties are collection properties, because one data resource can have multiple categories and multiple keywords. These are the only two properties of the collection type. It isn’t possible to define custom metadata properties with a collection type.

The possible values for the Categories property are listed in the GET /api/data/queryable-properties REST endpoint.

RSQL operators

The filter REST API supports a rich collection of comparison and logical operators. You can use them to create property filters to query data resources based on the defined queryable properties. See Table 2, “Supported RSQL comparison operators”, Table 3, “Supported RSQL comparison operators on collection types” and Table 4, “Supported RSQL logical operators” for an overview with example RSQL strings and supported property value types.

Table 2. Supported RSQL comparison operators
Operator Description Example RSQL String Property types

==

Equal to.

The asterisk (*) wildcard character allows for the substitution of one or more characters.

longProp==5

stringProp==fusion*

String, Boolean, Long, Double, Date

!=

Not equal to.

The asterisk (*) wildcard character allows for the substitution of one or more characters.

longProp!=5

stringProp!=fusion*

String, Boolean, Long, Double, Date

> or =gt=

Greater than

longProp>5

Long, Double, Date

>= or =ge=

Greater than or equal

longProp>=5

Long, Double, Date

< or =lt=

Less than

longProp<5

Long, Double, Date

<= or =le=

Less than or equal

longProp<=5

Long, Double, Date

=in=

In

lfn.type=in=(SHP,"3D Tiles")

String, Boolean, Long, Double, Date

=out=

Not in

lfn.type=out=(SHP,"3D Tiles")

String, Boolean, Long, Double, Date

=na= or =isnull= or =null=

Is null.

stringProp=na=''

String, Boolean, Long, Double, Date

=nn= or =notnull= or =isnotnull=

Is not null

stringProp=nn=''

String, Boolean, Long, Double, Date

=ic= or =icase=

Ignore case.

This operator doesn’t support any of the wildcard string/text matching. This also means that you can’t use the wildcard characters *, ? and ^.

stringProp=ic=FUSION

String

=bt= or =between=

Between

longProp=bt=(2,5)

Long, Double, Date

=nb= or =notbetween=

Not between

longProp=nb=(2,5)

Long, Double, Date
Table 3. Supported RSQL comparison operators on collection types
Operator Description Example RSQL String

=na= or =isnull= or =null=

Is null.

For collection properties this matches an empty collection.

lfn.keywords=na=''

=nn= or =notnull= or =isnotnull=

Is not null

For collection properties this matches a non-empty collection.

lfn.keywords=nn=''

=contains=

Contains

lfn.categories=contains=Vector

=notcontains=

Does not contain

lfn.categories=notcontains=Vector
Table 4. Supported RSQL logical operators
Operator Description Example RSQL String

; or and

Logical AND

longProp==5;boolProp==false

, or or

Logical OR

longProp==5,boolProp==false

Operator precedence

The AND logical operator takes precedence over OR. You can use a parenthesized expression to change the precedence, though, yielding whatever the contained expression yields.

Table 5. RSQL logical expression examples
Example Expression Interpretation

prop1==foobar || prop1==foo && prop2==foobar

prop1==foobar || (prop1==foo && prop2==foobar)

prop1==foobar && prop2==foo || prop2==foobar && prop1==foo

(prop1==foobar && prop2==foo) || (prop2==foobar && prop1==foo)

prop1==foobar && prop2==foo && prop2==foobar || prop1==foo

((prop1==foobar && prop2==foo) && prop2==foobar) || prop1==foo

Wildcard string matching

Wildcard-based pattern matching of text is supported through the ==, !=, =contains= and =notcontains= RSQL operators. There is a single exception: the lfn.categories standard property doesn’t support wildcard matching, but you can still select multiple categories by combining queries using the OR logical operator.

Table 6. Supported wildcard characters
Wildcard character Description

*

Represents zero or more characters.
For example, word==co* finds co, cover, concept, commerce, and convention.

?

Represents a single character.
For example, word==co??t finds coast, comet, count and court.

^

Represents that the search is case-insensitive when placed at the beginning of the text or string.
For example, word==^co??t finds coast, COAST, comet, CoMeT, count and couNt.
The ^ character when used should be placed at the beginning of the text or string irrespective of the presence of other wildcard characters.
For example, word==^*der finds Reader, reader, REAder, READER, RIder, rider etc.

\

Represents that the character following the \ must be escaped within a string or text. For example, word==Daisy\'s book escapes the character '.

Supported property comparisons

The examples so far showed that it’s possible to compare metadata to a literal value or a wildcard matching pattern. Additionally, it’s possible to create filters that compare metadata properties with other metadata properties.

This means the GET /api/data/filter REST API endpoint supports three types of comparisons, as listed in Table 7, “Comparison operation types”.

Table 7. Comparison operation types
Comparison Type Example RSQL String Explanation

Comparing properties with literal values

lfn.type==someType

The left operand is a property name, the right operand is a literal value. The value of the property referred to by the left operand will be compared to the literal value of the right operand. The property name expression ${lfn.propertyName} is equivalent to using lfn.propertyName as the property name for the left operand.

Comparing properties with other properties

lfn.type==${somePropertyName}

The left operand is a property name, and the right operand is a property name expression. The value of the property referred to by the left operand will be compared to the value of the property name expression of the right operand.

Comparing properties with both literal values and other properties

lfn.type=in=(${somePropertyName},'someType')

This approach is a mix of previous approaches where the left operand is a property name, and the right hand side is a list of operands of one or more property name expressions and one or more literal values that are to be compared.

In a property name to property name comparison, it’s mandatory to enclose the property names that are part of right side of the comparison operator in a ${} placeholder, lfn.type==${lfn.title} for example.

Sample querying example

This example shows how you can use the GET /api/data/filter endpoint to search for LuciadFusion data resources with a custom property prop1 and a standard property lfn.creationTime. The properties are part of an RSQL query string to retrieve the matching data resources.

Sample RSQL query string used: lfn.creationTime=gt=2022-11-09T00:00:00+05:30

Step 1

Launch the REST API console at http://localhost:8081/api/console
rest api console
Step 2

Expand the Data section to navigate to the filter REST API.

rest filter api expanded

Step 3

Click the Try it out button to enable the user interaction with the REST API console.

Step 4

Fill in the query parameters.

rest filter api query params

  • page: the page of the returned response.

  • pageSize: the maximum number of results on each page as part of the response.

  • rsqlQuery: the RSQL query string for filtering data resources based on queryable properties.

  • sortBy: the order of the results returned as part of the response. The result can be sorted by attributes such as title, type, creationTime and updateTime.

  • sortOrder: the order in which results are sorted. The possible values can be ascending (ASC) or descending (DESC).

Step 5

Click the Execute button to start the HTTP REST API request and get the results.

The sample response is:

rest filter api response