AutomaticFilters: Simple filtering — Recipe 0.14.0 documentation

# AutomaticFilters: Simple filtering

The AutomaticFilters extension provides a simpler approach to building filters using Ingredient.build_filter.

class `recipe.` `AutomaticFilters`(*args, **kwargs)

  Automatic generation and addition of Filters to a recipe.

  Automatic filters take a dictionary of keys and values. For each key in the dictionary, if the key is the id of a `Dimension` on the shelf, a filter will be added to the recipe containing the values.

  `apply_automatic_filters`(value)

    Toggles whether automatic filters are applied to a recipe. The following will disable automatic filters for this recipe:

        recipe.apply_automatic_filters(False)

  `automatic_filters`(value)

    Sets a dictionary of automatic filters to apply to this recipe. If your recipe uses a shelf that has dimensions ‘state’ and ‘gender’ you could filter the data to Men in California and New Hampshire with:

        shelf = Shelf({
            'state': Dimension(Census.state),
            'gender': Dimension(Census.gender),
            'population': Metric(func.sum(Census.population)),
        })
        recipe = Recipe(shelf=shelf)
        recipe.dimensions('state').metrics('population').automatic_filters({
            'state': ['California', 'New Hampshire'],
            'gender': 'M'
        })

    Automatic filter keys can optionally include an `operator`.

    List operators

    If the value provided in the automatic_filter dictionary is a list, the following operators are available. The default operator is `in`:

        in (default)
        notin
        quickselect (applies multiple conditions matching the
          named quickselect, quickselects are ORed together)
        between (requires a list of two items)

    Scalar operators

    If the value provided in the automatic_filter dictionary is a scalar (a string, integer, or number), the following operators are available. The default operator is `eq`:

        eq (equal) (the default)
        ne (not equal)
        lt (less than)
        lte (less than or equal)
        gt (greater than)
        gte (greater than or equal)
        like (SQL LIKE)
        ilike (Case insensitive LIKE)
        quickselect (applies the condition matching the named quickselect)

    An example using operators

    Here’s an example that filters to states that start with the letters A-C:

        shelf = Shelf({
            'state': Dimension(Census.state),
            'gender': Dimension(Census.gender),
            'population': Metric(func.sum(Census.population)),
        })
        recipe = Recipe(shelf=shelf)
        recipe.dimensions('state').metrics('population').automatic_filters({
            'state__lt': 'D'
        })

  `exclude_automatic_filter_keys`(*keys)

    A “blacklist” of automatic filter keys to exclude. The following will cause `'state'` to be ignored if it is present in the `automatic_filters` dictionary:

        recipe.exclude_automatic_filter_keys('state')

  `include_automatic_filter_keys`(*keys)

    A “whitelist” of automatic filter keys to use. The following will only use `'state'` for automatic filters regardless of what is provided in the automatic_filters dictionary:

        recipe.include_automatic_filter_keys('state')

The AutomaticFilters extension.