Filters 🔗
Catalog 🔗
/datasets/{id}/filters/
GET on this resource returns a Shoji Catalog with the list of Filters that the current user can use on this Dataset.
This index contains two kinds of filters: public and personal, denoted by
the is_public tuple attribute. Personal filters are those created by
the authenticated user, and they cannot be accessed by other users.
Public filters are available to all users who are authorized to view the
dataset.
{
"name": "My filter",
"is_public": true,
"id": "1442ea",
"owner_id": "https://app.crunch.io/api/users/4152de/",
"team": "https://app.crunch.io/api/teams/680abc/"
}
The only tuple attribute editable via PATCH``ing the catalog is the
"name". A 204 response indicates a successful ``PATCH. Attempting to PATCH
any other attribute will return a 400 response.
POST a Shoji Entity to this catalog to create a new filter. Entities
must include a name and an expression. If omitted, is_public
defaults to False. A successful POST yields a 201 response that will
contain a Location header with the URL of the newly created filter.
All users with access to the dataset can create personal filters;
however, only the current dataset editor can create public filters
(is_public: true). Attempting to create a public filter when not the
current dataset editor results in a 403 response.
Public filters cannot contain references to secure variables. Attempting to create one results in a 400 response. Hidden variables, however, are permitted.
Entity 🔗
/datasets/{id}/filters/{id}/
GET this resource to return a Shoji Entity containing the requested filter.
{
"element": "shoji:entity",
"self": "https://app.crunch.io/api/datasets/ac64ef/filters/1442ea/",
"views": {
"applied": "https://app.crunch.io/api/datasets/ac64ef/filters/1442ea/applied/"
},
"body": {
"id": "1442ea",
"name": "My filter",
"is_public": true,
"expression": {},
"last_update": "2015-12-31",
"creation_time": "2015-11-12T12:34:56",
"team": "https://app.crunch.io/api/teams/680abc/"
}
}
PATCH an entity to edit its expression, name, team or
is_public attributes. Successful PATCH requests return 204 status.
As with the POST``ing new entities to the catalog, only the dataset's
current editor can alter a public filter. Likewise, attempting to ``PATCH
is_public: true to a filter containing a secure variable will receive a
400 response.
The expression attribute must contain a valid Crunch filter
expression.
The team attribute will point to the team this filter is shared
with, in case it isn’t shared with any teams, it will default to
null.
See expressions in the Object Reference for more details.
Views 🔗
Applied filter 🔗
/datasets/{id}/filters/{id}/applied/
GET this resource to return a Shoji View containing the requested filter applied to the dataset. An applied view will return information on whether it was amended (modified in order to be applied) and information about why it was amended.
{
"element": "shoji:view",
"self": "https://app.crunch.io/api/datasets/ac64ef/filters/1442ea/applied/",
"description": "Detail information of one applied filter",
"value": {
"amended": true,
"application": {
"6JHjTBC": {
"alias": "variable_alias_1",
"issue": "MISSING",
"id": "6JHjTBC"
},
"KAve4tqo": {
"alias": "variable_alias_2",
"issue": null,
"id": "KAve4tqo"
}
},
"id": "1442ea",
"name": "My filter",
"is_public": true,
"expression": {},
"last_update": "2015-12-31",
"creation_time": "2015-11-12T12:34:56",
"team": "https://app.crunch.io/api/teams/680abc/"
}
}
The amended attribute will be true if the filter expression
was modified from its original form.
The application attribute will contain the reasons why the filter
expression had to be modified in case it is amended. Each entry on the
application contains information about a different variable in the
expression.
| Issue value | Issue Description |
|---|---|
null |
Variable does not have any issue in order to be applied on the dataset. |
"MISSING" |
Variable is not present on the dataset anymore. |
"MISMATCHING_CATEGORIES" |
The categorical variable had categories when the filter was created that does not exist anymore. |
"INVALID_TYPE" |
The variable type has changed from the time the filter was created. |
User Applied filters 🔗
/datasets/{id}/filters/applied/
A Shoji order containing the filters applied by the current user. The web app uses this to maintain state; the value of this setting does not itself affect other queries.
{
"element": "shoji:order",
"self": "http://app.crunch.io/api/datasets/ac64ef/filters/applied/",
"graph": [
"http://app.crunch.io/api/datasets/ac64ef/filters/28ef72/",
"http://app.crunch.io/api/datasets/ac64ef/filters/0ac6e1/",
]
}
PUT the applied endpoint to change the which filters are applied for
other operations. The graph parameter indicates which filters are
applied. Successful PUT requests return 204 status.
Filter Order 🔗
GET /datasets/{id}/filters/order/
A Shoji order containing the persisted filter order.
{
"element": "shoji:order",
"self": "http://app.crunch.io/api/datasets/ac64ef/filters/order/",
"graph": [
"http://app.crunch.io/api/datasets/ac64ef/filters/28ef72/",
"http://app.crunch.io/api/datasets/ac64ef/filters/0ac6e1/",
]
}
PATCH the order to change the order of the filters. The graph parameter indicates the order. Private filters are not included in the order. Any filters that are missing are appended to the end of the order. Successful PATCH requests return 204 status.
Filtering endpoints 🔗
Some endpoints will support filtering, they will accept a filter GET
parameter that can be a JSON encoded object that can contain either the
URL of a filter (available through the Filters catalog) or a filter
expression or a filter URL.
To filter using a filter URL using JSON pass in an object as the
filter parameter:
{
"filter": "http://app.crunch.io/api/datasets/ac64ef/filters/28ef72/"
}
GET /datasets/id/summary/?filter=%7B%22filter%22%3A%22http%3A%2F%2Fapp.crunch.io%2Fapi%2Fdatasets%2Fac64ef%2Ffilters%2F28ef72%2F%22%7D HTTP/1.1
It is also possible to send straight filter URLs without a JSON wrapping:
GET /datasets/id/summary/?filter=http%3A%2F%2Fapp.crunch.io%2Fapi%2Fdatasets%2Fac64ef%2Ffilters%2F28ef72%2F HTTP/1.1
Or multiple filters that will be ANDed together
GET /datasets/id/summary/?filter=http%3A%2F%2Fapp.crunch.io%2Fapi%2Fdatasets%2Fac64ef%2Ffilters%2F28ef72%2F&filter=http%3A%2F%2Fapp.crunch.io%2Fapi%2Fdatasets%2Fac64ef%2Ffilters%2F28ef72%2F HTTP/1.1
To filter using a filter expression, pass a Crunch filter expression as
the filter parameter, like:
{
"function": "==",
"args": [
{"variable": "http://app.crunch.io/api/datasets/ac64ef/variables/aae3c2/"},
{"value": 1}
]
}
GET /datasets/id/summary/?filter=%7B%22function%22%3A%22%3D%3D%22%2C%22args%22%3A%5B%7B%22variable%22%3A%22http%3A%2F%2Fapp.crunch.io%2Fapi%2Fdatasets%2Fac64ef%2Fvariables%2Faae3c2%2F%22%7D%2C%7B%22value%22%3A1%7D%5D%7D HTTP/1.1
Filter expressions can be combined with filter URLs to make reference to other filters, like so:
{
"function": "and",
"args": [
{
"filter": "http://app.crunch.io/api/datasets/ac64ef/filters/28ef72/"
},
{
"function": "==",
"args": [
{"variable": "http://app.crunch.io/api/datasets/ac64ef/variables/aae3c2/"},
{"value": 1}
]
}
]
}