notebook-development.mdx

title	description	published
Notebook Development	Use Chalk in your notebook of choice.	true

Installation

Dependencies

Install Chalk in your notebook environment by running the following command in a cell:

!pip install chalkpy[all]

Authentication

To use Chalk in a notebook, we will need to generate a client ID and secret key pair.

In the Chalk Dashboard, under Settings > Access Tokens, generate a client ID and secret key pair by clicking on New Token and selecting all necessary permissions.

We will need the client ID and client secret we generated to initialize a Chalk client in our notebook.

---

Environment Setup

You can use the ChalkClient from any Jupyter notebook environment.

Local

If you are working with a local notebook, Chalk will pick up your credentials generated from running chalkpy login in your terminal.

All you need to do is initialize the client:

from chalk.client import ChalkClient

client = ChalkClient()

Deepnote

On Deepnote, you can set environment variables by going to the integrations tab and clicking on the "Environment Variables" button.

Set the CHALK_CLIENT_ID and CHALK_CLIENT_SECRET variables to the values you generated in the previous step. You can then initialize Chalk by running the following code in a cell:

import os
from chalk import ChalkClient

client = ChalkClient()

Hex

On Hex, you can store the client ID and secret key using secrets

Select Python 3.10 as the image under Environment > Compute Profile.

The Chalk client can then be initialized referencing the variables directly

from chalk import ChalkClient

client = ChalkClient()

Creating a branch

To start using Chalk in a notebook, we will need to create a branch deployment. Branch deployments are isolated environments that can be used to test features and resolvers before deploying them to production.

Working in a branch makes it seamless to iterate on features and resolvers in notebooks. Any time we execute a cell in our notebook with feature or resolver definitions, Chalk will automatically update our branch deployment with the latest changes.

Once you've got your client setup, you can create a branch calling create_branch. Setting switch=True will point your client to the newly created branch.

client.create_branch("my-branch", switch=True)

Cell Magics

Chalk provides a set of IPython magics to improve the experience of defining resolvers in notebooks.

%%resolver

You can define a SQL resolver in a notebook cell using the %%resolver magic. The magic will parse the cell contents and upload your resolver to your current working branch.

%%resolver needs to be followed by a resolver name, e.g. root_authorization_resolver as shown below.

Refer to the section on SQL Resolvers to learn more about how to define resolvers.

%%resolver root_authorization_resolver
-- resolves: Authorization
-- source: snowflake
SELECT
    id,
    amount_in_cents,
    card_id,
    merchant_id,
    created_at as authorized_at
FROM authorizations

Chalk lines up the names of your target SQL columns with the names of your features. In this case, we have an Authorization feature class that contains a features called authorized_at. However, our Snowflake table has a column called created_at that we want to use to populate the authorized_at feature. So, we use the as keyword to rename the column in our resolver.

Inline Syntax

In notebooks, you can define features inline using the syntax shown below.

Consider the following feature class definition for RocketEngine

from chalk.features import features

@features
class RocketEngine:
    id: int
    mass: float
    volume: float
    thrust: float

If we wanted to define a feature inline in a notebook cell, we could do so using the underscore syntax below:

RocketEngine.density: float = _.mass / _.volume