Overview

These are manual instructions for setting up BigQuery. Follow this if you're not able to grant Narrator access to an Admin user.

To set up BigQuery, we will

1. Create a custom role
2. Create a service account with the custom role

Create the Custom Role

Step 1: Open Console

Go to the Roles Console for the project or organization that contains your BigQuery data

🚧

Project Specific Roles

Make sure you're in the correct Project (the project that contains your BigQuery data) when doing the steps below. If you'd prefer to grant Dataset specific access to Narrator, scroll down to the "Dataset Specific Permissions" section at the bottom of this doc: https://docs.narrator.ai/page/how-to-setup-non-admin-permissions-in-bigquery#dataset-specific-permissions

Step 2: Click on "+ Create Role"

Step 3: Define your basic information

Step 4: Add the proper permissions

Click the "+ ADD PERMISSIONS" button:

First, filter out only the roles we'll need by clicking into "Filter permissions by role" and selecting "BigQuery Admin":
Now go down to "Filter table" and select all of the necessary permissions below.
**Do not hit ADD until you select all of them**

Filter for "Dataset" and add:

bigquery.datasets.get
bigquery.datasets.create

Filter for "tables" and add

bigquery.tables.create
bigquery.tables.delete
bigquery.tables.get
bigquery.tables.getData
bigquery.tables.list
bigquery.tables.update
bigquery.tables.updateData (*note updateData might be on page 2)

Filter for "jobs" and add

bigquery.jobs.create
bigquery.jobs.get
bigquery.jobs.list
bigquery.jobs.update

Click "Add" to add the selected assigned permissions.

Step 5: Confirm the permissions

Look over the list and double-check that everything has been assigned

Step 6: Click "Create"

Create a Service Account

Now create the service account and use the role you just created: https://docs.narrator.ai/docs/bigquery

You can now use your new service account with Narrator.

📘

STOP HERE

At this point, you've done everything you need and can continue with the steps here https://docs.narrator.ai/docs/bigquery to add the new service account to Narrator.

Dataset Specific Permissions

This is for folks who'd like to grant Dataset specific permissions: https://cloud.google.com/bigquery/docs/dataset-access-controls#controlling_access_to_a_dataset

Follow the steps above for creating a service account, but ONLY with the following project roles:

bigquery.jobs.create
bigquery.jobs.get
bigquery.jobs.list
bigquery.jobs.update

bigquery.datasets.create

📘

Why do we need bigquery.datasets.create?

Narrator uses this permission to create two datasets: narrator and narrator_mv (though these names can be configured on the company settings page).

You can omit bigquery.datasets.create if you create both of these datasets and assign the BigQuery Admin role to the service account for each one (see instructions below)

With your new service account, go to each dataset for the source data that you want Narrator to be able to access and click "Share Dataset":

Then copy that new service account's email (something like "[email protected]") and give it the "BigQuery Data Owner" permission.

❗️

Note about permissions on Views vs Tables

If you'd like Narrator to be able to access a view, make sure to add the BigQuery Data Owner permission to any Dataset that is used by a view you want Narrator to access.

Then, create new datasets for narrator_mv and narrator and give the service account "BigQuery Admin" access to those two new datasets.

Click "Add", and then "Done" at the bottom of the window.

Note: we'll be creating all the Narrator derived tables inside the narrator and narrator_mvs datasets respectively. If you prefer to use different dataset names, make sure to update that in your Company Settings from the Narrator UI: https://portal.narrator.ai/COMPANY_SLUG/company

📘

STOP HERE

At this point, you've done everything you need and can continue with the steps here https://docs.narrator.ai/docs/bigquery to add the new service account to Narrator.