Quickstart — Recipe 0.1.0 documentation

# Quickstart

This page gives a good introduction in how to get started with Recipe. This assumes you already have Recipe installed. If you do not, head over to Installing Recipe.

First, make sure that:

- Recipe is installed
- Recipe is up-to-date

Let’s gets started with some simple examples.

## Creating a Shelf

A `Shelf` is a place to store SQL fragments. In recipe these are called `Ingredients`. Ingredients may contain columns that should be part of the `SELECT` portion of a query, filters that are part of the `WHERE` clause of a query, group_bys that contribute to a query’s `GROUP BY` and havings which add `HAVING` limits ot a query.

It’s a safe bet that you won’t have to construct an Ingredient with all these parts directly because Recipe contains convenience classes that help you build the most common SQL fragments. The two most common Ingredient subclasses are `Dimensions` which supply both a column and a grouping on that column and `Metrics` which supply a column aggregation.

Shelf acts like a dictionary. The keys are strings and the values are Ingredients. The keys are a shortcut name for the ingredient. Here’s an example.

    from recipe import *

    shelf = Shelf({
        'age': WtdAvgMetric(Census.age, Census.pop2000),
        'population': Metric(func.sum(Census.pop2000)),
        'state': Dimension(Census.state)
    })

This is a shelf with two metrics (a weighted average of age, and the sum of population) and a dimension which lets you group on US State names.

## Using the Shelf to build a Recipe

Now that you have the shelf, you can build a recipe. Given the shelf we just created, we can create a recipe that gives us the average age for each state in the United States.

    recipe = Recipe(shelf=shelf, session=Session())\
        .dimensions('state')\
        .metrics('age')
    print(recipe.to_sql())
    print(recipe.dataset.csv)

The output will be:

    SELECT census.state AS state,
       CAST(sum(census.age * census.pop2000) AS FLOAT) / (coalesce(CAST(sum(census.pop2000) AS FLOAT), 0.0) + 1e-09) AS age,
       sum(census.pop2000) AS population
    FROM census
    GROUP BY census.state

    state,age,state_id
    Alabama,36.27787892421841,Alabama
    Alaska,31.947384766048568,Alaska
    Arizona,35.37065466080318,Arizona
    Arkansas,36.63745110262778,Arkansas
    ...

Recipes can be built interactively by building on previous recipes. Consider the recipe we just created. We can add a filter to it:

    recipe = recipe.filters(Census.state.like('V%'))
    print(recipe.to_sql())
    print(recipe.dataset.csv)

The output will be:

    SELECT census.state AS state,
           CAST(sum(census.age * census.pop2000) AS FLOAT) / (coalesce(CAST(sum(census.pop2000) AS FLOAT), 0.0) + 1e-09) AS age
    FROM census
    WHERE census.state LIKE 'V%'
    GROUP BY census.state
    state,age,state_id
    Vermont,37.0597968760254,Vermont
    Virginia,35.83989223366432,Virginia

Basic parts of a recipe

dimension, metrics, order_by, having

Note that a recipe contains data from a single table.`

## Viewing the data from your Recipe

recipe.dataset.xxxx iterating over recipe.all dimensions have a separate _id property

# More about Ingredients

## Types of Ingredients

List of ingredients

### Dimension

Dimensions are groupings that exist in your data.

    # A simple dimension
    self.shelf['state'] = Dimension(Census.state)

### IdValueDimension

IdValueDimensions support separate properties for ids and values. Consider a table of employees with an `employee_id` and a `full_name`. If you had two employees with the same name you need to be able to distinguish between them.

    # Support an id and a label
    shelf = Shelf({
      'employee': IdValueDimension(Employee.id, Employee.full_name)
    })

The id is accessible as `employee_id` in each row and their full name is available as `employee`.

### LookupDimension

Lookup dimension maps values in your data to descriptive names. The `_id` property of your dimension contains the original value.

    # Convert M/F into Male/Female
    shelf = Shelf({
        'gender': LookupDimension(Census.sex, {'M': 'Male',
                    'F': 'Female'}, default='Unknown')
    })

If you use the gender dimension, there will be a `gender_id` in each row that will be “M” or “F” and a `gender` in each row that will be “Male” or “Female”.

### Metric

### DivideMetric

### WtdAvgMetric

### SumIfMetric

### CountIfMetric

### Filter

### Having

## Formatters

## Building filters

Ingredient.build_filter

## Storing extra attributes in meta

# Using Extensions

This part of the documentation services to give you an idea that are otherwise hard to extract from the API Documentation

And now for something completely different.

What are extensions for?

## Automatic Filtering

AutomaticFilter

## Summarizing over Dimensions

SummarizeOverRecipe

## Merging multiple tables

BlendRecipe

## Adding comparison data

CompareRecipe

## Anonymizing data

Anonymize

# Advanced Features

## Database connections

## Caching

## Running recipes in parallel with RecipePool

Now, go check out the API Documentation or begin Recipe Development.