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 allow you to search for data resources in LuciadFusion, the REST API extensively uses the RSQL specification for the definition of metadata property filters.

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.

RSQL logical and comparison operator support

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 1, “Supported RSQL comparison Operators” and Table 2, “Supported RSQL logical Operators” for an overview with example RSQL strings and supported property value types.

Table 1. 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, Enum

!=

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, Enum

> 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, Enum

=out=

Not in

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

String, Boolean, Long, Double, Date, Enum

=na= or =isnull= or =null=

Is null

stringProp=na=''

String, Boolean, Long, Double, Date, Enum

=nn= or =notnull= or =isnotnull=

Is not null

stringProp=nn=''

String, Boolean, Long, Double, Date, Enum

=ic= or =icase=

Ignore case.

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

stringProp=ic=FUSION

String, Enum

=bt= or =between=

Between

longProp=bt=(2,5)

Long, Double, Date

=nb= or =notbetween=

Not between

longProp=nb=(2,5)

Long, Double, Date
Table 2. 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 3. 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

Fuzzy string matching

Fuzzy matching of Texts/Strings is supported through the == and != RSQL operators.

Table 4. 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==c??t finds cast, chat, cart, cost, and cent.

^

Represents that the search is case-insensitive when placed at the beginning of the text or string.
For example, word==^c??t finds cast, CAST, chat, ChAt, cart, caRt, cost, CoSt, CeNT and cent.

\

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

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 5. Standard properties
Property Queryable name Example RSQL String

ID

lfn.id

lfn.id==someId

Creation Time

lfn.creationTime

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

Update Time

lfn.updateTime

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

File Path

lfn.filePath

lfn.filePath==someFilePath

Type

lfn.type

lfn.type==SHP

Title

lfn.title

lfn.title==someTitle

Abstract Text

lfn.abstractText

lfn.abstractText==someText

Supported property comparisons

The GET /api/data/filter REST API endpoint supports three types of comparisons.

Table 6. 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 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 a 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 value that are to be compared.

In a property name to property name comparison, it is mandatory to enclose the property names that are part of right side of the comparsion operator in a ${} placeholder. e.g. lfn.type==${lfn.title}

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: (prop1=gt=10);(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