Connection Settings

Create a user for Narrator

Narrator just needs a personal access token to connect. This can be done either though an existing user, or with a service principal.

Option 1: Service Principal (cannot be done through the user interface)

1. create a new service principal for Narrator to connect
2. grant the can use token permission to it
3. Create a Databricks personal access token on behalf of the service principal using the POST /token-management/on-behalf-of/tokens operation API in the token management REST API.

Further reading

Option 2: User

1. Navigate to your Account Console
2. create a new user, or identify an existing user Narrator can connect as
3. generate a personal access token (see below)

Create an access token

Additional resources can be found in the following documentation

1. Navigate to your Databricks workspace and click the Settings Icon in the lower-left corner as shown below. Then go to your User Settings

2. Navigate to the Access Tokens tab and click on Generate New Token as shown below.

Ensure you have a SQL Warehouse

go to SQL > Create > SQL warehouse if it hasn't been created

Get your connection details

3. Navigate to your Databricks workspace and click the SQL Endpoints icon present in the sidebar.

4. Choose an endpoint where you want to connect.

5. Navigate to the Connection Details tab and copy the server Hostname and HTTP Path details as shown below.

6. Click Test Connection

Connecting using SSH Tunnel

Instructions

Narrator's Public Key

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHQLZ/BQf5GDPRfXmHt9ecmChGjhOWZsZZOGsn82M1nJ

Connect in Narrator

Navigate to the Narrator warehouse settings page and enter the credentials to connect your warehouse

If connecting doesn't work ensure the user has databricks-sql-access permissions. It should be granted by default

Permissions

Narrator needs the proper permissions to query source tables and manage its activity stream.

Here's how Narrator works with the warehouse

• We have full access to one schema, called narrator by convention, where we create and update the activity stream tables, enrichment tables, materialized views, etc
• We have readonly access to any schemas we need to query to build the activity stream

Create the Narrator Schema

Create the narrator and narrator_mv schemas and grant all privileges to the narrator user

CREATE SCHEMA narrator;
GRANT ALL PRIVILEGES ON SCHEMA narrator TO `...`;

CREATE SCHEMA narrator_mv;
GRANT ALL PRIVILEGES ON SCHEMA narrator_mv TO `...`;

If ALL PRIVILEGES seems like too much grant SELECT, CREATE, MODIFY, USAGE, READ_METADATA

Grant access to all needed schemas

Grant select on all source data schemas Narrator will need to access

GRANT USAGE, READ_METADATA, SELECT ON SCHEMA <schema_name> TO `...`