Google BigQuery Reference
Authentication options and data type handling for BigQuery connections.
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.
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> |