Azure Synapse migration, run by an agent fleet.

What the Documenter reads in Azure Synapse Analytics

A Synapse workspace looks like one product. It’s really a collaboration boundary wrapped around four distinct engines, and treating it as a single thing is the first mistake a migration makes. The Documenter (the agent that builds the knowledge base before any rebuild begins) reads each workload on its own terms, then follows the data where it crosses between them. The point of the assessment gate is to read the logic, not the labels: the distribution key behind a fast join, the %run that quietly shares a notebook’s variables, the view that turns raw lake files into a warehouse. Microsoft positions Fabric as the path forward for all four, so every observation is recorded against its documented destination on the target. Autonomous in the loop, accountable at the gates.

Synapse pipelines

Synapse pipelines run the same engine and JSON model as Azure Data Factory, so the Documenter parses them as Azure Resource Manager resources: a pipeline file with activities[], parameters, and concurrency; execution and control activities distinguished by whether they carry an activity-level linked service; and the dependsOn graph with its Succeeded, Failed, Skipped, and Completed conditions reconstructed into both the happy path and the error branches. What it records as Synapse-specific is environmental. Synapse pipelines support only Azure and self-hosted integration runtimes (there is no Azure-SSIS IR here) and storage-event trigger metadata is referenced differently, through @trigger().outputs.body.fileName and folderPath rather than the ADF @triggerBody() form. The Documenter notes those differences so the activity graph rebuilds faithfully on Data Factory in Fabric.

Spark notebooks

Synapse notebooks run on serverless Apache Spark pools across PySpark, Scala, Spark SQL, and .NET for Spark. The Documenter reads the chaining semantics first, because they decide how state moves. The %run magic copies another notebook’s cells into the caller and shares the variable context (include semantics) and a mssparkutils.notebook.exit inside the referenced notebook stops the caller; mssparkutils.notebook.run(...) instead invokes the other notebook as an isolated function with no shared variables. Confusing the two silently changes which variables and side-effects propagate, so the Documenter distinguishes them explicitly. It also captures session configuration set through %%configure (honored under %run, ignored under notebook.run), the mssparkutils / notebookutils calls into file systems and secrets, and the Delta Lake reads and writes that make Spark the producer of the interchange format the SQL side consumes. The .NET for Spark note is flagged as a rebuild driver, since it is unsupported on newer runtimes and Microsoft recommends Python or Scala.

Dedicated SQL pools

The dedicated SQL pool is an MPP T-SQL warehouse spread across 60 distributions, and almost none of its physical design survives a literal port, so the Documenter reads the design intent, not just the DDL. It captures the distribution strategy per table: hash-distributed on a chosen column for large facts and dimensions, where co-located joins on the same key avoid data movement; round-robin for staging, where joins reshuffle; replicated for small dimensions cached on every node. It records single-column partitioning and the partition switching and merging that drives data lifecycle, and the statistics the optimizer depends on, including the absence of an sp_create_stats equivalent that pushes teams toward a custom stored procedure. It also flags the dialect subset that signals what has already been adapted away from full SQL Server: the eight-level nesting cap, no @@NESTLEVEL, no INSERT...EXECUTE, constrained scalar UDFs, and blob-type limits that force dynamic SQL to be chunked through EXEC(). Distribution keys, replicated choices, and one-column partitioning are tuned to the 60-distribution architecture and must be re-derived for Fabric Warehouse or Databricks, never copied.

Serverless SQL

Serverless SQL is an on-demand T-SQL engine that queries lake files in place, with no provisioned infrastructure and no stored table data, so the Documenter reads how the relational surface is constructed over raw files. It captures OPENROWSET queries with their wildcards and schema inference, and for Delta the BULK pointer at a root folder containing _delta_log, noting the constraint that serverless reads Delta reader version 1 only: column renames, deletion vectors, and v2 checkpoints are out of reach, which is itself a reason Microsoft points newer Delta work to the Fabric SQL analytics endpoint. It records external tables with their external data sources and file formats, CETAS exports, and the views that assemble a logical data warehouse over the lake, including the partitioned views used because external tables do not partition. It also documents what cannot exist here by design: no regular tables, no DML, no triggers or materialized views, no scalar UDFs, and no time travel. Lake tables created by Spark pools become queryable from serverless after a schema-sync delay, which is the bridge the Documenter follows from the notebook workload to this one.