# Connections Reference Guide {% hint style="info" %} This feature is available to all 2025.1+ tenants. Contact your Immuta representative to enable this feature. {% 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 hierarchy of objects in your data platform: * **Host** (e.g., account, metastore, etc.) * **Database** * **Schema** * **Tables**: These represent the individual objects in your data platform, and when enabled, become data sources 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. ## Requirements See the following guides for a list of requirements per data platform: * [Register a Snowflake connection](https://documentation.immuta.com/latest/configuration/integrations/snowflake/how-to-guides/register-a-snowflake-connection) * [Register a Databricks Unity Catalog connection](https://documentation.immuta.com/latest/configuration/integrations/databricks/databricks-unity-catalog/how-to-guides/register-a-databricks-unity-catalog-connection) * [Register a Trino connection](https://documentation.immuta.com/latest/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection) ## Supported object types See the integration's reference guide for the supported object types for each technology: * [Snowflake](https://documentation.immuta.com/latest/configuration/snowflake/reference-guides/snowflake-overview#supported-object-types) * [Databricks Unity Catalog](https://documentation.immuta.com/latest/configuration/databricks/databricks-unity-catalog/unity-catalog-overview#supported-object-types) * [Trino](https://documentation.immuta.com/latest/configuration/starburst-trino/reference-guides/trino-connection-reference-guide#supported-object-types) ## 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. See the [connections' reference pages](https://documentation.immuta.com/latest/configuration/integrations/..#integrations) for each connection's support, but in general, the following is true: * If tables are added, new data sources 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 data dictionary. Your connection can be synced in two ways: * **Periodic object sync**: This happens once every 24 hours (at 1:00 AM UTC). Currently, updating this schedule is not configurable. * [**Manual object sync**](https://documentation.immuta.com/latest/configuration/integrations/registering-metadata/connections/how-to-guides/run-object-sync): You can manually run object sync on your whole connection or on any object in your connection. Object sync is designed to pull in the user’s data objects from the connected backing technology, so it specifically excludes internal Immuta-managed objects. These objects reside within the Immuta database or catalog, which is [created during the initial connection setup](https://documentation.immuta.com/latest/configuration/integrations/registering-metadata/connections/how-to-guides), and are used solely for Immuta's internal processes. Because these objects are only for Immuta processes and cannot be queried by users, the objects will be ignored by object sync and will not be ingested into Immuta. ### Connection 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](https://documentation.immuta.com/latest/governance/author-policies-for-data-access-control/authoring-policies-in-secure), [add data sources to domains](https://documentation.immuta.com/latest/configuration/domains/domains), [generate reports](https://documentation.immuta.com/latest/governance/detect-your-activity/audit/reference-guides/reports), etc. However, they cannot be edited or deleted. The tag will be formatted as follows and applied to data sources from table data objects: `Immuta Connections . The Technology . Your Connection Name . Your Schema . Your Database` ### Tracking new data source columns When new columns are detected and added to Immuta, they will be automatically tagged with the `New` tag. This allows governors to use the [seeded `New Column Added` global policy](https://documentation.immuta.com/latest/governance/author-policies-for-data-access-control/authoring-policies-in-secure/data-policies/reference-guides/data-policies#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](https://documentation.immuta.com/latest/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/how-to-guides/clone-activate-stage) to activate this seeded global policy if you want any columns with the `New` tag to be automatically masked. {% hint style="info" %} Without connections, [schema monitoring](https://documentation.immuta.com/latest/configuration/integrations/registering-metadata/data-sources/schema-monitoring/reference-guides/schema-monitoring) would also tag new data sources with the `New` tag. However this behavior is exclusive to schema monitoring and will not happen with object sync. Object sync only tags new columns of known data sources with the `New` tag. {% endhint %} ### 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 data dictionary 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](https://documentation.immuta.com/latest/configuration/integrations/data-sources/data-source-settings/how-to-guides/manage-requests#manage-access-requests). To view and manage your tasks and requests via the Immuta API, see the [Manage data source requests](https://documentation.immuta.com/latest/developer-guides/api-intro/immuta-v1-api/data-sources#manage-data-source-requests) section of the API documentation. ## Default settings When registering a connection, Immuta sets the connection to the recommended default settings to protect your data[^1]. The recommended settings are described below: * **Object sync**: This setting allows Immuta to monitor the connection for changes. *This setting is enabled by default and cannot be disabled.* * **Default run schedule**: This sets the time interval for Immuta to check for new objects. *By default, this schedule is set to 24 hours.* * **Impersonation**: This setting enables and defines the role for user impersonation, available with [select integrations](https://documentation.immuta.com/latest/configuration/integrations/integrations-overview). *This setting is disabled by default.* * **Project workspaces**: This setting enables [Snowflake project workspaces](https://documentation.immuta.com/latest/governance/author-policies-for-data-access-control/projects-and-purpose-based-access-control/writing-to-projects/how-to-guides/create-and-manage-project-workspaces). If you use [Snowflake secure data sharing with Immuta](https://documentation.immuta.com/latest/configuration/integrations/snowflake/reference-guides/data-sharing), enable this setting, as project workspaces are required. If you use [Snowflake table grants](https://documentation.immuta.com/latest/configuration/integrations/snowflake/reference-guides/table-grants-overview), disable this setting; project workspaces cannot be used when Snowflake table grants are enabled. Project workspaces are not supported with any other connections. *This setting is disabled by default.* ### Tag ingestion If you want all data objects from connections to have data tags ingested from the data provider into Immuta, ensure the credentials provided on the Immuta app settings page for the external catalog feature can access all the data objects. Any data objects the credentials do not have access to will not be tagged in Immuta. In practice, it is recommended to just use the same credentials for the connection and tag ingestion. ## 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 ## Deregistering a connection Deregistering a connection automatically deletes all of its child objects in Immuta. However, Immuta will not remove the objects in your backing technology. ### 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. * Having multiple objects with the same name within the same schema is currently unsupported and will lead to object uniqueness violations in Immuta. If this happens, all objects within the schema will not be properly ingested into Immuta. In this scenario, you can work around it as follows: * Ensure every object within the same schema has a unique name, or * Remove the visibility of one of the objects from the Immuta system account by adjusting the permissions in the backing technology. This will ensure only one of the objects is seen by the system account and ingested in Immuta. * 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. ### Related guides
LearnRead these guides to learn more about data platform connections, data sources, and policies.
  1. Databricks Unity Catalog reference guide
  2. Snowflake reference guide
  3. Trino reference guide
  4. Policies in Immuta
  5. Data sources in Immuta
ImplementFollow these guides to register a connection.
  1. Register a Databricks Unity Catalog connection
  2. Register a Snowflake connection
  3. Register a Trino connection
[^1]: Users cannot currently change the default settings. However, these settings can be adjusted using the integration configuration for [Snowflake](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api) or [Databricks Unity Catalog](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/how-to-guides/databricks-uc-api) without connections.