Overview

Ingredients are reusable fragments of SQL defined in SQLAlchemy or using configuration dictionaries. Ingredients contribute to a SQL query’s select, group by, where or having clauses. For convenience, we define Metric, Dimension, Filter, and Having classes which support common query patterns.

A Shelf is a container that holds named ingredients. Shelves can be defined with python code or using configuration dictionaries. Shelves defined with configuration can be bound to a SQLAlchemy selectable (which can be a subquery, another recipe, or a mapped database table).

Note

By convention, all the ingredients on a Shelf should reference the same SQLAlchemy selectable.

A Recipe uses a Shelf. The Recipe picks dimensions, metrics, filters, and havings from the shelf. Dimensions and Metrics can also be used to order results. While the Recipe can refer to items in the shelf by name, you can also supply raw Ingredient objects. Recipe uses a builder pattern to allow a recipe object to be modified.

A Recipe generates and runs a SQL query using SQLAlchemy. The query uses an Oven; an abstraction on top of a SQLAlchemy connection. The query results are “enchanted” which adds additional properties to each result row. This allows ingredients to format or transform values with python code.

Recipe results can optionally be cached with the recipe_caching support library.

Extensions

Extensions add to Recipe to change how SQL queries get built.

Recipe includes the following built-in extensions.

  • AutomaticFilter: Supports a configuration syntax for applying filters.

  • SummarizeOver: Supports summarizing over a dimension

  • Paginate: Supports paginating results

  • BlendRecipe: Allows data from different tables to be combined

  • CompareRecipe: Allows a secondary recipe against the same table to be combined.

  • Anonymize: Allows result data to be anonymized.