M↓ View as Markdown ↗

Azure Synapse¶

Connect an Azure Synapse Analytics dedicated SQL pool to Actian AI Analyst so you can build Models on its tables and let your AI Analysts query them.

Availability

Who can do this: members with the Edit capability in the active Workspace. If your organization has turned on Restrict connection management, you also need the Manage organization capability.
Plan: Studio lists only the connectors that your organization's plan and your deployment include. If Azure Synapse is missing from the list, ask your administrator.
Deployment: Actian SaaS and self-managed deployments.

Read-only access depends on the login or service principal

Synapse has no read-only session that AI Analyst can switch on, so AI Analyst relies on the permissions of the login or service principal you supply. The connection form shows: This Connector cannot enforce read-only access itself. Supply a warehouse user that is limited to read-only privileges. Give the identity db_datareader only. See Read-only access.

1. Create a read-only identity in Synapse¶

Choose one of the two authentication methods that AI Analyst supports.

On a dedicated SQL pool, you create the login in the master database and the user in the pool database. Run the two blocks separately.

-- Run while connected to the master database
CREATE LOGIN analyst_synapse WITH PASSWORD = '<your_secure_password>';

-- Run while connected to your dedicated SQL pool database
CREATE USER analyst_user FOR LOGIN analyst_synapse;
ALTER ROLE db_datareader ADD MEMBER analyst_user;

Option B: service principal (Microsoft Entra ID)¶

In the Azure portal, create an app registration (or use an existing one) and note its Directory (tenant) ID and Application (client) ID.
Under Certificates & secrets, create a client secret and copy its Value.

While connected to your dedicated SQL pool database with an account that can create users in the pool, create a database user for the app and give it read access:

-- Run while connected to your dedicated SQL pool database
CREATE USER [<app-registration-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<app-registration-name>];

For a service principal, you don't need a SQL login. The Microsoft Fabric guide describes the same app registration steps in more detail.

2. Allow AI Analyst to reach Synapse¶

Add AI Analyst's outbound IP addresses to the firewall rules of your Synapse workspace:

Actian SaaS: when your deployment publishes its outbound addresses, the Setup help panel next to the connection form lists them under Which IPs to allow. If the panel doesn't list any addresses, contact Actian support for them.
Self-managed deployment: allow the outbound addresses of your own AI Analyst installation.

See Network access for details.

3. Add the connection in Studio¶

In Studio, open Connections, click + (Add connection) and choose Azure Synapse under Warehouses.
Under Connection details, enter a Name, for example Sales Synapse. Names must be unique among the connections you can see. See Connections and Workspaces. Optionally add a Description.
Optionally, tick Private to this Workspace so that only the active Workspace can see and use the connection. See Who can see the connection.

Under Credentials, fill in the fields:

Field	Value
Host	Your dedicated SQL pool endpoint, without a protocol, for example `your-workspace.sql.azuresynapse.net`
Port	`1433` by default
Database	Your dedicated SQL pool database
Authentication	SQL login (default) or Service principal
SSL mode	Require (no verify) by default. See SSL mode.

The credential fields depend on the Authentication you choose:

Authentication	Fields
SQL login	Username (`analyst_synapse`) and Password
Service principal	Tenant ID, Client ID and Client secret from your app registration

Instead of typing each field, you can click Paste a connection string, paste a string such as Server=tcp:workspace.sql.azuresynapse.net,1433;Database=database;User ID=user;Password=password;Encrypt=True, and click Fill the form. If the string contains Authentication=Active Directory Service Principal, Studio selects Service principal and fills Client ID (and Tenant ID, if given as client-id@tenant-id) and Client secret from User ID and Password. Nothing is sent until you test the connection.

Click Test connection. When the test succeeds, Schemas appears and lists the schemas the identity can see. dbo is selected if it exists.
To expose schemas other than dbo, select them for browsing and model authoring. Changing the selection resets the test, so click Test connection again. Your selection is kept. If dbo doesn't exist, nothing is preselected: select at least one schema before you save.
Click Save connection. The button stays disabled until a test succeeds and the connection has a name.

Studio opens the new connection. Credentials are encrypted at rest and are never shown again after saving. To browse tables, re-test the connection or update credentials later, see Manage connections.

SSL mode¶

SSL mode	Encrypts the connection	Verifies the server certificate
Disable	No	No
Require	Yes	Yes
Require (no verify) (default)	Yes	No. The server certificate is trusted as presented.
Verify CA	Yes	No. It behaves like Require (no verify).
Verify full	Yes	Yes

Choose Verify full (or Require) to validate the server certificate. Uploading a CA certificate or a client certificate is not supported.

Who can see the connection¶

A new connection is attached to the Workspace you are working in.

Organization connection (default): an organization admin can attach it to other Workspaces later.
Private to this Workspace: only this Workspace can see or use it. An organization admin can later share it with the whole organization. A shared connection can't be made private again.

See Connections and Workspaces.

Next steps¶

Before people can ask questions about this data:

Create Models on the tables you want to analyse.
Add the Models to an AI Analyst.

You can also monitor the connection's health.

Troubleshooting¶

Message after Test connection or Save connection	Likely cause and fix
Fill in … before testing the connection	A required field is empty. With Service principal, all of Tenant ID, Client ID and Client secret are required.
Authentication failed (if shown)	Check the login and password, or the tenant ID, client ID and client secret. Make sure you copied the secret's Value, not its ID.
Could not connect	Studio shows this when it can't classify the failure. Click the message to expand the driver's detail. A "Login failed for user" message means the login or password is wrong, or the user has no access to the pool database. For a service principal, an "Invalid client secret" or `AADSTS` message means a wrong or expired secret, or a wrong Tenant ID or Client ID.
Could not reach the warehouse	Check the Host and Port, and that the Synapse firewall allows AI Analyst's IP addresses (step 2).
Could not establish a secure connection	The SSL settings don't match the server. See SSL mode.
This warehouse user cannot see those objects (if shown)	Check that the database user exists in the pool database and is a member of `db_datareader`.
The test succeeds but Schemas doesn't appear	The identity can't see any schema in this database. Check the grants in step 1. The request to list schemas can also fail after the test (a brief error appears). Click Test connection again.
Warehouse host is not allowed	The host is a private or blocked address, doesn't resolve, or includes a protocol, path or port. Use a publicly reachable host name, or on a self-managed deployment ask your operator to allow the private range. See Network access.
A connection with this name already exists	Choose a different Name. This message appears after you click Save connection.