Query parameter reference

Datagraphs API makes a range of query parameters available for organizing and refining searches for Datasets and Concepts. 

Definitions

Building a filter expression

Filter expressions can be constructed from a property, value and optional operator. More complex queries can use a filter function (see below).

In its simplest form a filter expression consists of a property and a value, eg filter=property1:value1 , where the separator (:) is equivalent to "=". Adding an operator allows for different types of comparisons. 

Filter expressions can be combined using ,  (AND) or |  (OR). Using parentheses around combinations of expressions – eg ({expression1},{expression2})  – overrides operator precedence.

The following defines the rules for each element in a constructed filter expression:

Filter functions

Functions for more complex queries follow the format filter=_functionName(arg1, arg2, etc) . The following are supported:

_has()

Search for Concepts where a given property is populated.

_lacks()

Search for Concepts where a given property is undefined.

Where a property is nested, _has() and _lacks() can accept the path to that property, eg _has(address.postcode) , but will not filter on an object, eg _has(address) .

Geospatial Functions

_within()

Search for Concepts within a given area. 

Coordinates can be provided either as latitude and longitude in the format (lat, long) , or as a geohash. If two coordinates are provided, they define the top left and bottom right corners of the search area as a bounding box. Three or more coordinates define the search as a polygon.

NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property.

_near()

Search for Concepts within range of a given location. 

Coordinates can be provided either as latitude and longitude in the format (lat, long)  or as a geohash.

The following units are supported for distance:

• mi  – miles
• km  – kilometres
• m  – metres
• cm  – centimetres
• mm  – millimetres

NB This function can only be used with Concepts whose properties include either a latitude/longitude pair or a geohash property.

Filter examples

The following expressions can all be used on a Search Concepts query:

Comparisons

• Search Concepts where string1 equals value1

  filter=string1:value1

• Search Concepts where string1  equals value1  and string2  equals value2

  filter=string1:value1,string2:value2

• Search Concepts where string1  equals value1  and string2  does not equal value2

  filter=string1:value1,string2:-value2

• Search Concepts where string1  equals value1  or value2

  filter=string1:[value1,value2]

Dates

All Concepts have two properties _createdDate and _lastModifiedDate that are internally and automatically maintained by the graph. They are prefixed with an underscore.

• Search Concepts created between 2020-01-01  and 2020-02-01

  filter=_createdDate:>=2020-01-01,_createdDate:2020-02-01

• Search Concepts created or modified since  2020-01-01

  filter=_createdDate:>=2020-01-01|_lastModifiedDate:>=2020-01-01

• Search Concepts where string1  equals value1  and it was created or modified since 2020-01-01

  filter=string1:value1,(_createdDate:>=2020-01-01|_lastModifiedDate:>=2020-01-01)

• You can also filter using the above pattern using any date or datetime properties that you have modelled in your project using the date property name.

Geospatial

• Search Concepts within 100 miles of coordinates (-40, 70)

  filter=_near((-40, 70), 100mi)

• Search Concepts within a polygon with points (-40, 70), (-30, 60), (-35, 60)

  filter=_within((-40, 70) (-30, 60), (-35, 60))

• Search Concepts within a box with top left corner (-40, 70) and bottom right corner (-30, 60)

  filter=_within((-40, 70) (-30, 60))

Property validation

• Search Concepts where property1 is populated

  filter=_has(property1)

• Search Concepts where property1 on object1 is populated

  filter=_has(object1.property1)

• Search Concepts where property1 is undefined

  filter=_lacks(property1)

• Search Concepts where property1 on object1 is undefined

  filter=_lacks(object1.property1)