With the Conversational Analytics API, you can connect a data agent to BigQuery to let users ask questions about your data in natural language and receive answers as text, tables, or charts.

To configure your data sources, define references to BigQuery tables, graphs, or both by using either the Python SDK or HTTP. You then provide these references when you create a persistent data agent or send a stateless chat query with inline context, as described in [Build a data agent using HTTP](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-http.md.txt) and [Build a data agent using the Python SDK](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-sdk.md.txt).

## Before you begin

Before you connect a data agent to BigQuery, complete the following tasks:

1. In your Google Cloud project, [enable the required APIs](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/enable-the-api.md.txt) for the Conversational Analytics API and BigQuery.
2. Verify that you have the [required Identity and Access Management (IAM) roles](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/connect-bigquery.md.txt#required-roles).
3. Ensure that you have access to the BigQuery datasets, tables, or graphs that you want to query.

### Required roles


To get the permissions that
you need to connect a data agent to BigQuery and run queries,

ask your administrator to grant you the
following IAM roles:

- Create or manage data agents:
  - [Gemini Data Analytics Data Agent Creator](https://docs.cloud.google.com/iam/docs/roles-permissions/geminidataanalytics.md.txt#geminidataanalytics.dataAgentCreator) (`roles/geminidataanalytics.dataAgentCreator`) on your project
  - [Gemini Data Analytics Data Agent Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/geminidataanalytics.md.txt#geminidataanalytics.dataAgentEditor) (`roles/geminidataanalytics.dataAgentEditor`) on your project
- Chat with data agents:
  - [Gemini Data Analytics Data Agent User](https://docs.cloud.google.com/iam/docs/roles-permissions/geminidataanalytics.md.txt#geminidataanalytics.dataAgentUser) (`roles/geminidataanalytics.dataAgentUser`) on your project
  - [Gemini for Google Cloud User](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudaicompanion.md.txt#cloudaicompanion.user) (`roles/cloudaicompanion.user`) on your project
- Send stateless chat queries with inline context: [Gemini Data Analytics Stateless Chat User](https://docs.cloud.google.com/iam/docs/roles-permissions/geminidataanalytics.md.txt#geminidataanalytics.dataAgentStatelessUser) (`roles/geminidataanalytics.dataAgentStatelessUser`) on your project
- Run BigQuery queries: [BigQuery Job User](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.jobUser) (`roles/bigquery.jobUser`) on your billing project
- Read BigQuery data: [BigQuery Data Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.dataViewer) (`roles/bigquery.dataViewer`) on your dataset, table, or graph


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Connect to BigQuery tables

To connect to BigQuery tables, you specify table references in your data source configuration and attach them to a `published_context` object. You can connect to multiple tables across different projects and datasets. If you're sending stateless chat queries without creating a persistent data agent, you can provide this data source configuration in the `inline_context` field of your request instead.

> [!NOTE]
> To connect to Lakehouse tables that use the Apache Iceberg REST catalog or an external catalog, use the four-part [P.C.N.T syntax](https://docs.cloud.google.com/lakehouse/docs/about-iceberg-rest-catalog-endpoint.md.txt#pcnt). When configuring table references for Lakehouse tables, specify `catalog.namespace` for the dataset ID.

The following sample code connects to two tables and configures a `published_context` object with the data sources. The first table (`TABLE_ID_1`) defines optional custom descriptions for the table and a column to provide additional semantic context, while the second table (`TABLE_ID_2`) relies on automatic schema discovery:

### Python SDK

```python
# Table 1: Define a table reference with custom table and column descriptions
table_reference_1 = geminidataanalytics.BigQueryTableReference()
table_reference_1.project_id = "PROJECT_ID"
table_reference_1.dataset_id = "DATASET_ID"
table_reference_1.table_id = "TABLE_ID_1"
# Optional: Provide semantic descriptions for the table and specific columns
table_reference_1.schema = geminidataanalytics.Schema()
table_reference_1.schema.description = "TABLE_DESCRIPTION"
table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="COLUMN_NAME",
        description="COLUMN_DESCRIPTION",
    )
]

# Table 2: Minimal table reference that relies on automatic schema discovery
table_reference_2 = geminidataanalytics.BigQueryTableReference()
table_reference_2.project_id = "PROJECT_ID"
table_reference_2.dataset_id = "DATASET_ID"
table_reference_2.table_id = "TABLE_ID_2"

# Combine table references into a data source configuration
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [
    table_reference_1,
    table_reference_2,
]

# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references
```

Replace the sample values as follows:

- <var class="readonly" translate="no">PROJECT_ID</var>: The ID of the Google Cloud project that contains your BigQuery dataset and tables. To connect to a [public dataset](https://docs.cloud.google.com/bigquery/public-data.md.txt), specify `bigquery-public-data`.
- <var class="readonly" translate="no">DATASET_ID</var>: The ID of the BigQuery dataset that contains your tables. For example, `san_francisco`.
- <var class="readonly" translate="no">TABLE_ID_1</var> and <var class="readonly" translate="no">TABLE_ID_2</var>: The IDs of the BigQuery tables to connect. For example, `street_trees`.
- <var class="readonly" translate="no">TABLE_DESCRIPTION</var>: An optional description of the table's content and purpose.
- <var class="readonly" translate="no">COLUMN_NAME</var>: The name of a column in the table for which you're providing an optional description.
- <var class="readonly" translate="no">COLUMN_DESCRIPTION</var>: An optional description of the column's content and purpose.

### HTTP

```python
bigquery_data_sources = {
    "bq": {
        "tableReferences": [
            # Table 1: Define a table reference with custom table and column descriptions
            {
                "projectId": "PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID_1",
                # Optional: Provide semantic descriptions for the table and specific columns
                "schema": {
                    "description": "TABLE_DESCRIPTION",
                    "fields": [
                        {
                            "name": "COLUMN_NAME",
                            "description": "COLUMN_DESCRIPTION",
                        }
                    ],
                },
            },
            # Table 2: Minimal table reference that relies on automatic schema discovery
            {
                "projectId": "PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID_2",
            },
        ],
    },
}

# Attach the data source to published context
published_context = {
    "datasourceReferences": bigquery_data_sources,
}
```

Replace the sample values as follows:

- <var class="readonly" translate="no">PROJECT_ID</var>: The ID of the Google Cloud project that contains your BigQuery dataset and tables. To connect to a [public dataset](https://docs.cloud.google.com/bigquery/public-data.md.txt), specify `bigquery-public-data`.
- <var class="readonly" translate="no">DATASET_ID</var>: The ID of the BigQuery dataset that contains your tables. For example, `san_francisco`.
- <var class="readonly" translate="no">TABLE_ID_1</var> and <var class="readonly" translate="no">TABLE_ID_2</var>: The IDs of the BigQuery tables to connect. For example, `street_trees`.
- <var class="readonly" translate="no">TABLE_DESCRIPTION</var>: An optional description of the table's content and purpose.
- <var class="readonly" translate="no">COLUMN_NAME</var>: The name of a column in the table for which you're providing an optional description.
- <var class="readonly" translate="no">COLUMN_DESCRIPTION</var>: An optional description of the column's content and purpose.

While there are no hard limits on the number of tables that you can connect, connecting a large number of tables or tables across unrelated domains can reduce query accuracy---particularly for queries that require complex joins---or exceed the model's input token limit. Configure each data agent with related tables for a specific use case.

To provide additional context for your tables, such as synonyms, tags, example queries, or user-defined functions, see [Define data agent context for BigQuery data sources](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/data-agent-authored-context-bq.md.txt).

## Connect to BigQuery Graph

You can connect to graphs by using [BigQuery Graph](https://docs.cloud.google.com/bigquery/docs/graph-overview.md.txt). You can configure a data agent to query graphs alone or to combine graph and table references in the same data source configuration. To connect, provide one or more graph references in the `property_graph_references` field (for the Python SDK) or the `propertyGraphReferences` field (for HTTP).

> [!NOTE]
> Depending on your graph schema and the question that is asked, the Conversational Analytics API queries a graph by using either Graph Query Language (GQL) or the [`GRAPH_EXPAND`](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/graph-sql-queries.md.txt#graph_expand) table-valued function in SQL:
>
> - GQL queries require a [BigQuery Enterprise or Enterprise Plus edition](https://docs.cloud.google.com/bigquery/docs/editions-intro.md.txt) reservation. In projects with on-demand pricing, GQL queries fail with an error and aren't retried with `GRAPH_EXPAND`.
> - `GRAPH_EXPAND` queries can run with on-demand pricing but aren't supported for all graphs. For requirements and limitations, see the [BigQuery Graph overview](https://docs.cloud.google.com/bigquery/docs/graph-overview.md.txt) and [`GRAPH_EXPAND`](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/graph-sql-queries.md.txt#graph_expand).

The following sample code defines a connection to a graph and configures a `published_context` object:

### Python SDK

```python
# Define a BigQuery Graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"

# Combine references into a data source configuration
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]

# Attach the data source to published context
published_context = geminidataanalytics.Context()
published_context.datasource_references = datasource_references
```

Replace the sample values as follows:

- <var class="readonly" translate="no">GRAPH_PROJECT_ID</var>: The ID of the Google Cloud project that contains your BigQuery graph.
- <var class="readonly" translate="no">GRAPH_DATASET_ID</var>: The ID of the BigQuery dataset that contains your graph. For example, `financial_data`.
- <var class="readonly" translate="no">GRAPH_ID</var>: The ID of the BigQuery graph. For example, `FinGraph`.

### HTTP

```python
bigquery_data_sources = {
    "bq": {
        "propertyGraphReferences": [
            # Define a BigQuery Graph reference
            {
                "projectId": "GRAPH_PROJECT_ID",
                "datasetId": "GRAPH_DATASET_ID",
                "propertyGraphId": "GRAPH_ID",
            },
        ],
    },
}

# Attach the data source to published context
published_context = {
    "datasourceReferences": bigquery_data_sources,
}
```

Replace the sample values as follows:

- <var class="readonly" translate="no">GRAPH_PROJECT_ID</var>: The ID of the Google Cloud project that contains your BigQuery graph.
- <var class="readonly" translate="no">GRAPH_DATASET_ID</var>: The ID of the BigQuery dataset that contains your graph. For example, `financial_data`.
- <var class="readonly" translate="no">GRAPH_ID</var>: The ID of the BigQuery graph. For example, `FinGraph`.

To query both tables and graphs with the same data agent, include both `table_references` and `property_graph_references` (Python SDK) or `tableReferences` and `propertyGraphReferences` (HTTP) in your `bq` data source configuration.

## What's next

- [Define data agent context for BigQuery data sources](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/data-agent-authored-context-bq.md.txt) to improve your agent's performance with descriptions, synonyms, and example queries.
- Create a data agent or send stateless chat queries with your data source configuration, as described in [Build a data agent using HTTP](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-http.md.txt) or [Build a data agent using the Python SDK](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-sdk.md.txt).