> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/azure-synapse.md).

# Azure Synapse

[Azure Synapse Analytics](https://learn.microsoft.com/azure/synapse-analytics/) is a SQL-based analytics service from Microsoft. Nilus supports Synapse reads through the **MS SQL Server batch source path** because Synapse dedicated SQL pools speak T-SQL over TDS. There is no separate `synapse://` source scheme; use `mssql://` or a DataOS depot configured for the SQL Server/MSSQL driver.

{% hint style="info" %}
Synapse **is** also supported as a Nilus **destination** for writing data into a Synapse pool.
{% endhint %}

## Connector status

| Item                 | Status                                                                       |
| -------------------- | ---------------------------------------------------------------------------- |
| Native source scheme | No separate `synapse://` source scheme.                                      |
| Recommended path     | Use the MS SQL Server batch source against a dedicated Synapse SQL pool.     |
| Pipeline mode        | Batch pipeline using the `mssql://` source path or a SQL Server/MSSQL depot. |
| Destination support  | Synapse is supported as a Nilus destination.                                 |

## Supported source path

Use the [MS SQL Server (Batch)](/concepts/resources/nilus/batch/batch-sources/ms-sql-server.md) source against a Synapse dedicated SQL pool. Synapse's dedicated pool speaks T-SQL over TDS, so the `mssql://` scheme can connect and run `SELECT` queries against it. Caveats apply:

* **Dedicated SQL pool only**: serverless SQL pool support is not validated through this path. Behavior on serverless varies by query and may hit timeouts unrelated to Nilus.
* **Identifier and type quirks**: Synapse's T-SQL dialect is close to but not identical to SQL Server. Hand-test types and `incremental_key` semantics on a representative table before committing a production schedule.
* **Connection string**: use the Synapse-provided SQL endpoint (`<workspace>.sql.azuresynapse.net`) and a SQL or Azure AD identity with `SELECT` on the schemas you target.
* **Depot configuration**: connect via a DataOS depot configured for the SQL Server/MSSQL driver and pointed at the Synapse endpoint, or via direct `mssql://` URI with credentials projected through `spec.use.projection`.

This is the supported source path for compatible dedicated SQL pool workloads.

## Requirements

* Use a Synapse dedicated SQL pool endpoint; serverless SQL pool behavior is not validated through this path.
* Grant the projected SQL or Azure AD identity `SELECT` on every schema/table referenced by `source_table`.
* Use the Synapse SQL endpoint (`<workspace>.sql.azuresynapse.net`) with the SQL Server driver settings required by your environment.
* Test source SQL, data types, and `incremental_key` behavior on a representative table before scheduling production runs.

## Sample Nilus config (Synapse via MSSQL source)

```yaml
name: synapse-orders-batch
version: v1alpha
type: nilus
spec:
  type: batch
  compute: runnable-default
  use:
    projection:
      secrets:
        - id: engineering:synapse-secret
          contextAlias: synsecret
      projections:
        envVars:
          - key: SYN_USER
            template: "{{ secrets['synsecret'].user | base64_decode }}"
          - key: SYN_PASSWORD
            template: "{{ secrets['synsecret'].password | base64_decode }}"
  source:
    address: mssql://{SYN_USER}:{SYN_PASSWORD}@myworkspace.sql.azuresynapse.net/analyticsdb?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes&TrustServerCertificate=no
    options:
      source_table: dbo.orders
      incremental_key: modified_at
  sink:
    address: dataos://analytics-lakehouse
    options:
      dest_table: synapse.orders
      incremental_strategy: merge
```

The URI is the standard `mssql://` shape; Nilus does not validate that the host is actually Synapse vs SQL Server. If you hit a feature mismatch (e.g. a stored procedure or system view that exists in SQL Server but not in Synapse), the failure surfaces as a T-SQL syntax / object-not-found error rather than a connector error.

## Behavior and capabilities

* **Pipeline mode**: Synapse reads run as a `batch` pipeline through the MS SQL Server source path.
* **Object selection**: set `source.options.source_table` to a table or view that the Synapse endpoint can serve through TDS.
* **Fetch semantics**: Nilus behaves like a SQL Server batch reader; Synapse-specific SQL differences are surfaced as source query errors.
* **Operational fit**: use this for dedicated SQL pool workloads that behave like ordinary T-SQL table reads.
* **Unsupported behavior**: Nilus does not provide a `synapse://` source address or validate serverless SQL pool behavior.

## Troubleshooting

| Symptom                                      | Likely cause                                                                      | Resolution                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `Unsupported source scheme` for `synapse://` | Synapse does not have a separate Nilus source scheme.                             | Use the `mssql://` source path or a SQL Server/MSSQL depot against a dedicated SQL pool.     |
| T-SQL object or syntax errors                | The query path uses SQL Server behavior that differs in Synapse.                  | Test the query directly against the Synapse endpoint and adjust the table/view or SQL shape. |
| Authentication or encryption failure         | Driver, identity, or TLS settings do not match the Synapse endpoint requirements. | Verify the SQL endpoint, projected credentials, and `Encrypt` / certificate settings.        |

## Roadmap

A dedicated `synapse://` source scheme may be added in a future release; today Synapse source reads go through the MS SQL Server source path. If you have a Synapse-as-source use case the `mssql://` path can't cover, open a request with your Nilus contact so it can be sequenced.

## Related docs

* [MS SQL Server (Batch)](/concepts/resources/nilus/batch/batch-sources/ms-sql-server.md): supported source connector used for Synapse dedicated SQL pool reads.
* [Secrets and Projections](/concepts/resources/nilus/concepts/secrets-and-projections.md): credential projection model for direct URIs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/azure-synapse.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.