Skip to main content

tables

Creates, updates, deletes, gets or lists a tables resource.

Overview​

Nametables
TypeResource
Idgoogle.bigquery.tables

Fields​

The following fields are returned by SELECT queries:

Successful response

NameDatatypeDescription
idstringOutput only. An opaque ID uniquely identifying the table.
biglakeConfigurationobjectOptional. Specifies the configuration of a BigQuery table for Apache Iceberg. (id: BigLakeConfiguration)
cloneDefinitionobjectOutput only. Contains information about the clone. This value is set via the clone operation. (id: CloneDefinition)
clusteringobjectClustering specification for the table. Must be specified with time-based partitioning, data in the table will be first partitioned and subsequently clustered. (id: Clustering)
creationTimestring (int64)Output only. The time when this table was created, in milliseconds since the epoch.
defaultCollationstringOptional. Defines the default collation specification of new STRING fields in the table. During table creation or update, if a STRING field is added to this table without explicit collation specified, then the table inherits the table default collation. A change to this field affects only fields added afterwards, and does not alter the existing fields. The following values are supported: * 'und:ci': undetermined locale, case insensitive. * '': empty string. Default to case-sensitive behavior.
defaultRoundingModestringOptional. Defines the default rounding mode specification of new decimal fields (NUMERIC OR BIGNUMERIC) in the table. During table creation or update, if a decimal field is added to this table without an explicit rounding mode specified, then the field inherits the table default rounding mode. Changing this field doesn't affect existing fields.
descriptionstringOptional. A user-friendly description of this table.
encryptionConfigurationobjectCustom encryption configuration (e.g., Cloud KMS keys). (id: EncryptionConfiguration)
etagstringOutput only. A hash of this resource.
expirationTimestring (int64)Optional. The time when this table expires, in milliseconds since the epoch. If not present, the table will persist indefinitely. Expired tables will be deleted and their storage reclaimed. The defaultTableExpirationMs property of the encapsulating dataset can be used to set a default expirationTime on newly created tables.
externalCatalogTableOptionsobjectOptional. Options defining open source compatible table. (id: ExternalCatalogTableOptions)
externalDataConfigurationobjectOptional. Describes the data format, location, and other properties of a table stored outside of BigQuery. By defining these properties, the data source can then be queried as if it were a standard BigQuery table. (id: ExternalDataConfiguration)
friendlyNamestringOptional. A descriptive name for this table.
kindstringThe type of resource ID. (default: bigquery#table)
labelsobjectThe labels associated with this table. You can use these to organize and group your tables. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter and each label in the list must have a different key.
lastModifiedTimestring (uint64)Output only. The time when this table was last modified, in milliseconds since the epoch.
locationstringOutput only. The geographic location where the table resides. This value is inherited from the dataset.
managedTableTypestringOptional. If set, overrides the default managed table type configured in the dataset.
materializedViewobjectOptional. The materialized view definition. (id: MaterializedViewDefinition)
materializedViewStatusobjectOutput only. The materialized view status. (id: MaterializedViewStatus)
maxStalenessstringOptional. The maximum staleness of data that could be returned when the table (or stale MV) is queried. Staleness encoded as a string encoding of sql IntervalValue type.
modelobjectDeprecated. (id: ModelDefinition)
numActiveLogicalBytesstring (int64)Output only. Number of logical bytes that are less than 90 days old.
numActivePhysicalBytesstring (int64)Output only. Number of physical bytes less than 90 days old. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
numBytesstring (int64)Output only. The size of this table in logical bytes, excluding any data in the streaming buffer.
numCurrentPhysicalBytesstring (int64)Output only. Number of physical bytes used by current live data storage. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
numLongTermBytesstring (int64)Output only. The number of logical bytes in the table that are considered "long-term storage".
numLongTermLogicalBytesstring (int64)Output only. Number of logical bytes that are more than 90 days old.
numLongTermPhysicalBytesstring (int64)Output only. Number of physical bytes more than 90 days old. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
numPartitionsstring (int64)Output only. The number of partitions present in the table or materialized view. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
numPhysicalBytesstring (int64)Output only. The physical size of this table in bytes. This includes storage used for time travel.
numRowsstring (uint64)Output only. The number of rows of data in this table, excluding any data in the streaming buffer.
numTimeTravelPhysicalBytesstring (int64)Output only. Number of physical bytes used by time travel storage (deleted or changed data). This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
numTotalLogicalBytesstring (int64)Output only. Total number of logical bytes in the table or materialized view.
numTotalPhysicalBytesstring (int64)Output only. The physical size of this table in bytes. This also includes storage used for time travel. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
partitionDefinitionobjectOptional. The partition information for all table formats, including managed partitioned tables, hive partitioned tables, iceberg partitioned, and metastore partitioned tables. This field is only populated for metastore partitioned tables. For other table formats, this is an output only field. (id: PartitioningDefinition)
rangePartitioningobjectIf specified, configures range partitioning for this table. (id: RangePartitioning)
replicasarrayOptional. Output only. Table references of all replicas currently active on the table.
requirePartitionFilterbooleanOptional. If set to true, queries over this table require a partition filter that can be used for partition elimination to be specified. (default: false)
resourceTagsobject[Optional] The tags associated with this table. Tag keys are globally unique. See additional information on tags. An object containing a list of "key": value pairs. The key is the namespaced friendly name of the tag key, e.g. "12345/environment" where 12345 is parent id. The value is the friendly short name of the tag value, e.g. "production".
restrictionsobjectOptional. Output only. Restriction config for table. If set, restrict certain accesses on the table based on the config. See Data egress for more details. (id: RestrictionConfig)
schemaobjectOptional. Describes the schema of this table. (id: TableSchema)
selfLinkstringOutput only. A URL that can be used to access this resource again.
snapshotDefinitionobjectOutput only. Contains information about the snapshot. This value is set via snapshot creation. (id: SnapshotDefinition)
streamingBufferobjectOutput only. Contains information regarding this table's streaming buffer, if one is present. This field will be absent if the table is not being streamed to or if there is no data in the streaming buffer. (id: Streamingbuffer)
tableConstraintsobjectOptional. Tables Primary Key and Foreign Key information (id: TableConstraints)
tableReferenceobjectRequired. Reference describing the ID of this table. (id: TableReference)
tableReplicationInfoobjectOptional. Table replication info for table created AS REPLICA DDL like: CREATE MATERIALIZED VIEW mv1 AS REPLICA OF src_mv (id: TableReplicationInfo)
timePartitioningobjectIf specified, configures time-based partitioning for this table. (id: TimePartitioning)
typestringOutput only. Describes the table type. The following values are supported: * TABLE: A normal BigQuery table. * VIEW: A virtual table defined by a SQL query. * EXTERNAL: A table that references data stored in an external storage system, such as Google Cloud Storage. * MATERIALIZED_VIEW: A precomputed view defined by a SQL query. * SNAPSHOT: An immutable BigQuery table that preserves the contents of a base table at a particular time. See additional information on table snapshots. The default value is TABLE.
viewobjectOptional. The view definition. (id: ViewDefinition)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectprojectId, +datasetId, +tableIdselectedFields, viewGets the specified table resource by table ID. This method does not return the data in the table, it only returns the table resource, which describes the structure of this table.
listselectprojectId, +datasetIdmaxResults, pageTokenLists all tables in the specified dataset. Requires the READER dataset role.
insertinsertprojectId, +datasetIdCreates a new, empty table in the dataset.
patchupdateprojectId, +datasetId, +tableIdautodetect_schemaUpdates information in an existing table. The update method replaces the entire table resource, whereas the patch method only replaces fields that are provided in the submitted table resource. This method supports RFC5789 patch semantics.
updatereplaceprojectId, +datasetId, +tableIdautodetect_schemaUpdates information in an existing table. The update method replaces the entire Table resource, whereas the patch method only replaces fields that are provided in the submitted Table resource.
deletedeleteprojectId, +datasetId, +tableIdDeletes the table specified by tableId from the dataset. If the table contains data, all the data will be deleted.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
+datasetIdstring
+tableIdstring
projectIdstring
autodetect_schemaboolean
maxResultsinteger (uint32)
pageTokenstring
selectedFieldsstring
viewstring

SELECT examples​

Gets the specified table resource by table ID. This method does not return the data in the table, it only returns the table resource, which describes the structure of this table.

SELECT
id,
biglakeConfiguration,
cloneDefinition,
clustering,
creationTime,
defaultCollation,
defaultRoundingMode,
description,
encryptionConfiguration,
etag,
expirationTime,
externalCatalogTableOptions,
externalDataConfiguration,
friendlyName,
kind,
labels,
lastModifiedTime,
location,
managedTableType,
materializedView,
materializedViewStatus,
maxStaleness,
model,
numActiveLogicalBytes,
numActivePhysicalBytes,
numBytes,
numCurrentPhysicalBytes,
numLongTermBytes,
numLongTermLogicalBytes,
numLongTermPhysicalBytes,
numPartitions,
numPhysicalBytes,
numRows,
numTimeTravelPhysicalBytes,
numTotalLogicalBytes,
numTotalPhysicalBytes,
partitionDefinition,
rangePartitioning,
replicas,
requirePartitionFilter,
resourceTags,
restrictions,
schema,
selfLink,
snapshotDefinition,
streamingBuffer,
tableConstraints,
tableReference,
tableReplicationInfo,
timePartitioning,
type,
view
FROM google.bigquery.tables
WHERE projectId = '{{ projectId }}' -- required
AND +datasetId = '{{ +datasetId }}' -- required
AND +tableId = '{{ +tableId }}' -- required
AND selectedFields = '{{ selectedFields }}'
AND view = '{{ view }}';

INSERT examples​

Creates a new, empty table in the dataset.

INSERT INTO google.bigquery.tables (
data__biglakeConfiguration,
data__clustering,
data__defaultCollation,
data__defaultRoundingMode,
data__description,
data__encryptionConfiguration,
data__expirationTime,
data__externalCatalogTableOptions,
data__externalDataConfiguration,
data__friendlyName,
data__kind,
data__labels,
data__managedTableType,
data__materializedView,
data__maxStaleness,
data__model,
data__partitionDefinition,
data__rangePartitioning,
data__requirePartitionFilter,
data__resourceTags,
data__schema,
data__tableConstraints,
data__tableReference,
data__tableReplicationInfo,
data__timePartitioning,
data__view,
projectId,
+datasetId
)
SELECT 
'{{ biglakeConfiguration }}',
'{{ clustering }}',
'{{ defaultCollation }}',
'{{ defaultRoundingMode }}',
'{{ description }}',
'{{ encryptionConfiguration }}',
'{{ expirationTime }}',
'{{ externalCatalogTableOptions }}',
'{{ externalDataConfiguration }}',
'{{ friendlyName }}',
'{{ kind }}',
'{{ labels }}',
'{{ managedTableType }}',
'{{ materializedView }}',
'{{ maxStaleness }}',
'{{ model }}',
'{{ partitionDefinition }}',
'{{ rangePartitioning }}',
{{ requirePartitionFilter }},
'{{ resourceTags }}',
'{{ schema }}',
'{{ tableConstraints }}',
'{{ tableReference }}',
'{{ tableReplicationInfo }}',
'{{ timePartitioning }}',
'{{ view }}',
'{{ projectId }}',
'{{ +datasetId }}'
RETURNING
id,
biglakeConfiguration,
cloneDefinition,
clustering,
creationTime,
defaultCollation,
defaultRoundingMode,
description,
encryptionConfiguration,
etag,
expirationTime,
externalCatalogTableOptions,
externalDataConfiguration,
friendlyName,
kind,
labels,
lastModifiedTime,
location,
managedTableType,
materializedView,
materializedViewStatus,
maxStaleness,
model,
numActiveLogicalBytes,
numActivePhysicalBytes,
numBytes,
numCurrentPhysicalBytes,
numLongTermBytes,
numLongTermLogicalBytes,
numLongTermPhysicalBytes,
numPartitions,
numPhysicalBytes,
numRows,
numTimeTravelPhysicalBytes,
numTotalLogicalBytes,
numTotalPhysicalBytes,
partitionDefinition,
rangePartitioning,
replicas,
requirePartitionFilter,
resourceTags,
restrictions,
schema,
selfLink,
snapshotDefinition,
streamingBuffer,
tableConstraints,
tableReference,
tableReplicationInfo,
timePartitioning,
type,
view
;

UPDATE examples​

Updates information in an existing table. The update method replaces the entire table resource, whereas the patch method only replaces fields that are provided in the submitted table resource. This method supports RFC5789 patch semantics.

UPDATE google.bigquery.tables
SET 
data__biglakeConfiguration = '{{ biglakeConfiguration }}',
data__clustering = '{{ clustering }}',
data__defaultCollation = '{{ defaultCollation }}',
data__defaultRoundingMode = '{{ defaultRoundingMode }}',
data__description = '{{ description }}',
data__encryptionConfiguration = '{{ encryptionConfiguration }}',
data__expirationTime = '{{ expirationTime }}',
data__externalCatalogTableOptions = '{{ externalCatalogTableOptions }}',
data__externalDataConfiguration = '{{ externalDataConfiguration }}',
data__friendlyName = '{{ friendlyName }}',
data__kind = '{{ kind }}',
data__labels = '{{ labels }}',
data__managedTableType = '{{ managedTableType }}',
data__materializedView = '{{ materializedView }}',
data__maxStaleness = '{{ maxStaleness }}',
data__model = '{{ model }}',
data__partitionDefinition = '{{ partitionDefinition }}',
data__rangePartitioning = '{{ rangePartitioning }}',
data__requirePartitionFilter = {{ requirePartitionFilter }},
data__resourceTags = '{{ resourceTags }}',
data__schema = '{{ schema }}',
data__tableConstraints = '{{ tableConstraints }}',
data__tableReference = '{{ tableReference }}',
data__tableReplicationInfo = '{{ tableReplicationInfo }}',
data__timePartitioning = '{{ timePartitioning }}',
data__view = '{{ view }}'
WHERE 
projectId = '{{ projectId }}' --required
AND +datasetId = '{{ +datasetId }}' --required
AND +tableId = '{{ +tableId }}' --required
AND autodetect_schema = {{ autodetect_schema}}
RETURNING
id,
biglakeConfiguration,
cloneDefinition,
clustering,
creationTime,
defaultCollation,
defaultRoundingMode,
description,
encryptionConfiguration,
etag,
expirationTime,
externalCatalogTableOptions,
externalDataConfiguration,
friendlyName,
kind,
labels,
lastModifiedTime,
location,
managedTableType,
materializedView,
materializedViewStatus,
maxStaleness,
model,
numActiveLogicalBytes,
numActivePhysicalBytes,
numBytes,
numCurrentPhysicalBytes,
numLongTermBytes,
numLongTermLogicalBytes,
numLongTermPhysicalBytes,
numPartitions,
numPhysicalBytes,
numRows,
numTimeTravelPhysicalBytes,
numTotalLogicalBytes,
numTotalPhysicalBytes,
partitionDefinition,
rangePartitioning,
replicas,
requirePartitionFilter,
resourceTags,
restrictions,
schema,
selfLink,
snapshotDefinition,
streamingBuffer,
tableConstraints,
tableReference,
tableReplicationInfo,
timePartitioning,
type,
view;

REPLACE examples​

Updates information in an existing table. The update method replaces the entire Table resource, whereas the patch method only replaces fields that are provided in the submitted Table resource.

REPLACE google.bigquery.tables
SET 
data__biglakeConfiguration = '{{ biglakeConfiguration }}',
data__clustering = '{{ clustering }}',
data__defaultCollation = '{{ defaultCollation }}',
data__defaultRoundingMode = '{{ defaultRoundingMode }}',
data__description = '{{ description }}',
data__encryptionConfiguration = '{{ encryptionConfiguration }}',
data__expirationTime = '{{ expirationTime }}',
data__externalCatalogTableOptions = '{{ externalCatalogTableOptions }}',
data__externalDataConfiguration = '{{ externalDataConfiguration }}',
data__friendlyName = '{{ friendlyName }}',
data__kind = '{{ kind }}',
data__labels = '{{ labels }}',
data__managedTableType = '{{ managedTableType }}',
data__materializedView = '{{ materializedView }}',
data__maxStaleness = '{{ maxStaleness }}',
data__model = '{{ model }}',
data__partitionDefinition = '{{ partitionDefinition }}',
data__rangePartitioning = '{{ rangePartitioning }}',
data__requirePartitionFilter = {{ requirePartitionFilter }},
data__resourceTags = '{{ resourceTags }}',
data__schema = '{{ schema }}',
data__tableConstraints = '{{ tableConstraints }}',
data__tableReference = '{{ tableReference }}',
data__tableReplicationInfo = '{{ tableReplicationInfo }}',
data__timePartitioning = '{{ timePartitioning }}',
data__view = '{{ view }}'
WHERE 
projectId = '{{ projectId }}' --required
AND +datasetId = '{{ +datasetId }}' --required
AND +tableId = '{{ +tableId }}' --required
AND autodetect_schema = {{ autodetect_schema}}
RETURNING
id,
biglakeConfiguration,
cloneDefinition,
clustering,
creationTime,
defaultCollation,
defaultRoundingMode,
description,
encryptionConfiguration,
etag,
expirationTime,
externalCatalogTableOptions,
externalDataConfiguration,
friendlyName,
kind,
labels,
lastModifiedTime,
location,
managedTableType,
materializedView,
materializedViewStatus,
maxStaleness,
model,
numActiveLogicalBytes,
numActivePhysicalBytes,
numBytes,
numCurrentPhysicalBytes,
numLongTermBytes,
numLongTermLogicalBytes,
numLongTermPhysicalBytes,
numPartitions,
numPhysicalBytes,
numRows,
numTimeTravelPhysicalBytes,
numTotalLogicalBytes,
numTotalPhysicalBytes,
partitionDefinition,
rangePartitioning,
replicas,
requirePartitionFilter,
resourceTags,
restrictions,
schema,
selfLink,
snapshotDefinition,
streamingBuffer,
tableConstraints,
tableReference,
tableReplicationInfo,
timePartitioning,
type,
view;

DELETE examples​

Deletes the table specified by tableId from the dataset. If the table contains data, all the data will be deleted.

DELETE FROM google.bigquery.tables
WHERE projectId = '{{ projectId }}' --required
AND +datasetId = '{{ +datasetId }}' --required
AND +tableId = '{{ +tableId }}' --required;