Notebooks And Promotion

Explore logic in notebooks and promote durable outputs into managed models.

Use notebooks when you need an exploratory surface that can still graduate into shared production assets.

Inputs

a notebook with executable SQL cells
an agreed owner and purpose
a target project and model name for promotion

Flow

create a notebook and capture the exploratory logic
mark the output cell or publish target you want to preserve
run the notebook and confirm the output shape
promote the notebook output into a model
move ongoing changes into the durable model workflow

Promotion Flow

Git-Backed Notebook Sync

Use Git sync when you want notebooks to live as reviewed declarative files instead of only inside the UI.

Expected Repo Layout

set the Git repo record path to the declarative project root
place notebook documents under notebooks/*.yaml
use the declarative Notebook kind as the source format

Example:

TEXT

analytics/
  notebooks/
    sales.yaml
    margin-review.yaml

Sync Behavior

register a Git repo and branch with the notebooks integrations API
call sync to clone the branch and load declarative notebook files from <path>/notebooks
create or update local notebooks using the declarative notebook spec
remove previously linked notebooks when their source YAML is deleted from Git
carry forward notebook publish metadata so declared model promotion targets stay attached

Git is the source of truth for linked notebooks. A later sync overwrites linked notebook structure from Git, including cell order, roles, test config, visuals, and publish metadata.

Git Sync Flow

Verification

the published model retains the intended SQL logic
notebook exploration is no longer the only place the business logic lives
downstream dependencies point at the model, not a transient session
linked notebooks match the declarative files in Git after each sync
removing a linked notebook file from Git removes that linked notebook locally on the next sync