NEXUS – Synapse Notebook Command Center for VS Code

Run and manage Azure Synapse Spark notebooks directly from VS Code. NEXUS lets you browse, edit, execute, publish, and monitor Synapse notebooks without opening Synapse Studio.

Great for Synapse data engineers and analytics teams who live in notebooks.

At a Glance

Imagine a Synapse control center directly inside VS Code:

• Left sidebar: A dedicated NEXUS activity bar with three focused views — Workspaces, Notebooks, and Active Sessions — so you can see where you are, what you’re editing, and what’s running at a glance.
• Main editor: Native .ipynb notebooks backed by your Synapse workspace, with run buttons, cell status, and rich outputs just like you’d expect from a notebook-first experience.
• Status bar: A subtle cache indicator and workspace context so you always know which environment you’re connected to and whether NEXUS is serving results from cache or from Synapse.

In practice, this feels like having Synapse Studio’s notebook surface embedded into your day‑to‑day editor, but streamlined for keyboard‑driven, developer workflows.

Quick Start

What You Can Do

Multi-Workspace Management

• Keep multiple Synapse workspaces in the Workspaces view.
• Click to switch workspace; notebooks and sessions reload automatically.
• Each workspace entry keeps a last connected timestamp plus cache badge (⭐ active, ✅ fully cached, ☁ cache-needed) so you know what’s safe to open offline.
• Right-click to delete a workspace entry and clear its cached notebooks/configs in a single action.
• Export / import workspace settings (or export the entire list at once) and share JSON configs with your team.

Notebook Management

Think of the Notebooks view as a remote file explorer for Synapse notebooks:

• Browse a folder-aware tree of Synapse notebooks that mirrors what you see in Synapse Studio, including nested folders and shared libraries.
• Use search to instantly filter by notebook name or folder, which scales smoothly even when your workspace has thousands of items.
• Create local draft notebooks that live side‑by‑side with workspace notebooks, perfect for experiments and in‑progress work before you publish to the team.
• When you’re ready, use the Publish Notebook action to compare local vs workspace content, review the diff, and push the updated version back to Synapse.
• Right-click any notebook to clone it for experimentation or delete drafts/published copies as needed.
• At any time, you can refresh a single notebook if you know it changed, or all notebooks to resync the entire tree with your Synapse workspace.

Spark Sessions & Execution

Behind every notebook, NEXUS gives you a clear window into Spark sessions instead of treating them like a black box:

• Each notebook can use its own dedicated Spark session, created on first run and reused for subsequent cells so you get fast feedback loops.
• The Session Settings panel acts like a configuration sheet for the notebook: choose the Spark pool, executor size, executor count, idle timeout, and any advanced Spark configuration before you run.
• Set a session timeout (5‑60 minutes, default 30) so idle sessions auto-stop before they consume extra Spark capacity.
• The Active Sessions view surfaces all of your running Spark sessions in one place, with state, pool, and notebook information so you can see what’s consuming resources.
• From either the notebook toolbar or the Active Sessions view, you can stop a single session or all sessions in a couple of clicks.
• Long‑running or stuck cells respect cancellation signals, so you can cancel work quickly instead of waiting minutes for timeouts.
  • Need to fan out compute? Use the Run Parallel button on any code cell to bypass the sequential queue and fire it immediately (up to five parallel cells per notebook session).

Magic Commands & Interactive Output

Magic commands:

# Run another notebook (nested up to 10 levels, circular-safe)
%run "shared/data_processing"

# SQL cell
%%sql
SELECT TOP 100 * FROM database.table

# Explicit PySpark cell
%%pyspark


# Markdown cell
%%md
# My Analysis
This notebook analyzes customer behavior.

Interactive tables with display(df):

When you call display(df), NEXUS turns your DataFrame into a mini interactive data app inside the notebook:

• Click column headers to sort ascending or descending and quickly surface outliers or top‑N values.
• Add column filters to narrow down rows by value, ranges, or patterns without writing extra SQL or DataFrame code.
• Resize the results pane to focus on the table when you are exploring data, then collapse it to reclaim vertical space for code.
• Work comfortably with large result sets thanks to pagination controls that let you move through pages of data instead of overloading the notebook output.

Views & Commands

Tree Views

Common Commands

Day-to-Day Workflow

1. One-Time Setup

1. Install Azure CLI (if using CLI auth):

   • Download from aka.ms/install-azure-cli
   • Run az login in a terminal.

2. Configure your first workspace:

   • Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
   • Run Configure Workspace.
   • Enter:
     • Azure Subscription ID
     • Resource Group

• Synapse Workspace name
• NEXUS loads notebooks and configurations and warms up cache.

2. Working with Notebooks

• Open the Notebooks view from the NEXUS icon.
• Use the search box to filter.
• Select a notebook to open it as .ipynb in VS Code.
• Use the Run button on cells or the notebook to execute.

For new work:

• Click the + button in Notebooks to create a draft.
• Edit locally as you would any notebook.
• When ready, use Publish Notebook to push it to Synapse.

3. Managing Spark Sessions

• Use Session Settings (⚙️ in the notebook toolbar) to pick:
  • Spark pool
  • Executor size (Small–XXLarge)
  • Executor count (validated against pool capacity)
  • Optional Spark configuration
  • Session timeout in minutes (5–60, default 30) for automatic idle cleanup
• NEXUS stops and recreates sessions when needed to apply new settings.
• Check the Active Sessions view to see all running sessions and stop them as needed.

4. Multi-Workspace Workflow

• Add each workspace once in the Workspaces view.
• Click a workspace’s switch icon to jump between environments.
• Export workspace settings to JSON and share with teammates; they can import to get the same list.

5. Cache & Performance

• NEXUS caches data under %TEMP%/nexus/<workspace>/ (notebooks, configs, workspace info).
• If you see a cache indicator, click Refresh Notebooks or Refresh Configuration to sync with Synapse.
• Prefer a custom cache location (network drive, SSD, encrypted folder)? Set the VS Code setting nexus.cacheFolder to any directory and NEXUS will place its /nexus/<workspace>/ tree there.
• Cache speeds up startup and reduces API calls; you can always force a refresh.

Requirements

Troubleshooting & Tips

Common Issues

Support

• Leave a review or question directly on the extension page in the VS Code Marketplace.
• Optionally, use Help → Report Issue in VS Code or file an issue in the extension repository with VS Code + extension versions, Synapse workspace region, steps to reproduce, and any relevant error messages.

FAQ

Does this replace Synapse Studio?
No. NEXUS is meant to complement Synapse Studio by giving you a fast, code-first notebook experience in VS Code. You still use Synapse Studio for workspace admin, pipelines, and other UX.

Which languages are supported?
The extension works with Spark notebooks that use PySpark, Scala, or Spark SQL, and supports the standard Synapse-style magic commands (%run, %%sql, %%pyspark, %%md).

Where does NEXUS store cache data?
Under %TEMP%/nexus/<workspace>/ on your machine (notebooks, configs, workspace info). You can always force a refresh from Synapse if needed.

Will it work with large workspaces?
Yes. NEXUS uses caching, search, and pagination and has been tested with 1000+ notebooks.

Happy building with NEXUS! 🚀