Get in touch
Get in touch

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)