Skip to main content
Malloy notebooks (.malloynb files) combine semantic modeling with narrative documentation. Create data stories, analysis walkthroughs, and simple dashboards—all versioned and published alongside your models.

​
What Are Malloy Notebooks?

Malloy notebooks blend markdown text, Malloy queries, and visualizations into interactive documents. Unlike traditional notebooks, they’re built on your semantic layer, ensuring consistent, governed definitions across all analysis.

​
Use Cases

  • Data storytelling: Create narrative reports with live queries that update as data changes
  • Standard analysis: Document common analyses with exact queries and business context
  • Simple dashboards: Build linear KPI dashboards for key metrics
  • Package documentation: Add README.malloynb to provide an interactive package overview

​
Creating Notebooks

​
In VS Code

  1. Create a file with .malloynb extension
  2. Add markdown blocks for descriptions or headings
  3. Add code blocks for Malloy queries
  4. Run the notebook cell-by-cell or click “Run All” to see results for the entire notebook

​
Basic Example

Here is a screenshot of a markdown cell (Business Overview…) and code cell (run: order_items...) in a malloynb notebook in VS Code. Malloy Notebook Example

​
Publishing Notebooks

Notebooks are published with your package - if you include notebooks in your package directory, then they’ll be versioned with your models and viewable in the admin portal.

​
README.malloynb

Create a README.malloynb in your package root for special functionality:
  • Automatically renders on the package landing page
  • Provides package overview with live examples
  • Serves as onboarding guide for new users

​
Next Steps

Embedded Data

Include CSV and Parquet files in packages

Publishing Models

Learn how to publish packages with notebooks
⌘I