bigframes.pandas.DataFrame.to_gbq

DataFrame.to_gbq(destination_table: str | None = None, *, if_exists: Literal['fail', 'replace', 'append'] | None = None, index: bool = True, ordering_id: str | None = None, clustering_columns: Index | Iterable[Hashable] = (), labels: dict[str, str] = {}) → str

Write a DataFrame to a BigQuery table.

Examples:

>>> import bigframes.pandas as bpd

Write a DataFrame to a BigQuery table.

>>> df = bpd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> # destination_table = PROJECT_ID + "." + DATASET_ID + "." + TABLE_NAME
>>> df.to_gbq("bigframes-dev.birds.test-numbers", if_exists="replace")
'bigframes-dev.birds.test-numbers'

Write a DataFrame to a temporary BigQuery table in the anonymous dataset.

>>> df = bpd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
>>> destination = df.to_gbq(ordering_id="ordering_id")
>>> # The table created can be read outside of the current session.
>>> bpd.close_session()  # Optional, to demonstrate a new session.
>>> bpd.read_gbq(destination, index_col="ordering_id")
             col1  col2
ordering_id
0               1     3
1               2     4

[2 rows x 2 columns]

Write a DataFrame to a BigQuery table with clustering columns:

>>> df = bpd.DataFrame({'col1': [1, 2], 'col2': [3, 4], 'col3': [5, 6]})
>>> clustering_cols = ['col1', 'col3']
>>> df.to_gbq(
...             "bigframes-dev.birds.test-clusters",
...             if_exists="replace",
...             clustering_columns=clustering_cols,
...           )
'bigframes-dev.birds.test-clusters'

Parameters:

• destination_table (Optional[str]) –

  Name of table to be written, in the form dataset.tablename or project.dataset.tablename.

  If no destination_table is set, a new temporary table is created in the BigQuery anonymous dataset.

• if_exists (Optional[str]) –

  Behavior when the destination table exists. When destination_table is set, this defaults to 'fail'. When destination_table is not set, this field is not applicable. A new table is always created. Value can be one of:

  'fail'

  If table exists raise pandas_gbq.gbq.TableCreationError.

  'replace'

  If table exists, drop it, recreate it, and insert data.

  'append'

  If table exists, insert data. Create if does not exist.

• index (bool. default True) – whether write row names (index) or not.

• ordering_id (Optional[str], default None) – If set, write the ordering of the DataFrame as a column in the result table with this name.

• clustering_columns (Union[pd.Index, Iterable[Hashable]], default ()) – Specifies the columns for clustering in the BigQuery table. The order of columns in this list is significant for clustering hierarchy. Index columns may be included in clustering if the index parameter is set to True, and their names are specified in this. These index columns, if included, precede DataFrame columns in the clustering order. The clustering order within the Index/DataFrame columns follows the order specified in clustering_columns.

• labels (dict[str, str], default None) – Specifies table labels within BigQuery

Returns:

The fully-qualified ID for the written table, in the form project.dataset.tablename.

Return type:

str

Raises:

• ValueError – If an invalid value is provided for if_exists when destination_table is None. None or replace are the only valid values for if_exists.

• ValueError – If an invalid value is provided for destination_table that is not one of datasetID.tableId or projectId.datasetId.tableId.

• ValueError – If an invalid value is provided for if_exists that is not one of fail, replace, or append.