console: add MZ Academy tutorial menu to the SQL Shell#36513
Draft
bosconi wants to merge 3 commits into
Draft
Conversation
Adds a design doc describing how to convert the single Quickstart toggle in the SQL Shell header into an MZ Academy pull-down menu hosting multiple tutorials.
Adds a chevron Menu next to the existing tutorial toggle in the SQL Shell header. The menu lets the user choose between the Quickstart and a new MZ Academy: intro to Materialize tutorial. The choice persists in localStorage; the open/close toggle and step state continue to live on the existing shellStateAtom. Refactor: - Extract Runnable, TextContainer, RunnableContainer, StepLayout, and the step-data type into tutorialUtils.tsx. - Move the existing quickstart step array into quickstartSteps.tsx. - Add academySteps.tsx with 13 steps covering clusters, views, materialized views, indexes, index reuse, idiomatic Materialize SQL patterns (top-K, aggregate rewrites), temporal filters with mz_now(), filter-pushdown vs materialize-then-filter, and a pointer to the built-in /api/mcp/developer MCP server. The SQL targets an e-commerce schema fed by a PostgreSQL CDC source plus a Kafka clickstream source. - Tutorial.tsx becomes a thin harness that dispatches to the right step array based on shellState.activeTutorial. Behavior: when "Quickstart" is the active tutorial the panel is byte-for- byte identical to today.
- shell.test.ts: covers setStoredActiveTutorial / SHELL_ACTIVE_TUTORIAL localStorage round-trip. - Tutorial.test.tsx: renders the Tutorial component with each activeTutorial value and asserts the right header label and intro content appears.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an MZ Academy pull-down menu next to the SQL Shell's tutorial toggle. The menu lets the user pick between multiple in-shell tutorials. This iteration adds two:
mz_now(), the filter-pushdown vs materialize-then-filter trade-off, and a pointer to the built-in/api/mcp/developerMCP server. The SQL targets an e-commerce schema replicated via a PostgreSQL CDC source plus a Kafka clickstream source.Generic-purpose. The framing is built around a learner working through Materialize, whether that's an individual at their own pace or a group running the material together.
The active tutorial is persisted in
localStorageso it survives reloads.UI
IconButtonnext to the toggle opens a ChakraMenulisting all tutorials. Selecting a tutorial sets it active, persists the choice, resets the step counter to 0, and opens the panel.How to try it
That produces
console/dist/. Two ways to view it against a running emulator:Option A —
docker cpinto a running emulator (fastest iteration). With a stockmaterialize/materialized:v26.22.0container running and exposing port 6874:nginx in the container serves the swapped files immediately — no restart needed.
Option B — local dev server. From
console/:CONSOLE_DEPLOYMENT_MODE=flexible-deployment DEV_SERVER_PROXY_PORT=6876 yarn start # Visit http://localhost:3000/Running the academy tutorial's SQL
The Quickstart tutorial works on a stock emulator out of the box (it creates its own load-generator source).
The Academy tutorial assumes you have:
users,products,orders,order_items,shopping_carts,shopping_cart_items,categories,featured_products.clickstreamtopic, plus aclickstreamview in Materialize that parses event JSON into columns (at minimumevent_typeandevent_time).source_cluster,transform_cluster,serving_cluster(each 100cc or so).If those aren't present, the academy tutorial's Runnables will surface "relation does not exist" / "cluster does not exist" errors from Materialize. The tutorial's step 2 ("Verify the environment") spells out what to check.
Test plan
yarn typecheck— clean.yarn lint src/platform/shell— clean.yarn vitest run src/platform/shell— all 74 tests pass (2 new tests added for the menu/dispatch + storage flow).Notes
console/src/platform/shell/and the design doc.console/doc/design/20260510_mz_academy_tutorial_menu.md.🤖 Generated with Claude Code