# Google BigQuery Reference

> All BigQuery authentication options and data type mappings.

#  Google BigQuery Reference

Authentication options and data type handling for [BigQuery connections](../connect/bigquery.md).

## Authentication

Authentication uses a Service Account Key or Application Default Credentials (ADC) — including Workload Identity Federation (WIF), the GCE metadata server, and `gcloud auth application-default login`. The account needs the **BigQuery Job User** and **BigQuery Data Viewer** roles.

| Variable | Example | Description |
|---|---|---|
| `DATACONTRACT_BIGQUERY_ACCOUNT_INFO_JSON_PATH` | `~/service-access-key.json` | Service Account key JSON file used by `test`. If unset, ADC/WIF is used. |
| `DATACONTRACT_BIGQUERY_BILLING_PROJECT` | `my-compute-project` | Optional. Project to bill query jobs to. Requires `bigquery.jobUser` on the billing project and `bigquery.dataViewer` on the data project. |

`project` and `dataset` come from the contract's `servers` block. `datacontract import bigquery` always uses ADC — set `GOOGLE_APPLICATION_CREDENTIALS` to point it at a key file.

## Data types

### Importing

`datacontract import bigquery` maps BigQuery types as follows; the original BigQuery type is kept as `physicalType`. An unknown type fails the import with an error.

| BigQuery type | `logicalType` |
|---|---|
| `STRING` | `string` (`maxLength` if declared) |
| `BYTES` | `array` |
| `INTEGER`, `INT64` | `integer` |
| `FLOAT`, `FLOAT64` | `number` |
| `NUMERIC`, `BIGNUMERIC` | `number` (precision/scale as custom properties) |
| `BOOLEAN`, `BOOL` | `boolean` |
| `TIMESTAMP`, `DATETIME` | `timestamp` |
| `DATE` | `date` |
| `TIME` | `time` |
| `GEOGRAPHY`, `JSON` | `object` |
| `INTERVAL` | `string` |
| `RECORD`, `STRUCT` | `object` with nested `properties` |
| `RANGE` | `array` with typed `items` |
| any type with mode `REPEATED` | `array` with typed `items` |

Fields with mode `REQUIRED` become `required: true`. Tables, external tables, and snapshots become schema `physicalType: table`; views and materialized views become `view`.

### Testing

BigQuery supports **native type introspection**: the declared `physicalType` is checked against the actual column type from the BigQuery API. Timezone variants of timestamps are interchangeable; parameters (precision, length) are only enforced when the contract declares them. If the `physicalType` cannot be interpreted as a BigQuery type, the check falls back to the logical type category comparison.

{/* AUTOGENERATED TYPE MAPPING: do not edit by hand; regenerate with update_reference_types.py */}

### Logical type mapping

When no `physicalType` is declared, the CLI derives the native type from the `logicalType` — for example in `datacontract export sql` and the dbt exports. This table is generated from the converter in the CLI's code:

| `logicalType` | BigQuery type |
|---|---|
| `string` | `STRING` |
| `integer` | `INTEGER` |
| `number` | `NUMERIC` |
| `boolean` | `BOOL` |
| `date` | `DATE` |
| `timestamp` | `TIMESTAMP` |
| `time` | `TIME` |
| `object` | `STRUCT<>` |
| `array` | `ARRAY<STRING>` |

{/* END AUTOGENERATED TYPE MAPPING */}