Query parameter reference

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

Definitions

pageSize	The number of results to return in the response, eg pageSize=10
pageNo	The page number indicating which set of results should be returned in the response, eg pageNo=2
sort	Sorts the results in the response using a specified field and direction, eg sort=property1:asc,property2:desc
filter	A expression that filters a request. It is a string that takes the form  {property}:{operator}{value} or uses a special function
q	Full text search, eg q=name
facets	Facets to be listed, eg, facets=type
facetSize	Number of facets to include in results, eg facetSize=10
dateFacets	Date facets, eg dateFacets=publishedDate:1d:1w:1M
fields	List of fields to be included in the response, eg fields=id,label,image
embed	List of ids of related properties to be embedded in the response, eg embed=id1,id2,id3 or for all properties embed=_all
ids	List of Concept ids to be returned (separated by a comma), eg ids=id1,id2,id3

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:

Property	A path representing the field to filter on.	It matches [a-zA-Z_][a-zA-Z0-9_.]. It supports . separated paths. It can contain only alpha-numeric characters and _. It cannot contain whitespace. It must start with a letter.
Operator	Used to compare values (on its own is roughly =); optional.	- not > greater than >= greater than or equals < less than <= less than or equals [ value, value, ... ] in group
Value	A string containing the value to match the expression against.	It can contain whitespace. Dates and datetimes should be in ISO 8601 format.

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

_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

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

Geometry

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