Filter expressions in Nebula

Overview

In order to simplify your API usage and enrich API consumption you can make a decision about what results and the number of results you want to show.

You can do this by using filter expressions which are an advanced way to filter queries in Nebula without the need for custom implementations for each use case.

Example expressions

Equals, filter by field:
Example: display_name == 'Baker Street elevator'
Using logical operators (&&, ||, etc.):
Example: display_name == 'Baker Street elevator' || name == 'installations/surelock-homes-hq/gateways/conan-doyle-gateway'
Using parentheses:
Example: (display_name == 'Baker Street elevator' && name == 'installations/surelock-homes-hq/gateways/conan-doyle-gateway') || display_name == 'Maintenance door'

Supported expressions

You can use filters to limit your terms so they only apply to specific fields within applicable objects. Preface a term with one of the filters in the table below. The more terms you provide in your query, the more specific the results you'll get.

Operator	Description	Type	Example
`!`	`not`. Is not "Baker Street Entrance" (is any value except "Baker Street Entrance"). Matches "Back door", "Maintenance door", but not "Baker Street Entrance"	`bool`	`display_name ! 'Baker Street Entrance'`
`&&`	`and`. Is equal to "Sherlock" and "Watson"	`bool`	`given_name == 'Sherlock' && family_name == 'Watson'`
`\|\|`	`or`. Is equal to either "Sherlock" or "Watson"	`bool`	`given_name == 'Sherlock' \|\| family_name == 'Watson'`
`==`	`equals`. Is equal to "Entrance gateway"	`string`, `int`	`display_name == 'Entrance gateway'`
`!=`	`not equals`. Is not equal to "Baker Street elevator"	`string`, `int`	`display_name == 'Baker Street elevator'`
`in`	Is in a list containing "Sherlock Holmes"	`string`, `int`	`display_name in['Sherlock Holmes']`
`contains`	Contains "son", matches "Hudson" and "Mrs Hudson"	`string`	`display_name.contains('son')`
`endsWith`	Ends with "lock". Matches "erlock" and "Sherlock" but not "Sherlock Holmes"	`string`	`display_name.endsWith('lock')`
`startsWith`	Starts with "Sher". Matches "Sherlock" and "Sherlock Holmes" but not "John" or "John Watson"	`string`	`display_name.startsWith('Sher')`

Notes

Matches in string filters are case insensitive. For example: the expressions SHERLOCK and sherlock will match the word "Sherlock"
Some filters can only be applied to strings. For example: contains, startsWith, endsWith whereas others, for example, equals support both strings and ints
Filter terms are in camelCase
The maximum length of the filter is 20000 characters
Filters can be combined using or, and and not boolean logic

Example request

Below you can find an example request for a user search. Examples are in JSON format.

json

{
  "parent": "installations/surelock-homes-hq",
  "page_size": 10,
  "filter": "display_name.startsWith('Sherlock')"
}

Example response

json

{
  "users": [
    {
      "name": "installations/surelock-homes-hq/users/01DMDAFG5GGW8XNJYTTFA4XCJ6",
      "first_name": "Sherlock",
      "last_name": "Holmes",
      "display_name": "Sherlock Holmes",
      "email": "sherlock@surelockhomes.com",
      "activate_time": {
        "seconds": "1568110176",
        "nanos": 0
      },
      "expire_time": null
    }
  ],
  "next_page_token": ""
}

Example request with Boolean operator

Each Boolean operator can be wrapped in parentheses to group and / or change the precedence when executing the query. For example:

json

{
  "parent": "installations/surelock-homes-hq",
  "page_size": 10,
  "filter": "(display_name.startsWith('sherlock') || display_name.startsWith('john')) && display_name.endsWith('watson')"
}

Error handling

Filtering on a service that doesn't contain filter functionality will result in an error which currently looks something like this: 2 UNKNOWN: ERROR: <input>:1:1: undeclared reference to 'field'
Filtering using a combination of more than 3 expressions will result in an error, for example: 2 UNKNOWN: expr: limit of 3 depth level exceed

Filter by date

You can also filter over google.protobuf.Timestamp types. This is useful if you want to filter for events such as the unlocking of access points that take place within an installation over a specific time period.

The following is an example of a ListEvents using the parameter occur_time:

json

{
  "parent": "installations/acme",
  "page_size": 10,
  "filter": "occur_time <= timestamp('2020-05-27T13:35:36.697714Z')"
}

You can use the following operators in the date filter:

Operator	Description
`>`	Greater than
`<`	Less than
`>=`	Greater than or equal to
`<=`	Less than or equal to

You can combine these with && (and) and || (or).

Best practices

Filtering is provided on List methods (or similar methods to query a collection, such as Search). Searches can be performed with a single term. Use something that would be atypical, such as a name or email address. If you are seeing a small number of results, make the term less specific. If there is a large number of results, include additional terms, one at a time.

Contents