Filter Entities

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:

/api/entities/...[?&]filter=<RSQL>

To filter a property with a desired value you have to form comparison rule, that contains of:

• property as an attribute of queried entity,
• comparison-operator one of supported operators (see below),
• argument represent filtered value in form related to comparison operator, grouped eventually.

filter=property=comparison-operator=arguments;

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.

Logical operators

To filter upon multiple properties logical operator AND is available:

• Logical AND: and or ;

  filter entities with specified title and tag: filter=title=like=*date+and+tags==Sales (url encoded value) and filter=title=like=*date;tags==Sales

Comparison operators

You can use the comparison operators listed bellow. Only a subset of RSQL is available.

• Equal to: ==

  filter entities having tag ‘Sales’: filter=tags==Sales

• Not equal to: !=

  filter entities not having tag ‘Sales’: filter=tags!=Sales

• In: =in=

  filter entities having one of the specified tags ‘PreSales’ or ‘PostSales’: filter=tags=in=(PreSales,PostSales) see also section grouping

• Not in: =out=

  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

• Case-sensitive contains: =contains=

  filter entities having a tag containing only substring ‘sales’: filter=contains==sales

• Case-insensitive contains: =containsic=

filter entities having a tag containing a substring ‘sales’ regardless on the case sensitivity: filter=containsic==sales

• search for a specified pattern: =like=

  • * 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: filter=tags=like=P*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)

<relationship-property-name>.<property-of-related-entity>

For example, you can filter only visualizationObjects having relation to metrics with a title ‘quantities’ :

.../visualizationObjects?filter=metrics.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:

<relationship-property-name>::<required-entity-type>.<property-of-required-entity-type>

filter=animal::bird.numberOfWings==2

filter=animal::cat.furColor==black

If you are sure that all referenced entities inherit the property you want to use in your filter, you may omit the type definition:

filter=mammal.numberOfLegs==4

Grouping

To create a list / group of items to filter use grouping operator () and separate items with , or or - for example (PreSales,PostSales) or (PreSales or PostSales).