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
|
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 multiple levels using the syntax
|
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. |
|
Operator | Used to compare values (on its own is roughly =); optional. |
|
Value | A string containing the value to match the expression against. |
|
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
– mileskm
– kilometresm
– metrescm
– centimetresmm
– 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
equalsvalue1
filter=string1:value1
Search Concepts where
string1
equalsvalue1
andstring2
equalsvalue2
filter=string1:value1,string2:value2
Search Concepts where
string1
equalsvalue1
andstring2
does not equalvalue2
filter=string1:value1,string2:-value2
Search Concepts where
string1
equalsvalue1
orvalue2
filter=string1:[value1,value2]
Dates
Search Concepts created between
2020-01-01
and2020-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
equalsvalue1
and it was created or modified since2020-01-01
filter=string1:value1,(createdDate:>=2020-01-01|lastModifiedDate:>=2020-01-01)
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 populatedfilter=_has(property1)
Search Concepts where
property1
onobject1
is populatedfilter=_has(object1.property1)
Search Concepts where
property1
is undefinedfilter=_lacks(property1)
Search Concepts where
property1
onobject1
is undefinedfilter=_lacks(object1.property1)