Create a Parameterized Notebook

Parameterization is the ability to execute the same notebook with different parameters.

This article shows you how to create and run a parameterized notebook in Azure Data Studio using the python kernel.

Prerequisites

Install and set up Papermill in Azure Data Studio

The steps in this section all run within an Azure Data Studio notebook.

  1. Create a new notebook and change the Kernel to Python 3.

    New Notebook

  2. You may be prompted to upgrade your Python packages when your packages need updating.

    Yes

  3. Install Papermill:

    import sys
    !{sys.executable} -m pip install papermill --no-cache-dir --upgrade
    

    Verify it's installed:

    import sys
    !{sys.executable} -m pip list
    

    List

  4. You can test if papermill is loaded properly by checking the version of papermill.

    import papermill
    papermill
    

    Validation

Set up a parameterized notebook

  1. Verify the Kernel is set to Python3.

    Kernel change

  2. Create a New Code Cell and Tag as Parameters Cell.

    x = 2.0
    y = 5.0
    

    Parameter Cell Notebook

  3. Add other cells to test different parameters.

    addition = x + y
    multiply = x * y
    
    print("Addition: " + str(addition))
    print("Multiplication: " + str(multiply))
    

    Cells in Example Input Notebook: Additional Input Notebook Cells

  4. Save notebook as Input.ipynb. Save Notebook

How to execute Papermill notebook

Papermill can be executed two ways:

  • Command Line Interface (CLI)
  • Python API

Parameterized CLI execution

To execute a notebook using the CLI, enter the papermill command in the terminal with the input notebook, location for output notebook, and options.

Note

Papermill Command Line Interface Documentation can be found here.

  1. Execute Input Notebook with new parameters.

    papermill Input.ipynb Output.ipynb -p x 10 -p y 20
    

    This will execute the Input Notebook with new values for parameters x and y.

  2. After Execution view new Output Parameterized Notebook. You can note that there's a new cell labeled # Injected-Parameters containing the new parameter values passed in via CLI.

    Output Notebook

Parameterized Python API execution

Note

Papermill Python API Documentation can be found here.

  1. Create a new notebook and change the Kernel to Python 3. New Notebook

  2. Add a new code cell and use papermill to use the execute method.

    import papermill as pm
    
    pm.execute_notebook(
    '/Users/vasubhog/GitProjects/AzureDataStudio-Notebooks/Demo_Parameterization/Input.ipynb',
    '/Users/vasubhog/GitProjects/AzureDataStudio-Notebooks/Demo_Parameterization/Output.ipynb',
    parameters = dict(x = 10, y = 20)
    )
    

    Papermill Python API Execution

  3. After Execution view new Output Parameterization Notebook.

    You can note that there's a new cell labeled # Injected-Parameters containing the new parameter values passed in via CLI.

    Output Notebook

Next steps

Learn more about notebooks and Parameterization: