recipe¶
Recipe¶
-
class
recipe.
Ingredient
(**kwargs)[source]¶ Ingredients combine to make a SQLAlchemy query.
-
build_filter
(value, operator=None)[source]¶ Builds a filter based on a supplied value and optional operator. If no operator is supplied an
in
filter will be used for a list and aeq
filter if we get a scalar valueParameters: - value (object) – The value to use in the filter
- operator (str) – An operator to override the default interaction
-
cauldron_extras
¶ Yield extra tuples containing a field name and a callable that takes a row
-
expression
¶ An accessor for the sqlalchemy expression representing this Ingredient
-
make_column_suffixes
()[source]¶ Make sure we have the right column suffixes. These will be appended to id when generating the query.
-
order_by_columns
¶ Yield columns to be used in an order by using this ingredient
-
query_columns
¶ Yield labeled columns to be used as a select in a query
-
-
class
recipe.
Dimension
(expression, **kwargs)[source]¶ A Dimension is an Ingredient that adds columns and groups by those columns. Columns should be non-aggregate sqlalchemy expressions
The required expression supplies the dimension’s value role. Additional expressions can be provided in keyword arguments with keys that look like “{role}_expression”. The role is suffixed to the end of the SQL column name.
For instance, the following
- Dimension(Hospitals.name,
- latitude_expression=Hospitals.lat longitude_expression=Hospitals.lng, id=’hospital’)
would add columns named “hospital”, “hospital_latitude”, and “hospital_longitude” to the recipes results. All three of these expressions would be used as group bys.
The following additional keyword parameters are also supported:
Parameters: - lookup – dict A dictionary to translate values into
- lookup_default – A default to show if the value can’t be found in the
lookup dictionary.
-
cauldron_extras
¶ Yield extra tuples containing a field name and a callable that takes a row
-
id_prop
¶ The label of this dimensions id in the query columns
-
make_column_suffixes
()[source]¶ Make sure we have the right column suffixes. These will be appended to id when generating the query.
-
order_by_columns
¶ Yield columns to be used in an order by using this ingredient
-
class
recipe.
LookupDimension
(expression, lookup, **kwargs)[source]¶ DEPRECATED Returns the expression value looked up in a lookup dictionary
-
class
recipe.
DivideMetric
(numerator, denominator, **kwargs)[source]¶ A metric that divides a numerator by a denominator handling several possible error conditions
The default strategy is to add an small value to the denominator Passing ifzero allows you to give a different value if the denominator is zero.
-
class
recipe.
WtdAvgMetric
(expression, weight_expression, **kwargs)[source]¶ A metric that generates the weighted average of a metric by a weight.
-
class
recipe.
Filter
(expression, **kwargs)[source]¶ A simple filter created from a single expression.
-
expression
¶ An accessor for the sqlalchemy expression representing this Ingredient
-
-
class
recipe.
Having
(expression, **kwargs)[source]¶ A Having that limits results based on an aggregate boolean clause
-
expression
¶ An accessor for the sqlalchemy expression representing this Ingredient
-
-
class
recipe.
Recipe
(shelf=None, metrics=None, dimensions=None, filters=None, order_by=None, session=None, extension_classes=(), dynamic_extensions=None)[source]¶ A tool for getting data.
Parameters: - shelf (Shelf) – A shelf to use for shared metrics
- metrics (
list
ofstr
) – A list of metrics to use from the shelf. These can also beMetric
objects. - dimensions (
list
ofstr
) – A list of dimensions to use from the shelf. These can also beDimension
objects. - filters (
list
ofstr
) – A list of filters to use from the shelf. These can also beFilter
objects. - order_by (
list
ofstr
) – A list of dimension or metric keys from the shelf to use for ordering. If prefixed by ‘-‘ the ordering will be descending. - session (
Session
) - extension_classes (
list
ofRecipeExtension
) – Extensions to apply to this recipe.
Returns: A Recipe object.
-
dimensions
(*dimensions)[source]¶ Add a list of Dimension ingredients to the query. These can either be Dimension objects or strings representing dimensions on the shelf.
The Dimension expression will be added to the query’s select statement and to the group_by.
Parameters: dimensions (list) – Dimensions to add to the recipe. Dimensions can either be keys on the shelf
or Dimension objects
-
filters
(*filters)[source]¶ Add a list of Filter ingredients to the query. These can either be Filter objects or strings representing filters on the service’s shelf.
.filters()
are additive, calling .filters() more than once will add to the list of filters being used by the recipe.The Filter expression will be added to the query’s where clause
Parameters: filters (list) – Filters to add to the recipe. Filters can either be keys on the shelf
or Filter objects
-
classmethod
from_config
(shelf, obj, **kwargs)[source]¶ Construct a Recipe from a plain Python dictionary.
Most of the directives only support named ingredients, specified as strings, and looked up on the shelf. But filters can be specified as objects.
Additionally, each RecipeExtension can extract and handle data from the configuration.
-
limit
(limit)[source]¶ Limit the number of rows returned from the database.
Parameters: limit (int) – The number of rows to return in the recipe. 0 will return all rows.
-
metrics
(*metrics)[source]¶ Add a list of Metric ingredients to the query. These can either be Metric objects or strings representing metrics on the shelf.
The Metric expression will be added to the query’s select statement. The metric value is a property of each row of the result.
Parameters: metrics (list) – Metrics to add to the recipe. Metrics can either be keys on the shelf
or Metric objects
-
offset
(offset)[source]¶ Offset a number of rows before returning rows from the database.
Parameters: offset (int) – The number of rows to offset in the recipe. 0 will return from the first available row
-
order_by
(*order_bys)[source]¶ Add a list of ingredients to order by to the query. These can either be Dimension or Metric objects or strings representing order_bys on the shelf.
The Order_by expression will be added to the query’s order_by statement
Parameters: order_bys (list) – Order_bys to add to the recipe. Order_bys can either be keys on the shelf
or Dimension or Metric objects. If the key is prefixed by “-” the ordering will be descending.
-
query
()[source]¶ Generates a query using the ingredients supplied by the recipe.
Returns: A SQLAlchemy query
-
subquery
(name=None)[source]¶ The recipe’s query as a subquery suitable for use in joins or other queries.
-
class
recipe.
Shelf
(*args, **kwargs)[source]¶ Holds ingredients used by a recipe.
Can be initialized with no arguments, but also accepts: - a dictionary of ingredients as a positional argument - ingredients as keyword arguments
These keyword arguments have special meaning: :param select_from: The SQLALchemy-compatible object which will be queried
(usually a Table or ORM object).Parameters: - table – Unused, but stored on the Meta attribute.
- metadata – Unused, but stored on the Meta attribute.
-
dimension_ids
¶ Return the Dimensions on this shelf in the order in which they were used.
-
enchant
(list, cache_context=None)[source]¶ Add any calculated values to each row of a resultset generating a new namedtuple
Parameters: - list – a list of row results
- cache_context – optional extra context for caching
Returns: a list with ingredient.cauldron_extras added for all ingredients
-
filter_ids
¶ Return the Metrics on this shelf in the order in which they were used.
-
find
(obj, filter_to_class=<class 'recipe.ingredients.Ingredient'>, constructor=None)[source]¶ Find an Ingredient, optionally using the shelf.
Parameters: - obj – A string or Ingredient
- filter_to_class – The Ingredient subclass that obj must be an instance of
- constructor – An optional callable for building Ingredients from obj
Returns: An Ingredient of subclass filter_to_class
-
classmethod
from_config
(obj, selectable, ingredient_constructor=<function ingredient_from_validated_dict>, metadata=None)[source]¶ Create a shelf using a dict shelf definition.
Parameters: - obj – A Python dictionary describing a Shelf.
- selectable – A SQLAlchemy Table, a Recipe, a table name, or a SQLAlchemy join to select from.
- metadata – If selectable is passed as a table name, then in order to introspect its schema, we must have the SQLAlchemy MetaData object to associate it with.
Returns: A shelf that contains the ingredients defined in obj.
-
classmethod
from_validated_yaml
(yaml_str, selectable, **kwargs)[source]¶ Create a shelf using a yaml shelf definition.
Parameters: - yaml_str – A string containing yaml ingredient definitions.
- selectable – A SQLAlchemy Table, a Recipe, or a SQLAlchemy
join to select from. :return: A shelf that contains the ingredients defined in yaml_str.
-
classmethod
from_yaml
(yaml_str, selectable, **kwargs)[source]¶ Shim that calls from_validated_yaml.
This used to call a different implementation of yaml parsing
-
metric_ids
¶ Return the Metrics on this shelf in the order in which they were used.
-
recipe.
AutomaticShelf
(table)[source]¶ Given a SQLAlchemy Table, automatically generate a Shelf with metrics and dimensions based on its schema.
-
class
recipe.
Anonymize
(*args, **kwargs)[source]¶ Allows recipes to be anonymized by adding an anonymize property This flips the anonymize flag on all Ingredients used in the recipe.
Injects an ingredient.meta._anonymize boolean property on each used ingredient.
AnonymizeRecipe should occur last
-
class
recipe.
AutomaticFilters
(*args, **kwargs)[source]¶ 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.-
add_ingredients
()[source]¶ Add ingredients to the recipe
This method should be overridden by subclasses
-
apply_automatic_filters
(value)[source]¶ 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)[source]¶ 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 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)
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' })
-
-
class
recipe.
BlendRecipe
(*args, **kwargs)[source]¶ Add blend recipes, used for joining data from another table to a base table
Supply a second recipe with a different
from
Optionally supply join criteria, if no join criteria is provided join will be attempted using constraints. All ingredients from the blended recipe will be hoisted to the base recipe except for ingredients that are used for joins (they must be the same anyway).Supports blend (inner) and full_blend (outer) joins.
-
blend
(blend_recipe, join_base, join_blend)[source]¶ Blend a recipe into the base recipe. This performs an inner join of the blend_recipe to the base recipe’s SQL.
-
-
class
recipe.
CompareRecipe
(*args, **kwargs)[source]¶ Add compare recipes, used for presenting comparative context vis-a-vis a base recipe.
Supply a second recipe with the same
`from
. Metrics from the second recipe will be hoisted to the base recipe and suffixed with a string (the default is “_compare” Dimensions will be used to match the base recipe to the compare recipe. Ordering from the base recipe is maintained.
-
class
recipe.
RecipeExtension
(recipe)[source]¶ Recipe extensions plug into the recipe builder pattern and can modify the generated query.
recipe generates a query in the following way
(RECIPE) recipe checks if a query has been generated
(EXTENSIONS) all extension
add_ingredients
run to inject ingredients directly on the recipe(RECIPE) recipe runs gather_all_ingredients_into_cauldron to build a global lookup for ingredients
(RECIPE) recipe runs cauldron.brew_query_parts to gather sqlalchemy columns, group_bys and filters
(EXTENSIONS) all extension
modify_recipe_parts(recipeparts)
run to directly modify the collected sqlalchemy columns, group_bys or filters(RECIPE) recipe builds a preliminary query with columns
(EXTENSIONS) all extension
modify_prequery_parts(prequery_parts)
run to modify the query(RECIPE) recipe builds a full query with group_bys, order_bys, and filters.
(RECIPE) recipe tests that this query only uses a single from
(EXTENSIONS) all extension
modify_postquery_parts( postquery_parts)
run to modify the query(RECIPE) recipe applies limits and offsets on the query
(RECIPE) recipe caches completed query
When the recipe fetches data the results will be
enchanted
to add fields to the result.RecipeExtensions
can modify result rows withenchant_add_fields: Return a tuple of field names to add to a result row
enchant_row(row): Return a tuple of field values for each row in results.
-
add_ingredients
()[source]¶ Add ingredients to the recipe
This method should be overridden by subclasses
-
enchant_add_fields
()[source]¶ This method allows extensions to add fields to a result row. Return a tuple of the field names that are being added with this method
-
enchant_row
(row)[source]¶ This method adds the fields named in
enchant_add_fields
to each result row.
-
modify_postquery_parts
(postquery_parts)[source]¶ This method allows extensions to directly modify query, group_bys, filters, and order_bys generated from collected ingredients after a final query using columns has been created.
-