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