Prerequisites:

• Databricks Unity Catalog integration configured with Immuta

• Databricks tables registered as Immuta data sources

Query data with Python

1. Create a new workspace.

2. Query the Immuta-protected data as you normally would:

   Copy

   df = spark.sql('select * from database.table_name')
   df.show()

Query data with SQL

1. Create a new workspace.

2. Query the Immuta-protected data as you normally would:

   Copy

   select * from database.table_name;

View my data sources

1. Click on the Data Source icon in the panel on the left.

2. By default, all data sources will be displayed.

3. Opt to filter the data sources by your access, the backing technology, or the health of the data sources using filters.

4. To view the overview details of a data source, click on the arrow icon for data source, or open the data source overview page by clicking the name.

Subscribe to a data source

1. Click the Get Access button from either the data sources list page or the data source overview tab, which can be accessed by clicking on the Data Source.

2. If prompted, fill out the custom request form set up by the system admin and click Request Access.

3. A notification will be sent to the data owners informing them of your request.

4. Once reviewed, you will receive a notification with a response indicating if your request was accepted or denied.

5. If accepted, the status displayed next to that data source will be updated to "Subscribed" and you will have access to the data source via your personal SQL connection. If not accepted, a reason will be provided in the notification details.

Bulk access requests

To request access to multiple data sources simultaneously,

1. Navigate to the data sources list page.

2. Select the checkboxes for the data sources you want to subscribe to.

3. Select More Actions.

4. Click Request Access.

5. If prompted, fill out the custom request form set up by the system admin and click Request Access.

6. A notification will be sent to the data owners informing them of your request.

7. Once reviewed, you will receive a notification with a response indicating if your request was accepted or denied.

8. If accepted, the status displayed next to that data source will be updated to "Subscribed" and you will have access to the data source via your personal SQL connection. If not accepted, a reason will be provided in the notification details.

Unsubscribe from a data source

If you no longer need access to a data source, click Unsubscribe in the upper right corner of the Data Source Overview tab.

Manually run health jobs

If a data source health check fails and needs to be re-generated,

1. Click the health indicator in the upper right-hand corner.

2. Select Re-run on the job you want to run.

Note: To generate a fingerprint, the row count must be up-to-date.

View the data dictionary

To view the data dictionary,

1. Select the data source from the data source list page.

2. Navigate to the Data Dictionary tab.

3. The data dictionary will display and include the column’s name, type, and tags. Masked columns will display a symbol next to their names.

View data source contact information

Contact information for data owners is provided for each data source, which allows other users to ask them questions about accessibility and attributes required for viewing the data.

To view this contact information, click the Contacts tab.

Make an unmasking request

To request to unmask a value in a data source,

1. Navigate to the Data Source Overview tab, click the dropdown menu in the top right corner, and select Make Unmasking Request.

2. In the modal that appears, select the column from the first dropdown menu, and then complete the Values to Unmask and the Reason for Unmasking fields.

3. Select the user to unmask the value from the final dropdown menu, and then click Submit.

A Tasks tab will then appear for your data source that details the task type and the status of your request. You may also view task information or delete the task from this page.

View and manage tasks

After sending an unmask request, a tasks tab will appear on the data source overview page listing the target and requesting users, the task type, and the state of the task.

To view information about a task,

1. Navigate to the Tasks tab from the Data Source Overview page.

2. Click the Task Info icon in the Actions column of the relevant task.

To delete a task,

1. Navigate to the Tasks tab from the Data Source Overview page.

2. Click Delete Task.

Prerequisites:

• REVOKE users' access to raw tables

Query data

1. Use your tool of choice to connect to Redshift.

2. Select the Immuta database name used when .

3. Query the Immuta-protected data, which takes the form of immuta_database.backing_schema.table_name:

   1. Immuta Database: The Immuta database name used when .

   2. Backing Schema: The schema that houses the backing tables of your Immuta data sources.

   3. Table Name: The name of the table backing your Immuta data sources.

4. Run your query (it is recommended that you use the catalog in the query). It should look something like this:

Data consumers are Immuta users that consume the data available through Immuta in their data platform as usual. Find how-to guides specific to data consumers listed below.

How-to guides

• : Subscribe to data sources in Immuta, run health jobs, and complete other actions as a data source subscriber.

• Query data: Query policy-protected data in your normal data platform.

• : Subscribe to projects in Immuta to collaborate with others, work under a purpose, or write data to a workspace.

Prerequisites:

Query data with Snowflake table grants

1. Execute the USE SECONDARY ROLES ALL command or change your role to the .

2. Query the data as you normally would in Snowflake.

Query data without Snowflake table grants

Prerequisite: Users have been granted SELECT privileges on all or relevant Snowflake tables

Query the data as you normally would in Snowflake:

Prerequisites:

Query data

1. Select SQL from the navigation menu in Databricks.

2. Click Create → Query.

3. Run your query as you normally would:

Prerequisites:

Query data

1. Use your tool of choice to connect to Starburst.

2. Query the Immuta-protected data as you normally would:

Subscribe to a project

1. Click Data in the navigation menu and then select Projects.

2. Click Join Project from either the all projects view or the project overview tab, which can be accessed by clicking on the project.

3. Click Join to confirm you want to join the project.

4. After you have been granted access to the project, go to the project and click I Agree to acknowledge that you will only use the project for its specified purposes.

Change project contexts

Switch projects in the Immuta UI

1. Click the dropdown menu in the top right corner of the console.

2. Select a project. Once selected, the current project will display at all times in the top right corner of the console.

If you unsubscribe from the project, this display will default to No Current Project.

Switch projects using UDFs in Databricks

1. View your available projects by running the following query in Spark: select * from immuta.list_projects. In the resulting table, note the values listed in the id column; this value will be used at the parameter in the following step.

2. Run select immuta.set_current_project(<id>). This UDF must be called in its own notebook cell to ensure the changes take effect.

Your project context will be switched, and that project's data sources and workspaces will now be visible. To set your project context to None, run select immuta.set_current_project() with no parameters.

Note: Since the UDFs are not actually registered with the FunctionRegistry, if you call DESCRIBE FUNCTION immuta.set_current_project, you won't get back the documentation for the UDF. For a complete list of functions, see the Project UDFs reference guide.

Create a project-based API key

Any project member can create project-based API keys, which are used for authenticating external tools with Immuta.

1. Navigate to the Project Overview tab.

2. Click the Get API Key button at the bottom of the left panel.

3. An API Key modal will display with your requested information. Store these credentials somewhere secure. If you misplace this information, you will have to generate a new key and re-authenticate all services connected to Immuta via this key.

4. Click the Close button.

Create project-based SQL connections

Project SQL accounts are unique to each project and only provide access to the data sources in that project. Project SQL credentials cannot be retrieved from Immuta if they are lost. Credentials can only be re-generated using the instructions below. When a user generates new SQL credentials for a project, any existing SQL credentials for that project the user may have had are revoked.

1. Navigate to the Project Overview tab.

2. Click SQL Connection in the upper right corner.

3. A window will display with the connection information. Store these credentials somewhere secure. If you misplace them, you will have to generate a new account and re-authenticate all services connected to Immuta via this account.

4. Click Close.

Leave a project

1. Navigate to the Project Overview tab.

2. Click the Leave Project button in the upper right corner, and then click Confirm.

Manage project data sources

Add data sources to a project

Any project member can add data sources to a project, unless the project equalization or allow masked joins features are enabled; in those cases only project owners can add data sources to the project.

1. Select the project, and then navigate to the Project Overview tab.

2. Click the Add Data Sources button in the Data Sources section in the center pane.

3. Start typing the name of a data source you'd like to include in the project.

4. Select the data source from the list of auto-completed options in the dropdown menu.

5. Repeat this process to add additional data sources to the list. Click Remove to remove them.

6. When complete, click the Add button at the bottom of the list.

Add data sources by purpose

You can automatically add all data sources to a project that contain a Limit usage to purpose policy that matches the purpose of that project.

1. Select a Project, and click the Add Data Sources button on the Data Sources tab.

2. Click Add By Purpose in the top right of the dialog.

3. All data sources matching the project's purpose(s) will populate at the bottom of the dialog. Review this list, and then click Save.

Create a derived data source outside a workspace

1. Select a project and navigate to the Overview or Data Sources tab.

2. Click Add Derived Data Source.

3. Begin typing in the Search by Name or Description text box, and then select the data source(s) from which your new data source will be derived.

4. Click Save.

5. Follow the instructions for creating a data source.

Remove data sources from a project

As a project member, you can only delete data sources you've added to the project.

1. Select a project, and then click the Data Sources tab.

2. Click the Remove Data Source icon in the Actions column of the data source you want to remove.

3. Click Confirm in the window that appears.

Search for projects

Immuta's UI provides a list of all projects, excluding those that have been set to private. Users can search for projects by keyword, tag, or data source.

1. To access a list of all projects, click the projects icon in the left sidebar, and then click the All Projects tab.

2. To filter projects by keyword, type one or more keywords into the search box at the top of the page, and select a keyword from the auto-completed results. If a list does not display, then no keywords matching that text currently exist.

3. To filter projects by tags, type one or more tag names into the search box at the top of the page and select a tag from the list of auto-completed results. If a list of tags does not display, then no tags matching that text currently exist.

4. To filter projects by data sources, type one or more data source names into the search box at the top of the page and select a data source from the list of auto-completed results. If a list of data sources does not display, then no data sources matching that text currently exist.

Prerequisites:

• Azure Synapse Analytics integration configured with Immuta

• Azure Synapse Analytics tables registered as Immuta data sources

• REVOKE users' access to raw tables

• GRANT users' access to the Immuta schema

Query data

1. Click the Data menu in Synapse Studio.

2. Click the Workspace tab.

3. Expand the databases, and you should see the dedicated pool you specified when configuring the integration.

4. Expand the dedicated pool and you should see the Immuta schema you created when configuring the integration.

5. Select that schema.

6. Select New SQL script and then Empty script.

7. Run your query (note that Synapse does not support LIMIT and the SQL is case sensitive). It should look something like this:

   Copy

   SELECT TOP 100 * FROM immuta_schema.backing_database_backing_table;