Notebook Development

​

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(
  client_id=CHALK_CLIENT_ID,
  client_secret=CHALK_CLIENT_SECRET
)

​

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