# Give GOAT access to your data

Let GOAT read the BigQuery data and files you choose.

GOAT reads your data as its own service account, and an install gives that account no access to your data. You grant it, one dataset or bucket at a time. 

## Before you start

- You need permission to change access on the projects, datasets, and buckets involved.
- You need the address of GOAT's service account. It looks like `goat-platform@your-project.iam.gserviceaccount.com`, where `goat` is your install's name. Whoever installed GOAT can give it to you.

## The grants GOAT needs

| To let GOAT | Grant this role | On |
|---|---|---|
| Browse a project's datasets, tables, and columns | BigQuery Metadata Viewer (`roles/bigquery.metadataViewer`) | The project. The install's own project already has it. |
| Read a dataset's tables | BigQuery Data Viewer (`roles/bigquery.dataViewer`) | The dataset. |
| List and read a bucket's files | Storage Object Viewer (`roles/storage.objectViewer`) | The bucket. |

The first grant lets GOAT see names and columns, and also view and routine definitions and who has access to each dataset and table. It reads no table data.

Grant per dataset and per bucket. The same roles on a whole project work too, but give GOAT every dataset or bucket in it.

## Give the grants

In the commands below, replace `SA` with GOAT's service account address.

To let GOAT browse another project:

```sh
gcloud projects add-iam-policy-binding <project> \
  --member="serviceAccount:SA" --role=roles/bigquery.metadataViewer
```

To let GOAT read one dataset:

```sh
bq query --project_id=<project> --location=<dataset location> --nouse_legacy_sql \
  'GRANT `roles/bigquery.dataViewer` ON SCHEMA `<project>`.<dataset> TO "serviceAccount:SA"'
```

The `GRANT` runs as a query, so you also need permission to run queries in that project.

To let GOAT read one bucket:

```sh
gcloud storage buckets add-iam-policy-binding gs://<bucket> \
  --member="serviceAccount:SA" --role=roles/storage.objectViewer
```

A change of access can take a few minutes to reach GOAT. Wait, then try again.

## When a grant is missing

GOAT says which access it lacks, and where:

| Where | What GOAT shows | What to grant |
|---|---|---|
| Picking a table, or a project's tables | "The install cannot read that location." and "Grant roles/bigquery.metadataViewer on ..." | Metadata Viewer on that project. |
| Browsing another project | "Nothing visible in this project" | Metadata Viewer on that project. BigQuery shows an empty list both when the project has no datasets and when GOAT cannot see them. |
| Checking a table | "Grant roles/bigquery.dataViewer on ..." | Data Viewer on that dataset. |
| Picking files | "Grant roles/storage.objectViewer on ..." | Storage Object Viewer on that bucket. |
| A load that fails | "We do not have permission to read the source. Check its access, then try again." | The grant for that table or bucket. |

If GOAT says "No grant fixes this", the problem is how the table or view is defined, not access. Check that the view's own query runs in BigQuery.

## Removing access

Remove a grant the same way you gave it. What happens next depends on the dataset:

- Datasets GOAT reads in place (Live connect tables, and files read in place) stop showing their charts at once.
- Datasets GOAT copied (managed copies, and uploaded files) keep the copy in the install's own `goat` BigQuery dataset, and their charts keep showing it. Every reload fails from then on.

To stop a managed copy from showing data, delete the dataset in GOAT.

## Common problems

| What you see | What to check |
|---|---|
| You gave a grant and GOAT still says it lacks it | Wait a few minutes, then try again. Check the address of the service account. |
| "GOAT cannot find" a table | The project, dataset, and table names, and that the service account can read it. |
| Charts on a Live connect dataset fail after a change in BigQuery | The table moved, or a grant was removed. |
