azure-synapse-analytics

name	azure-synapse-analytics
description	Expert knowledge for Azure Synapse Analytics development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when designing Synapse workspaces, Spark pools, dedicated/serverless SQL, Delta Lake, or Synapse Link workloads, and other Azure Synapse Analytics related development tasks. Not for Azure Data Factory (use azure-data-factory), Azure Data Explorer (use azure-data-explorer), Azure Databricks (use azure-databricks), Azure HDInsight (use azure-hdinsight).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-04-12","generator":"docs2skills/1.0.0"}

Azure Synapse Analytics Skill

This skill provides expert guidance for Azure Synapse Analytics. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L62	Diagnosing and fixing Synapse issues: workspace/tenant moves, Spark jobs and libraries, SQL pools and queries, Synapse Link, Studio/storage connectivity, and common errors/timeouts.
Best Practices	L63-L121	Best practices for Synapse: Spark tuning, Delta/Hyperspace optimization, dedicated/serverless SQL design and performance, T-SQL patterns, indexing/stats, and Netezza/Oracle/Teradata migration guidance.
Decision Making	L122-L141	Guidance on choosing Synapse components, planning migrations (Netezza/Oracle/Teradata/SQL pools), sizing and cost management, Spark lifecycle, table distribution, and using tools like Advisor and query history.
Architecture & Design Patterns	L142-L162	Architecture and design guidance for Synapse workspaces, SQL/serverless/Spark pools, data warehouse migrations, table design, ELT/PolyBase loading, and workload management.
Limits & Quotas	L163-L172	Synapse SQL pool limits: maintenance windows, memory/concurrency by performance level, capacity caps, temp table behavior, serverless Delta Lake v1 querying, and Synapse Link feature limits/issues.
Security	L173-L231	Securing Synapse workspaces end-to-end: auth and RBAC, network isolation, private endpoints, encryption, data exfiltration, policies, and secure access to storage, SQL, Spark, and migration scenarios.
Configuration	L232-L280	Configuring Synapse workspaces, Spark pools, and SQL pools: environments, scaling, libraries, monitoring/metrics, backups/restore, workload management, and integrations (Purview, AML, SynapseML).
Integrations & Coding Patterns	L281-L317	Patterns and code to integrate Synapse (Spark, serverless, dedicated SQL) with ADLS, Cosmos DB, Azure SQL, AML, monitoring (Log Analytics, Prometheus), and external tools via connectors, REST, and T-SQL.
Deployment	L318-L331	Deploying and managing Synapse workspaces and dedicated SQL pools: ARM/Bicep templates, CI/CD, source control, restore points, maintenance windows, and automated compute management.

Troubleshooting

Topic	URL
Recover Synapse workspaces after Entra tenant move	https://learn.microsoft.com/en-us/azure/synapse-analytics/how-to-recover-workspace-after-tenant-move
Known issues and workarounds for Azure Synapse Analytics	https://learn.microsoft.com/en-us/azure/synapse-analytics/known-issues
Resolve compatibility issues between SQL Server apps and Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/partner/compatibility-issues
Diagnose and resolve Livy job errors in Synapse Spark	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-handle-livy-error
Debug Synapse Spark apps with extended history server	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-history-server
Troubleshoot Synapse Spark library installation failures	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-troubleshoot-library-errors
Identify Synapse queries exceeding execution timeouts	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/sql-data-warehouse-how-to-find-queries-running-beyond-wlm-elapsed-timeout
Troubleshoot and optimize Gen2 cache performance	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/sql-data-warehouse-how-to-monitor-cache
Troubleshoot misclassified workloads in Synapse SQL pools	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/sql-data-warehouse-how-to-troubleshoot-missed-classification

Best Practices

Topic	URL
Configure Git source control for Synapse Studio	https://learn.microsoft.com/en-us/azure/synapse-analytics/cicd/source-control
Apply design and performance best practices for Netezza to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/1-design-performance-migration
Plan ETL and data load for Netezza to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/2-etl-load-migration-considerations
Implement visualization and reporting after Netezza to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/4-visualization-reporting
Minimize SQL compatibility issues in Netezza to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/5-minimize-sql-issues
Apply design and performance best practices for Oracle to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/oracle/1-design-performance-migration
Plan ETL and data load for Oracle to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/oracle/2-etl-load-migration-considerations
Implement visualization and reporting after Oracle to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/oracle/4-visualization-reporting
Minimize SQL compatibility issues in Oracle to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/oracle/5-minimize-sql-issues

Decision Making

Topic	URL
Compare Synapse data integration with Azure Data Factory	https://learn.microsoft.com/en-us/azure/synapse-analytics/data-integration/concepts-data-factory-differences
Assess environment to choose Synapse technologies	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-assess-environment
Review Synapse project plan for implementation success	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-project-plan
Plan migration to Azure Synapse dedicated SQL pool	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/migrate-to-synapse-analytics-guide
Select tools for Netezza data warehouse migration to Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/6-microsoft-third-party-migration-tools
Select tools for Oracle data warehouse migration to Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/oracle/6-microsoft-third-party-migration-tools
Choose Microsoft and third-party tools for Teradata to Synapse migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/teradata/6-microsoft-third-party-migration-tools
Plan and manage Azure Synapse Analytics costs	https://learn.microsoft.com/en-us/azure/synapse-analytics/plan-manage-costs
Plan Synapse Spark runtime lifecycle and support	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/runtime-for-apache-spark-lifecycle-and-supportability

Architecture & Design Patterns

Topic	URL
Evaluate Synapse data integration architecture design	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-data-integration-design
Evaluate dedicated SQL pool data warehouse design	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-dedicated-sql-pool-design
Evaluate serverless SQL pool architecture and design	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-serverless-sql-pool-design
Evaluate Apache Spark pool design in Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-spark-pool-design
Evaluate Azure Synapse workspace architecture design	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-workspace-design
Success by Design architecture guidance for Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/success-by-design-introduction
Design a modern Azure data warehouse after Netezza migration	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/netezza/7-beyond-data-warehouse-migration
Design a modern data warehouse after Teradata migration to Azure	https://learn.microsoft.com/en-us/azure/synapse-analytics/migration-guides/teradata/7-beyond-data-warehouse-migration
Design ELT-based data loading patterns for Synapse dedicated SQL pools	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/design-elt-data-loading

Limits & Quotas

Topic	URL
Memory and concurrency limits by Synapse performance level	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/memory-concurrency-limits
Review capacity limits for Synapse dedicated SQL pools	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/sql-data-warehouse-service-capacity-limits
Use temporary tables in Synapse SQL pools	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql/develop-tables-temporary
Query Delta Lake v1 with Synapse serverless SQL	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql/query-delta-lake-format
Supported features and limitations of Synapse Link for Cosmos DB	https://learn.microsoft.com/en-us/azure/synapse-analytics/synapse-link/concept-synapse-link-cosmos-db-support
Limitations and known issues for Synapse Link for SQL	https://learn.microsoft.com/en-us/azure/synapse-analytics/synapse-link/synapse-link-for-sql-known-issues

Security

Topic	URL
Access firewall-protected Purview from Synapse securely	https://learn.microsoft.com/en-us/azure/synapse-analytics/catalog-and-governance/how-to-access-secured-purview-account
Secure Synapse linked services with managed VNet	https://learn.microsoft.com/en-us/azure/synapse-analytics/data-integration/linked-service
Design and implement access control in Azure Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/security-white-paper-access-control
Implement authentication options for Azure Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/security-white-paper-authentication
Configure data protection features in Azure Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/security-white-paper-data-protection
Configure network security for Azure Synapse workspaces	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/security-white-paper-network-security
Use threat detection and auditing in Azure Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/security-white-paper-threat-protection
Browse ADLS Gen2 with ACLs in Synapse securely	https://learn.microsoft.com/en-us/azure/synapse-analytics/how-to-access-container-with-access-control-lists
Configure secure prerequisites for Foundry Tools in Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/tutorial-configure-cognitive-services-synapse

Configuration

Topic	URL
Connect Synapse workspace to Microsoft Purview	https://learn.microsoft.com/en-us/azure/synapse-analytics/catalog-and-governance/quickstart-connect-azure-purview
Design Synapse development, test, and production environments	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-evaluate-solution-development-environment-design
Configure and review monitoring for Azure Synapse	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-perform-monitoring-review
Link Synapse workspace to Azure Machine Learning	https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/quickstart-integrate-azure-machine-learning
Set up SynapseML environment for Foundry Tools	https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/setup-environment-cognitive-services
Reference monitoring metrics and logs for Synapse Analytics	https://learn.microsoft.com/en-us/azure/synapse-analytics/monitor-synapse-analytics-reference
Monitor Apache Spark applications in Synapse Studio	https://learn.microsoft.com/en-us/azure/synapse-analytics/monitoring/how-to-monitor-spark-applications
Runtime components for Synapse Spark 3.3	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-33-runtime
Review component versions in Synapse Spark 3.4 runtime	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-34-runtime

Integrations & Coding Patterns

Topic	URL
Access Synapse ADLS Gen2 data from Azure Machine Learning	https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/access-data-from-aml
Score ML models with PREDICT in Synapse Spark	https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/tutorial-score-model-predict-spark-pool
Send Synapse Spark logs and metrics to Log Analytics	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-azure-log-analytics
Use Delta Lake tables with Synapse Spark	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-delta-lake-overview
Manage Synapse Spark packages via PowerShell and REST	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-manage-packages-outside-ui
Emit Synapse Spark logs and metrics to Event Hubs	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/azure-synapse-diagnostic-emitters-azure-eventhub
Emit Synapse Spark logs and metrics to Azure Storage	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/azure-synapse-diagnostic-emitters-azure-storage
Collect Synapse Spark metrics via Prometheus APIs	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/connect-monitor-azure-synapse-spark-application-level-metrics
Use Spark CDM connector to read/write Common Data Model	https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/data-sources/apache-spark-cdm-connector

Deployment

Topic	URL
Restore dedicated SQL pools in Synapse Analytics	https://learn.microsoft.com/en-us/azure/synapse-analytics/backuprestore/restore-sql-pool
Create user-defined restore points in Synapse SQL	https://learn.microsoft.com/en-us/azure/synapse-analytics/backuprestore/sqlpool-create-restore-point
Implement CI/CD for Azure Synapse workspaces	https://learn.microsoft.com/en-us/azure/synapse-analytics/cicd/continuous-integration-delivery
Perform operational readiness review for Synapse deployment	https://learn.microsoft.com/en-us/azure/synapse-analytics/guidance/implementation-success-perform-operational-readiness-review
Deploy Synapse workspaces using ARM templates	https://learn.microsoft.com/en-us/azure/synapse-analytics/quickstart-deployment-template-workspaces
Plan and configure Synapse SQL pool maintenance windows	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/maintenance-scheduling
Automate Synapse SQL compute management with Functions	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/manage-compute-with-azure-functions
Deploy Synapse dedicated SQL pool using ARM templates	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/quickstart-arm-template
Deploy Synapse dedicated SQL pool using Bicep templates	https://learn.microsoft.com/en-us/azure/synapse-analytics/sql-data-warehouse/quickstart-bicep
Set up CI/CD for Synapse dedicated SQL pools