Create a BigQuery connection

Learn more about creating a BigQuery connection for zero-copy integration from Google BigQuery.

Reltio requires a BigQuery connection to locate external interaction data and authenticate with Google Cloud. The Create BigQuery connection creates a named connection configuration in Reltio with the Google Cloud project, dataset, location, and service account email. Reltio authenticates through service account impersonation and does not accept or store a service account key.

HTTP method and endpoint

Use the following HTTP method and endpoint path to create the BigQuery connection.

POST {platformUrl}/reltio/api/tenants/{tenantId}/interactions/database-configs/

Replace {platformUrl} with your Reltio platform base URL and {tenantId} with your tenant ID.

The following table describes the endpoint path parameter.


Parameter	Type	Required	Description
`tenantId`	String	Yes	Identifier of the Reltio tenant where you want to create the BigQuery connection. Example: `ce5627DYnQ6abcD`

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<access_token>`	Yes
`Content-Type`	`application/json`	Yes

Request body

The following table describes the request body parameters required to create the BigQuery connection and specify the Google Cloud service account used for impersonation.


Parameter	Type	Required	Description	Accepted values / Default
`connection_name`	String	Yes	Unique name for the BigQuery connection within the tenant.	Example: `bigquery-primary`
`database_type`	String	Yes	Database type for the connection.	`BIGQUERY`
`connection_purposes`	Array of strings	Yes	Zero-copy capabilities that use the connection.	Must include `ZERO_COPY_INTERACTIONS`.
`bigquery_config`	Object	Yes	BigQuery-specific connection settings.	—
`bigquery_config.project_id`	String	Yes	Google Cloud project that contains the BigQuery source and runs the queries.	6–30 characters. Must start with a lowercase letter, contain lowercase letters, digits, or hyphens, and not end with a hyphen.
`bigquery_config.dataset`	String	Yes	BigQuery dataset containing the interaction tables or views.	Example: `reltio_interactions`
`bigquery_config.location`	String	No	BigQuery dataset location.	Example: `US`
`bigquery_config.service_account_email`	String	Yes	Email address of the Google Cloud service account that Reltio uses through service account impersonation.	Example: `reltio-zerocopy-sa@acme-analytics-prod.iam.gserviceaccount.com`
`bigquery_config.connection_properties`	Object	No	Optional BigQuery connection properties.	—
`bigquery_config.connection_properties.queryTimeout`	Long	No	Maximum time, in milliseconds, that Reltio waits for a BigQuery query to complete.	Default: `3000`

Example request

Use the following example to see how a complete request is structured.

POST {platformUrl}/reltio/api/tenants/{tenantId}/interactions/database-configs/
{
  "connection_name": "bigquery-primary",
  "database_type": "BIGQUERY",
  "connection_purposes": ["ZERO_COPY_INTERACTIONS"],
  "bigquery_config": {
    "project_id": "acme-analytics-prod",
    "dataset": "reltio_interactions",
    "location": "US",
    "service_account_email": "bigquery-reader@acme-analytics-prod.iam.gserviceaccount.com",
    "connection_properties": {
      "queryTimeout": 3000
}
  }
}

Response body

The following table describes the fields returned in the response body when the request succeeds.


Field	Type	Description
`successful`	Boolean	Indicates whether Reltio created the BigQuery connection.
`result`	Object	Contains information about the saved connection.
`result.connection_name`	String	Name of the saved BigQuery connection.
`result.connection_id`	String	Generated identifier of the created connection.
`result.tenant_id`	String	Identifier of the tenant containing the connection.
`result.database_type`	String	Database type. The value is `BIGQUERY`.
`result.connection_purposes`	Array	Zero copy capabilities that use the connection.
`result.bigquery_config`	Object	Saved BigQuery connection settings.
`result.status`	String	Status of the saved connection. Possible values: `PENDING` (the connection is created but not tested yet) and `ACTIVE` (the connection passed the connection test).
`result.created_time`	String	Timestamp when Reltio created the connection.
`result.updated_time`	String	Timestamp when Reltio last updated the connection.

Example response

The following example shows a successful response for a saved BigQuery connection.

{
  "successful": true,
  "result": {
    "connection_id": "b0f4c2de-7a15-4b0e-9d1a-5c8e3f2a7b41",
    "connection_name": "bigquery-primary",
    "tenant_id": "exampleTenant",
    "database_type": "BIGQUERY",
    "connection_purposes": [
      "ZERO_COPY_INTERACTIONS"
    ],
    "bigquery_config": {
      "project_id": "acme-analytics-prod",
      "dataset": "reltio_interactions",
      "location": "US",
      "service_account_email": "bigquery-reader@acme-analytics-prod.iam.gserviceaccount.com",
      "connection_properties": {
        "queryTimeout": 3000
      }
    },
    "status": "Successful",
    "created_time": "2026-10-09T10:00:00",
    "updated_time": "2026-10-09T10:00:00"
  }
}

After creating the connection, test the BigQuery connection.

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Error code	Description	Recommended action
`400 Bad Request`	`DS_BIGQUERY_PROJECT_ID_REQUIRED`	`project_id` is missing.	Provide the Google Cloud project ID.
	`DS_BIGQUERY_INVALID_PROJECT_ID`	`project_id` has an invalid format.	Provide a valid lowercase Google Cloud project ID.
	`DS_BIGQUERY_DATASET_REQUIRED`	`dataset` is missing.	Provide the BigQuery dataset name.
	`DS_BIGQUERY_SERVICE_ACCOUNT_REQUIRED`	`service_account_email` is missing.	Provide the Google Cloud service account email.
`409 Conflict`	`DS_CONNECTION_NAME_ALREADY_EXISTS`	The connection name already exists in the tenant.	Choose another connection name.
	`DS_BIGQUERY_ACTIVE_CONNECTION_EXISTS`	An active BigQuery connection already uses the requested purpose.	Update the existing connection.
	`DS_BIGQUERY_EXPIRED_CONNECTION_EXISTS`	An expired BigQuery connection already uses the requested purpose.	Update or remove the expired connection.

Unify and manage your data