The tags attribute is a String List, or in other words, an Array. Arrays has a range of useful filters.
Field Type: Array
Filters Available: exact (=), contains, contained_by, overlap, len, isnull
exact
Filters for an exact match of items in the Array (length and order of items in Array).
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags=usa,san%20diego
//Returns Array 'results' with matching device
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"tags": [
"usa",
"san diego"
],
...
}
]
}
contains
Filters for Arrays containing one or more item.
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags__contains=colombia
//Returns Array 'results' with device containing the tag 'colombia'
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"tags": [
"colombia",
"antioquia"
],
...
}
]
}
Attention
Even though some attributes might seem as if the order doesn't matter, for instance in the case of
tags, the data structure is Array, hence the order matters.
contained_by
Filters for Arrays that are completely contained by the superset provided as query param, i.e. all items from the query parameter mus match exactly the items found in the array.
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags__contained_by=antioquia,colombia
//Returns Array 'results' with matching tags array that is contained by items provided in the query
{
"count": 4,
"next": null,
"previous": null,
"results": [
{ "tags": [
"colombia",
"antioquia"
],
...
}
]
}
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags__contained_by=colombia,usa
//Returns empty Array as devices are not completely contained by items provided in query
{
"count": 0,
"next": null,
"previous": null,
"results": []
}
Empty Arrays
Please note that any empty array is a subset of any superset. Hence all empty devices will be retrieved as well. To avoid that, please add the query parameter
<array>__len=#where # is the number of items in the array.
Feature
Order of the query parameters do not matter for the filter
contained__by.
overlap
Filters for Arrays that overlap with parameters provided in query.
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags__overlap=colombia,usa
//Returns Array 'results' matching two devices since their tags overlap
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"tags": [
"colombia",
"antioquia"
],
...
},
{
"tags": [
"usa",
"san diego"
],
...
}
]
}
len [length]
Filters for Arrays matching the length parameter provided in the query.
GET https://industrial.api.ubidots.com/api/v2.0/devices/?tags__len=0
//Returns Array 'results' with all empty Arrays
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"tags": [],
...
},
{
"tags": [],
...
},
{
"tags": [],
...
}
]
}
The __isnull filter can be applied to Arrays as described in the Boolean section.