Filtering
A filter provides criteria for selecting entries used in a query. Unfiltered search includes all entries in the index. A filter scopes a search query to a subset of documents.
It is possible to use filtering in multiple ways:
- use OData for filtering by every filterable property. See filterable properties in search index schema.
Complex to use but gives you full control. - use custom filter properties for filtering. See request strucuture here Simplified usage without Azure Search internal know-how.
- use facets filter properties. For filtering by facets it's necessary to use property
filterPropertyName
from Search facet response as a request property name. See Facets. Simplified usage without Azure Search internal know-how.
Filtering samples¶
Filtering by categoryTree with odata filters¶
link:
https://api.discover.swiss/info/v2/search?resultsPerPage=5¤tPage=1&filters=categoryTree/any(category: category eq 'ch_root|ch_01|ch_0101')
link:
https://api.discover.swiss/info/v2/search
body:
{
"resultsPerPage": 5,
"currentPage": 1,
"filters": "categoryTree/any(category: category eq 'ch_root|ch_01|ch_0101')"
}
Filtering by Category(-ies) (request parameter)¶
link:
https://api.discover.swiss/info/v2/search?categoryTree=ch_root|ch_01|ch_0101|ch_010102&categoryTree=ch_root|ch_01|ch_0101|ch_010105
link:
https://api.discover.swiss/info/v2/search
body:
{
"categoryTree": ["ch_root|ch_01|ch_0101|ch_010102", "ch_root|ch_01|ch_0101|ch_010105"]
}
Filtering by Types and Datasources¶
link:
https://api.discover.swiss/info/v2/search?Type=Tour&type=Place&datasource=ZHT-CMS&datasource=oua
link:
https://api.discover.swiss/info/v2/search
body:
{
"type":["Place", "Tour"],
"datasource": ["oua", "ZHT-CMS"]
}
Filtering by CombinedType¶
link:
https://api.discover.swiss/info/v2/search?combinedType=LodgingBusiness&combinedType=Webcam
link:
https://api.discover.swiss/info/v2/search
body:
{
"combinedType":["LodgingBusiness", "Webcam"]
}
Filtering by the time range¶
link:
https://api.discover.swiss/info/v2/search?type=Tour&filters=((time gt 50) and (time lt 60)) or ((time gt 100) and (time lt 150))
link:
https://api.discover.swiss/info/v2/search
body:
{
"type":"Tour",
"filters": "((time gt 50) and (time lt 60)) or ((time gt 100) and (time lt 150))"
}
Filtering by review¶
If place contains review with reviewed items hasReview
is true
otherwise false
.
link:
https://api.discover.swiss/info/v2/search?type=Tour&filters=hasReview eq 'true'
link:
https://api.discover.swiss/info/v2/search
body:
{
"type":"Place",
"filters": "(hasReview eq 'true')"
}
Filtering by geo with odatafilters¶
Search Api supports geo-spatial queries in OData filter expressions via the geo.distance
and geo.intersects
functions.
The geo.distance function returns the distance in kilometers between two points, one being a field or range variable, and one being a constant passed as part of the filter. The geo.intersects function returns true if a given point is within a given polygon, where the point is a field or range variable and the polygon is specified as a constant passed as part of the filter.
Filtering can be applied to geo
and geoDestination
:
- geo: indicates the starting point of a tour and the location on all other entities.
- geoDestination: represents the end (last point) of a Tour and therefor is only available on Tour objects.
Filtering by distance¶
The geo.distance
function takes two parameters of type Edm.GeographyPoint
and returns an Edm.Double
value which is the distance between them in kilometers. This differs from other services that support OData geo-spatial operations, which typically return distances in meters.
One of the parameters to geo.distance
must be a geography point constant, and the other must be a field path (or a range variable in the case of a filter iterating over a field of type Collection(Edm.GeographyPoint)). The order of these parameters doesn't matter.
The geography point constant is of the form geography'POINT(longitude latitude)'
, where the longitude and latitude are numeric constants.
Warning
When using geo.distance in a filter, you must compare the distance returned by the function with a constant using lt (lower than), le (lower or equal), gt (greater than), or ge (greater or equal). The operators eq and ne are not supported when comparing distances.
Find entities by location:
https://api.discover.swiss/info/v2/search?type=Event&filters=geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5
Find tours which start OR end nearby a location:
https://api.discover.swiss/info/v2/search?type=Tour&filters=geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5 or geo.distance(geoDestination, geography'POINT(8.1734492 47.3907669)') le 5
Find tours which start AND end nearby a location:
https://api.discover.swiss/info/v2/search?type=Tour&filters=geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5 and geo.distance(geoDestination, geography'POINT(8.1734492 47.3907669)') le 5
link:
https://api.discover.swiss/info/v2/search
body:
Find entities by location:
{
"type":"Event",
"filters": "geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5"
}
Find tours which start OR end nearby a location:
{
"type":"Tour",
"filters": "geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5 OR geo.distance(geoDestination, geography'POINT(8.1734492 47.3907669)') le 5"
}
Find tours which start AND end nearby a location:
{
"type":"Tour",
"filters": "geo.distance(geo, geography'POINT(8.185059 47.387525)') le 5 AND geo.distance(geoDestination, geography'POINT(8.1734492 47.3907669)') le 5"
}
Filtering by polygons¶
The geo.intersects
function takes a variable of type Edm.GeographyPoint
and a constant Edm.GeographyPolygon
and returns an Edm.Boolean
-- true if the point is within the boundary of the polygon, false otherwise.
Warning
Note that the polygon is closed (the first and last points from the set must be the same)
link:
https://api.discover.swiss/info/v2/search?type=Event&filters=geo.intersects(geo, geography'POLYGON((10.089265201049788 46.71781861975809,10.056649539428694 46.70487120366226, 10.058709475952131 46.68285346787033, 10.083772036987288 46.67449144159856, 10.117760989624006 46.680027012226006, 10.121537539916975 46.706048369837056,10.089265201049788 46.71781861975809))')
link:
https://api.discover.swiss/info/v2/search
body:
{
"type":"Event",
"filters": "geo.intersects(geo, geography'POLYGON((10.089265201049788 46.71781861975809,10.056649539428694 46.70487120366226, 10.058709475952131 46.68285346787033, 10.083772036987288 46.67449144159856, 10.117760989624006 46.680027012226006, 10.121537539916975 46.706048369837056,10.089265201049788 46.71781861975809))')"
}
Filtering by hasGeoShape¶
Filtering by hasGeoShape
property allows to filter data which have geo shape (such as box, circle, line, polygon or multiline) and can be displayed on the map.
link:
https://api.discover.swiss/info/v2/search?type=Tour&hasGeoShape=true
link:
https://api.discover.swiss/info/v2/search
body:
{
"type": "Tour",
"hasGeoShape": "true"
}
Filtering by schedule¶
Filtering by schedule available only by filters
property.
Filteting by schedule/byDay¶
link:
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/byDay/any(day: day eq 'Monday'))
link:
https://api.discover.swiss/info/v2/search
body:
{
"type": "Event",
"filters": "schedule/any(item: item/byDay/any(day: day eq 'Monday'))"
}
Filtering by schedule/startDate and schedule/endDate¶
Properties schedule/startDate and schedule/endDate has DateTimeOffset
type and value for filtering should be presented in the following format: yyyy-mm-ddThh:mm:ss('.'s+)?(zzzzzz)
Timezone use cases in filter value:
yyyy-mm-ddThh:mm:ss.000001Z
- where Z - UTC timezoneyyyy-mm-ddThh:mm:ss+00:00
- where 00:00 - UTC timezoneyyyy-mm-ddThh:mm:ss.000001-02:00
- where UTC-02:00yyyy-mm-ddThh:mm:ss+06:00
- where UTC+06:00
Warning
Symbol +
in GET query string should be encoded to %2B
. E.g. filters=schedule/any(item: item/startDate lt 2020-04-14T00:00:00%2B02:00)
link:
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/startDate lt 2020-04-14T00:00:00Z)
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/endDate ge 2020-04-14T00:00:00Z)
or
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/startDate lt 2020-01-01T00:00:00Z and item/endDate ge 2020-04-01T00:00:00Z)
link:
https://api.discover.swiss/info/v2/search
body:
{
"type": "Event",
"filters": "schedule/any(item: item/startDate lt 2020-04-14T00:00:00Z)"
}
{
"type": "Event",
"filters": "schedule/any(item: item/endDate ge 2020-04-14T00:00:00Z)"
}
{
"type": "Event",
"filters": "schedule/any(item: item/startDate lt 2020-01-01T00:00:00Z and item/endDate ge 2020-04-01T00:00:00Z)"
}
Filtering by schedule/startTime and schedule/endTime¶
Azure Search doesn't support TimeSpan and that is why it is presented as string. That is why filtering available only for strings.
link:
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/startTime eq '12:00:00')
https://api.discover.swiss/info/v2/search?Type=Event&filters=schedule/any(item: item/endTime eq '12:00:00')
link:
https://api.discover.swiss/info/v2/search
body:
{
"type": "Event",
"filters": "schedule/any(item: item/startTime eq '12:00:00')"
}
{
"type": "Event",
"filters": "schedule/any(item: item/endTime eq '12:00:00')"
}
Filtering by lastModified¶
Property lastModified
has DateTimeOffset
type and value for filtering should be presented in the following format: yyyy-mm-ddThh:mm:ss('.'s+)?(zzzzzz)
Timezone use cases in filter value:
yyyy-mm-ddThh:mm:ss.000001Z
- where Z - UTC timezoneyyyy-mm-ddThh:mm:ss+00:00
- where 00:00 - UTC timezoneyyyy-mm-ddThh:mm:ss.000001-02:00
- where UTC-02:00yyyy-mm-ddThh:mm:ss+06:00
- where UTC+06:00
Warning
Symbol +
in GET query string should be encoded to %2B
. E.g. filters=lastModified lt 2020-04-14T00:00:00%2B02:00
link:
https://api.discover.swiss/info/v2/search?filters=lastModified lt 2020-04-14T00:00:00Z
https://api.discover.swiss/info/v2/search?filters=lastModified ge 2020-04-14T00:00:00Z
or
https://api.discover.swiss/info/v2/search?filters=lastModified lt 2020-01-01T00:00:00Z and lastModified ge 2020-04-01T00:00:00Z
link:
https://api.discover.swiss/info/v2/search
body:
{
"filters": "lastModified lt 2020-04-14T00:00:00Z"
}
{
"filters": "lastModified ge 2020-04-14T00:00:00Z"
}
{
"filters": "lastModified lt 2020-01-01T00:00:00Z and lastModified ge 2020-04-01T00:00:00Z"
}
OData filtering¶
You can read more about OData specification here
Structure samples¶
OData filter structure for property¶
identifier eq 'tou_4kq_bhgdcfdb'
OData filter structure for sub-property¶
address/addressLocality eq 'Martina'
OData filter structure for array¶
results/any(item: item eq 'something')
OData filter structure for sub-property in array¶
categoryTree/any(category: category eq 'ZHT-CMS_restaurants' or category eq 'TSVM-OUA_14359510')