> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/SaaS/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/SaaS/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/new-connections-reference-guide.md). # New Connections Reference Guide Learn how connections work and about feature limitations {% hint style="info" %} **New connections** This new connections flow is available and released to most tenants. {% endhint %} {% hint style="info" %} This reference page is for the following connections: * **Amazon Redshift** * **Databricks Unity Catalog** * **Google BigQuery** (viewless integration) * **Snowflake** * **Starburst (Trino)** * **Teradata** For any other technologies, see the other [connections reference guide](/SaaS/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview.md). {% endhint %} Connections allow you to register your data objects in a technology through a single connection, making data registration more scalable for your organization. Instead of registering schema and databases individually, you can register them all at once and allow Immuta to monitor your data platform for changes so that data sources are added and removed automatically to reflect the state of data on your data platform. Once you register your connection, Immuta presents a hierarchical view of your data that reflects the specific hierarchy of objects in your data platform. For example, * **Host** (e.g., account, metastore, etc.) * **Database** * **Schema** * **Child data objects** such as tables, views, and other supported object types. These objects can have policy sync enabled and be managed as Immuta [data sources](/SaaS/configuration/integrations/data-and-integrations/registering-metadata/data-source-overview.md). Beyond making the registration of your data more intuitive, connections provides more control. Instead of performing operations on individual schemas or tables, you can perform operations (such as object sync) at the connection level. ## Connection settings The following settings can be configured within your connections: * **Connection details**: These are the details about the technology that allow Immuta to register and maintain a healthy connection. * [**Object sync**](#object-sync): This setting allows Immuta to [monitor the connection for changes](#object-sync). The time and frequency of this setting can be configured. * **Policy settings**: These settings impact policy on your data objects in the connection. * **Impersonation**: This setting enables and defines the role for [user impersonation for Snowflake connections](/SaaS/configuration/integrations/snowflake/snowflake-overview/accessing-data.md#user-impersonation). * **Excluded users and groups**: This setting controls the [users or groups that will be excluded from data and subscription policies](/SaaS/configuration/integrations/snowflake/snowflake-overview.md#excepted-roles-users) in your connection. * **Query audit**: When this setting is enabled, your users' queries will be audited in Immuta. Enable the query audit in the connection settings and [configure the frequency on the app settings page](/SaaS/configuration/application-configuration/how-to-guides/config-builder-guide.md#integration-settings). * **Object settings**: These settings impact the child objects within the connection. * [**Policy sync**](#policy-sync): Policy sync is the setting that controls if policy will be enacted on a child object. When policy sync is enabled, the child objects (e.g., tables, views, etc.) will have a linked data source and any policy that should be applied will be applied. If policy sync is disabled, then the child objects will not have data sources (or the data source will be disabled) and any policy that would apply to the object will not be applied until policy sync is enabled. * [**Data owners**](#permissions): This setting controls the data owners that will be added to the data objects within the connection. ## Object sync Immuta will ensure the objects in your database stay synchronous with the registered objects in Immuta. To do this, Immuta uses the account credentials provided during registration to check the remote technology for object changes: * If tables are added, new data objects are created in Immuta. * If remote tables are deleted, the corresponding data sources in Immuta will become disabled; however, the data object representing the table will still appear in the connections view until manually deleted. * If a column changes in a table, those changes will be reflected in the Immuta data source columns tab. Your connection can be synced in two ways: * **Automatic object sync**: This happens once every 24 hours (at 12:00 AM UTC). You can [update this frequency in the connection settings](/SaaS/configuration/integrations/snowflake/how-to-guides/connect-snowflake/manage-snowflake-connection-settings.md#edit-the-connection-details-1). * **Manual object sync**: You can manually run object sync on your whole connection or on any object in your connection. Object sync excludes Immuta-managed internal objects created for connection operation and policy enforcement. These internal objects are used by Immuta and are not ingested as data objects. ### Performance The following scenarios are regularly tested in an isolated environment in order to provide a benchmark. These numbers can vary based on a number of factors such as (but not limited to) number and type of policies applied, overall API and user activity in the system, connection latency to your data platform.
Scenario 1

Running object sync on a single schema with 1 data source with 50 columns		0.512 seconds on average
Scenario 2

Running object sync on a single schema with 1,000 data sources with 10 columns each		9.38 seconds on average
Scenario 3

Running object sync on a single schema with 10,000 data sources with 50 columns each		172.2 seconds on average
Scenario 4

Running object sync on 15 databases with 5,500 schemas (100,000 tables)		0.67 hours on average
Scenario 5

Running object sync on 125 databases with 3,000 schemas (200,000 tables)		1.32 hours on average
Scenario 6

Running object sync on 1,000 databases with 17,000 schemas (500,000 tables)		5.43 hours on average
### Tracking new data source columns If you would like to track when new data sources or new columns within a data source are discovered and registered via object sync, [enable the **New** tag behavior option on the app settings page](/SaaS/configuration/application-configuration/how-to-guides/config-builder-guide.md#new-tag-behavior). The new tag behavior setting will ensure that * When new columns are detected and added to Immuta through object sync, they will each be automatically tagged with the Immuta-managed **New** tag. * When new securables are detected and policy sync is enabled for new objects, a data source will be registered and automatically tagged with the Immuta-managed **New** tag. You can opt to have the **New** tags applied to only columns, only data sources, or both. When enabling the **New** tag behavior option, you can also activate the [seeded `New Column Added` global policy](/SaaS/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/data-policies.md#new-column-added-policy) to mask columns with the **New** tag, since they could contain sensitive data. The `New Column Added` global policy is staged (inactive) by default. See the [Clone, activate, or stage a global policy guide](/SaaS/govern/secure-your-data/authoring-policies-in-secure/clone-activate-stage.md) to activate the seeded global policy if you want any columns with the **New** tag to be automatically masked. #### Data source requests When there is an active policy that targets the **New** tag, Immuta sends validation requests to data owners for the following changes made in the remote data platform: * **Column added**: Immuta applies the **New** tag on the column that has been added and sends a request to the data owner to validate if the new column contains sensitive data. Once the data owner confirms they have validated the content of the column, Immuta removes the **New** tag from it and as a result any policy that targets the **New** column tag no longer applies. * **Column deleted**: Immuta deletes the column from the data source's columns tab in Immuta. Then, Immuta sends a request to the data owner to validate the deleted column. For instructions on how to view and manage your tasks and requests in the Immuta UI, see the [Manage access requests guide](/SaaS/configuration/integrations/data-and-integrations/registering-metadata/data-source-settings/manage-requests.md#manage-data-source-requests). To view and manage your tasks and requests via the Immuta API, see the [Manage data source requests](/SaaS/developer-guides/api-intro/immuta-v1-api/data-sources.md#manage-data-source-requests) section of the API documentation. ## Tags Tags can be applied to objects on any level of the connection and they will be inherited down to the child objects. If the child objects have policy sync enabled, the tags will be propagated on the data sources as well. See the [Manage connection tags guide](/SaaS/configuration/integrations/data-and-integrations/registering-a-connection/how-to-guides/manage-connection-tags.md) for details on adding or removing tags within connections. ### Automated tags All data sources within the registered connection and found by object sync after will get an automated tag that represents the connection. These tags can be used like any other in Immuta to [build policies](/SaaS/govern/secure-your-data/authoring-policies-in-secure.md), [add data sources to domains](/SaaS/configuration/domains/domains.md#domain-data-sources), [generate reports](/SaaS/govern/detect-your-data/audit/reference-guides/reports.md), etc. However, they cannot be edited or deleted. The tag will be formatted similar to the following example and applied to data sources from child data objects: `Immuta Connections . The Technology . Your Connection Name . Your Database . Your Schema` ## Policy sync Policy synchronization controls whether policies are applied to data objects within the connection. The connection must be in a healthy state for policy sync to function. When policy sync is turned on, data objects will be represented in Immuta as [data sources](/SaaS/configuration/integrations/data-and-integrations/registering-metadata/data-source-overview.md) where you can view the active data policies on the columns and the subscribed users of the data. If policy sync is disabled, the object will not have a data source (or the data source will be in a disabled state). ## Permissions Within the connection, the **Data Owner** permission can be granted on any data object, and will allow that user to manage that object and any within it. For example, granting a user **Data Owner** on a schema will grant them **Data Owner** on tables within that schema as well. Data owners can complete the following actions: * View the connections UI * Access any connection where they are granted **Data Owner** anywhere in the hierarchy * Trigger object sync for their data objects * Delete their data objects Granting **Data Owner** to a user on a table with policy sync enabled will also make them a data owner for the data source. ## Limitations * When trying to enable a data object, it must have fewer than 100,000 child objects. The only exception is the second-to-lowest object (e.g., a Snowflake schema), which can be enabled with any number of child objects to ensure bulk actions can be completed. * Using periods (`.`) in the display name of the connection or data object names should be avoided because periods are used as hierarchy delimiters in Immuta. If you must use periods in names, explicitly escape them to avoid issues. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://documentation.immuta.com/SaaS/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/new-connections-reference-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.