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/",
    "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.

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}
            ]
        }
    ]
}