Rotor
Rotor is a Visual Studio Code extension for analytical Jupyter notebooks that use SQL cells. It adds a notebook-focused workflow for naming paragraphs, assigning SQL connections, navigating notebook structure, formatting SQL, linting SQL, and viewing query results without leaving the notebook.
Features
- A context-aware Rotor Outline: notebook paragraphs for Jupyter and the full
report structure for Motor
report.md files.
- Paragraph titles stored in notebook metadata and shown as CodeLens entries.
- SQL connection labels per paragraph, with configurable aliases and dialect mapping.
- One-click execution for the active cell or a selected paragraph.
- Query Result webview for mirrored notebook output.
- SQL formatting through SQLFluff, scoped to detected SQL cell bodies.
- SQL diagnostics through SQLFluff with configurable severity and ignored rules.
- OpenMetadata-aware SQL completion for configured metadata servers.
- Setup command that inserts a notebook bootstrap cell for required kernel packages.
- Native VS Code Outline navigation for Motor
report.md files, including nested
layouts, data sources, parameter types, SQL view/query kinds, component
types, and each component's query datasource.
- Go to Definition for Motor report references through
F12, Peek Definition,
or Cmd+Click on macOS / Ctrl+Click on Windows and Linux.
- Find All References for Motor declarations and references through
Shift+F12
or the editor context menu.
For a Motor report, use either the standard VS Code Outline view or the
dedicated Rotor: Outline panel. The Rotor panel switches automatically:
Jupyter notebooks show paragraphs, while recognized Motor reports show data
sources, parameters, SQL, templates, and nested layout. Clicking an entry jumps
to its declaration. The standard Outline and Go to Symbol in Editor
(Ctrl+Shift+O) support both Markdown and Evidence Markdown (emd). Keep the
standard Outline sorting set to Position to preserve source order.
Motor definition navigation works in both Markdown and Evidence Markdown
(emd). Rotor links component query, template, and params attributes;
parameter options.source; dimension default choices; SQL parameter helpers
such as in_filter, between_filter, and dimension; and relations after SQL
FROM or JOIN. Relation lookup understands report data sources, named SQL
blocks, and scoped CTEs, including chained and nested CTEs. Local CTE names take
priority while they are in scope. Find All References searches the current
report and can be invoked from either a declaration or one of its references.
Requirements
Rotor activates for VS Code Jupyter notebooks. Install and configure the VS Code Jupyter extension separately.
SQL formatting and linting require sqlfluff to be available on your PATH, or configured through rotor.sqlLint.sqlfluffPath.
OpenMetadata completion requires a reachable OpenMetadata server and an API key configured through the Rotor command palette command.
Commands
| Command |
Command ID |
Description |
| Rename Paragraph |
rotor.renameParagraph |
Rename the active or selected notebook paragraph. |
| Set Paragraph Connection |
rotor.setParagraphConnection |
Assign a configured SQL connection alias to a paragraph. |
| Run Cell in Place |
rotor.runCellInPlace |
Execute the active notebook cell and keep output in notebook context. |
| Run Paragraph |
rotor.runParagraph |
Execute a selected paragraph from the Rotor panel. |
| Reveal Paragraph |
rotor.revealParagraph |
Jump from the Rotor panel to the paragraph in the notebook. |
| Reveal Paragraph Output |
rotor.revealParagraphOutput |
Jump to a paragraph and focus the Query Result view. |
| Go to Paragraph |
rotor.goToParagraph |
Open a quick pick for notebook paragraphs and navigate to the selected item. |
| Open Query Result |
rotor.openQueryResult |
Open and refresh the Rotor Query Result view. |
| Clear Query Result |
rotor.clearQueryResult |
Clear the mirrored query result output. |
| Format SQL Cell |
rotor.formatSqlCell |
Format the active or selected SQL paragraph with SQLFluff. |
| Format All SQL Cells |
rotor.formatAllSqlCells |
Format all detected SQL paragraphs in the active notebook. |
| Setup Kernel Packages |
rotor.setupKernelPackages |
Insert or run the Rotor kernel setup cell in the active Jupyter notebook. |
| Configure OpenMetadata |
rotor.configureOpenMetadata |
Store the OpenMetadata API key used by metadata-aware completion. |
| Refresh OpenMetadata Cache |
rotor.refreshOpenMetadataCache |
Clear cached OpenMetadata responses. |
| Show Output |
rotor.showOutput |
Show the Rotor output channel. |
| Toggle SQL Lint Diagnostics |
rotor.toggleSqlLintDiagnostics |
Enable or disable SQL lint diagnostics and error highlighting. |
| Debug SQL Lint Active Cell |
rotor.debugSqlLintActiveCell |
Print SQL lint debug details for the active cell to the Rotor output channel. |
Settings
| Setting |
Default |
Description |
rotor.cellLanguages |
{ "%": "sql" } |
Language IDs to apply to notebook code cells by first magic-line prefix. |
rotor.connections |
ClickHouse, Greenplum, Trino aliases |
SQL connection aliases used for display and metadata. |
rotor.dialectByConnection |
ClickHouse, Greenplum, Trino dialects |
SQLFluff dialect names keyed by Rotor connection alias. |
rotor.sqlLint.enabled |
true |
Enable SQLFluff and Rotor SQL diagnostics for Rotor SQL notebook cells. |
rotor.sqlLint.sqlfluffPath |
sqlfluff |
Path to the SQLFluff executable. |
rotor.sqlLint.ignoreLocalConfig |
true |
Run SQLFluff diagnostics without local project config files. |
rotor.sqlLint.debug |
false |
Write SQLFluff diagnostic pipeline details to the Rotor output channel. |
rotor.sqlLint.errorCodes |
PRS, LXR, TMP |
SQLFluff codes or prefixes shown as errors. |
rotor.sqlLint.criticalCodesByDialect |
common parser and semantic rules |
Dialect-specific codes or prefixes shown as execution-risk errors. |
rotor.sqlLint.ignoredCodes |
LT13 |
SQLFluff codes or prefixes Rotor should never show. |
rotor.sqlLint.otherSeverity |
off |
Severity for non-ignored, non-critical SQLFluff violations. |
rotor.sqlFormat.ignoreLocalConfig |
true |
Run SQLFluff format without local project config files. |
rotor.openMetadata.baseUrl |
https://metadata.ecom.tech |
OpenMetadata server URL used for SQL metadata features. |
rotor.outputMode |
mirror-and-collapse |
Controls how notebook output is mirrored into Query Result. |
