You can filter the results of your API requests to refine the set of entities you want to obtain and limit the volume of data transferred between the back-end and your application.
The GoodData utilizes RSQL to define filters on the entities API. Only a subset of RSQL is supported, and we add our operators to make some queries easier.
You can filter the API call result by using URI parameter
filter as follows:
To filter a property with a desired value you have to form comparison rule, that contains of:
propertyas an attribute of queried entity,
comparison-operatorone of supported operators (see below),
argumentrepresent filtered value in form related to comparison operator, grouped eventually.
Following limitations apply:
- You can filter only results of the entities APIs
/api/entities/.... Declarative APIs do not support filtering.
- Take care to have the filter string properly url encoded e.g. quote values containing a whitespace character either with single or doubles quotes and apply url encoding to the entire value.
- Queries are case-sensitive in general. There are GoodData.CN specific operators allowing case-insensitive queries.
To filter upon multiple properties logical operator AND is available:
filter entities with specified title and tag:
filter=title=like=*date+and+tags==Sales(url encoded value) and
You can use the comparison operators listed bellow. Only a subset of RSQL is available.
filter entities having tag ‘Sales’:
Not equal to:
filter entities not having tag ‘Sales’:
filter entities having one of the specified tags ‘PreSales’ or ‘PostSales’:
filter=tags=in=(PreSales,PostSales)see also section grouping
filter entities which do not have at least one of the specified tags ‘PreSales’ or ‘PostSales’:
filter=tags=out=(PreSales,PostSales)see also section grouping
filter entities having a tag containing only substring ‘sales’:
filter entities having a tag containing a substring ‘sales’ regardless on the case sensitivity:
search for a specified pattern:
*to capture a group of characters
?to capture exactly one character
filter entities having a tag starting with letter P and ending with substring Sales:
Filtering via relationships
You can filter by a property from a referenced entity in case two entities are in a relationship. You have to specify the relationship property before the property you are going to filter (an extended form of the property)
For example, you can filter only visualizationObjects having relation to metrics with a title ‘quantities’ :
Filtering polymorphic properties
You use filtering via polymorphic properties when an entity relates to various types of entities through one property, i.e., relationship property is polymorphic, and referenced entities have different properties. In such a case, you need to specify the type of the property (referenced entity) in your filter:
If you are sure that all referenced entities inherit the property you want to use in your filter, you may omit the type definition:
To create a list / group of items to filter use grouping operator
() and separate items with
or - for example
(PreSales or PostSales).