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
boost

Full text search field boosts

boost=property:{boost} where property is a text property of a class, and boost is a score multiplication factor, using the same syntax factor as used in OpenSearch

facets Facets to be listed, eg, facets=type
facetSize Number of facets to include in results, egfacetSize=10
dateFacets Date facets, eg dateFacets=publishedDate:1d:1w:1M
fields List of fields to be included in the response, egfields=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

Embed multiple levels using the syntax embed=level:{level} where level = 1, 2 or 3

embed=level:1 is equalivalent to embed=_all

ids List of Concept ids to be returned (separated by a comma), eg ids=id1,id2,id3
includeDateFields

A boolean flag that will include the automatic date fields (_createdDate and _lastModifiedDate in the Concept JSON response, e.g.

includeDateFields=true

this flag defaults to false

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


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)