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 backend and your application.

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.

Filter

Filter the API call result using URI parameter filter as follows:

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

where <RSQL> is the RSQL query consisting of <property><operator><arguments>;:

  • property is an attribute of the queried entity
  • operator is one of the supported logical or comparison operators
  • argument represents the filtered value in form related to comparison operator

Example

Fetch only visualizationObjects that use a metric with the word ‘sale’ in the metrics title:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title=containsic='sale';

Note that this example uses the containsic operator which is the case-insensitive variation of the contains operator. See below for a complete list of supported operators.

Operators

Logical operators

To filter for multiple properties at the same time, use the AND logical operator:

  • Logical AND: and or ;

    Example: Filter entities with specified title and tag ‘Sales’. Using the and operator and url encoded value:

    filter=title=like=*date+and+tags==Sales

    or using the ; operator:

    filter=title=like=*date;tags==Sales

Comparison operators

The following subset of RSQL comparison operators is available:

  • Equal to: ==

    Example: Filter entities having tag ‘Sales’:

    filter=tags==Sales

  • Not equal to: !=

    Example: Filter entities not having tag ‘Sales’:

    filter=tags!=Sales

  • In: =in=

    Example: Filter entities having one of the specified tags ‘PreSales’ or ‘PostSales’:

    filter=tags=in=(PreSales,PostSales)

    See grouping.

  • Not in: =out=

    Example: Filter entities which do not have at least one of the specified tags ‘PreSales’ or ‘PostSales’:

    filter=tags=out=(PreSales,PostSales)

    See grouping.

  • Case-sensitive contains: =contains=

    Example: Filter entities having a tag containing only substring ‘sales’:

    filter=tags=contains=Sales

  • Case-insensitive contains: =containsic=

    Example: Filter entities having a tag containing a substring ‘sales’ regardless on the case sensitivity:

    filter=tags=containsic=sales

  • Pattern search: =like=

    • * to capture a group of characters
    • ? to capture exactly one character

    Example: Filter entities having a tag starting with letter P and ending with substring Sales:

    filter=tags=like=P*Sales

  • Is null: =isnull=

    • true to capture fields that are null
    • false to capture fields that are not null

    Example: Filter entities where some field is null:

    filter=someField=isnull=true

Filtering Using 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>

Example

Filter only visualizationObjects having relation to metrics with a title ‘quantities’:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title==quantities

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).

Origin

By default the api/v1/entities/workspaces/{workspaceId}/... API endpoints return entity definitions from the {workspaceId} workspace, as well as any parent workspaces the {workspaceId} may have. You can control this behaviour using the origin URI parameter:

.../api/v1/entities/...[?&]origin=ALL|PARENTS|NATIVE

where:

  • ALL returns entity definitions from the {workspaceId} workspace and from its parent workspaces (default behaviour)
  • PARENTS only returns entity definitions from the parent workspaces
  • NATIVE only returns entity definitions from the {workspaceId} workspace

Example

Fetch only visualizationObjects that use a metric with the word ‘sale’ in the metrics title and fetch visualizationObjects only from the {workspaceId} workspace itself, none from its parent workspaces:

.../api/v1/entities/workspaces/{workspaceId}/visualizationObjects?filter=metrics.title=containsic='sale'&origin=NATIVE;

Limitations

The following limitations apply to the filtering of API requests:

  • You can filter only results of the entities APIs /api/v1/entities/.... Declarative APIs do not support filtering.
  • Ensure the filtered string is properly url encoded. For example, wrap values containing a whitespace character with single or doubles quotes and apply url encoding to the entire value.
  • Queries are case-sensitive in general. There are GoodData specific operators allowing case-insensitive queries.
Errors
Versioning