Hide
BigQuery

Tables

A table is a part of a dataset. For more information, see Tables.

For a list of methods for this resource, see the end of this page.

Resource representations

{
  "kind": "bigquery#table",
  "etag": etag,
  "id": string,
  "selfLink": string,
  "tableReference": {
    "projectId": string,
    "datasetId": string,
    "tableId": string
  },
  "friendlyName": string,
  "description": string,
  "schema": {
    "fields": [
      {
        "name": string,
        "type": string,
        "mode": string,
        "fields": [
          (TableFieldSchema)
        ],
        "description": string
      }
    ]
  },
  "numBytes": long,
  "numRows": unsigned long,
  "creationTime": long,
  "expirationTime": long,
  "lastModifiedTime": unsigned long,
  "type": string,
  "view": {
    "query": string
  },
  "externalDataConfiguration": {
    "sourceUris": [
      string
    ],
    "schema": {
      "fields": [
        {
          "name": string,
          "type": string,
          "mode": string,
          "fields": [
            (TableFieldSchema)
          ],
          "description": string
        }
      ]
    },
    "sourceFormat": string,
    "maxBadRecords": integer,
    "ignoreUnknownValues": boolean,
    "compression": string,
    "csvOptions": {
      "fieldDelimiter": string,
      "skipLeadingRows": integer,
      "quote": string,
      "allowQuotedNewlines": boolean,
      "allowJaggedRows": boolean,
      "encoding": string
    }
  },
  "location": string,
  "streamingBuffer": {
    "estimatedRows": unsigned long,
    "estimatedBytes": unsigned long,
    "oldestEntryTime": unsigned long
  }
}
Property name Value Description Notes
creationTime long [Output-only] The time when this table was created, in milliseconds since the epoch.
description string [Optional] A user-friendly description of this table. writable
etag etag [Output-only] A hash of this resource.
expirationTime long [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.
externalDataConfiguration nested object [Experimental] 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.
externalDataConfiguration.compression string [Optional] The compression type of the data source. Possible values include GZIP and NONE. The default value is NONE.
externalDataConfiguration.csvOptions nested object Additional properties to set if sourceFormat is set to CSV.
externalDataConfiguration.csvOptions.allowJaggedRows boolean [Optional] Indicates if BigQuery should accept rows that are missing trailing optional columns. If true, BigQuery treats missing trailing columns as null values. If false, records with missing trailing columns are treated as bad records, and if there are too many bad records, an invalid error is returned in the job result. The default value is false.
externalDataConfiguration.csvOptions.allowQuotedNewlines boolean [Optional] Indicates if BigQuery should allow quoted data sections that contain newline characters in a CSV file. The default value is false.
externalDataConfiguration.csvOptions.encoding string [Optional] The character encoding of the data. The supported values are UTF-8 or ISO-8859-1. The default value is UTF-8. BigQuery decodes the data after the raw, binary data has been split using the values of the quote and fieldDelimiter properties.
externalDataConfiguration.csvOptions.fieldDelimiter string [Optional] The separator for fields in a CSV file. BigQuery converts the string to ISO-8859-1 encoding, and then uses the first byte of the encoded string to split the data in its raw, binary state. BigQuery also supports the escape sequence "\t" to specify a tab separator. The default value is a comma (',').
externalDataConfiguration.csvOptions.quote string [Optional] The value that is used to quote data sections in a CSV file. BigQuery converts the string to ISO-8859-1 encoding, and then uses the first byte of the encoded string to split the data in its raw, binary state. The default value is a double-quote ('"'). If your data does not contain quoted sections, set the property value to an empty string. If your data contains quoted newline characters, you must also set the allowQuotedNewlines property to true.
externalDataConfiguration.csvOptions.skipLeadingRows integer [Optional] The number of rows at the top of a CSV file that BigQuery will skip when reading the data. The default value is 0. This property is useful if you have header rows in the file that should be skipped.
externalDataConfiguration.ignoreUnknownValues boolean [Optional] Indicates if BigQuery should allow extra values that are not represented in the table schema. If true, the extra values are ignored. If false, records with extra columns are treated as bad records, and if there are too many bad records, an invalid error is returned in the job result. The default value is false. The sourceFormat property determines what BigQuery treats as an extra value: CSV: Trailing columns JSON: Named values that don't match any column names
externalDataConfiguration.maxBadRecords integer [Optional] The maximum number of bad records that BigQuery can ignore when reading data. If the number of bad records exceeds this value, an invalid error is returned in the job result. The default value is 0, which requires that all records are valid.
externalDataConfiguration.schema nested object [Required] The schema for the data.
externalDataConfiguration.schema.fields[] list Describes the fields in a table.
externalDataConfiguration.schema.fields[].description string [Optional] The field description. The maximum length is 16K characters.
externalDataConfiguration.schema.fields[].fields[] list [Optional] Describes the nested schema fields if the type property is set to RECORD.
externalDataConfiguration.schema.fields[].mode string [Optional] The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.
externalDataConfiguration.schema.fields[].name string [Required] The field name. The name must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
externalDataConfiguration.schema.fields[].type string [Required] The field data type. Possible values include STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP or RECORD (where RECORD indicates that the field contains a nested schema).
externalDataConfiguration.sourceFormat string [Required] The data format. For CSV files, specify "CSV". For newline-delimited JSON, specify "NEWLINE_DELIMITED_JSON".
externalDataConfiguration.sourceUris[] list [Required] The fully-qualified URIs that point to your data in Google Cloud Storage. Each URI can contain one '*' wildcard character and it must come after the 'bucket' name. Size limits related to load jobs apply to external data sources, plus an additional limit of 10 GB maximum size across all URIs.
friendlyName string [Optional] A descriptive name for this table. writable
id string [Output-only] An opaque ID uniquely identifying the table.
kind bigquery#table The type of resource ID.
lastModifiedTime unsigned long [Output-only] The time when this table was last modified, in milliseconds since the epoch.
location string [Output-only] The geographic location where the table resides. This value is inherited from the dataset.
numBytes long [Output-only] The size of this table in bytes, excluding any data in the streaming buffer.
numRows unsigned long [Output-only] The number of rows of data in this table, excluding any data in the streaming buffer.
schema nested object [Optional] Describes the schema of this table. writable
schema.fields[] list Describes the fields in a table.
schema.fields[].description string [Optional] The field description. The maximum length is 16K characters.
schema.fields[].fields[] list [Optional] Describes the nested schema fields if the type property is set to RECORD.
schema.fields[].mode string [Optional] The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.
schema.fields[].name string [Required] The field name. The name must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_), and must start with a letter or underscore. The maximum length is 128 characters.
schema.fields[].type string [Required] The field data type. Possible values include STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP or RECORD (where RECORD indicates that the field contains a nested schema). For more information about allowed values for each type, see data types.
streamingBuffer nested object [Output-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.
streamingBuffer.estimatedBytes unsigned long [Output-only] A lower-bound estimate of the number of bytes currently in the streaming buffer.
streamingBuffer.estimatedRows unsigned long [Output-only] A lower-bound estimate of the number of rows currently in the streaming buffer.
streamingBuffer.oldestEntryTime unsigned long [Output-only] Contains the timestamp of the oldest entry in the streaming buffer, in milliseconds since the epoch, if the streaming buffer is available.
tableReference nested object [Required] Reference describing the ID of this table.
tableReference.datasetId string [Required] The ID of the dataset containing this table.
tableReference.projectId string [Required] The ID of the project containing this table.
tableReference.tableId string [Required] The ID of the table. The ID must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_). The maximum length is 1,024 characters.
type string [Output-only] Describes the table type. The following values are supported:

  • TABLE: A normal BigQuery table. 
  • VIEW: A virtual table defined by a SQL query. For more information, see views.
The default value is TABLE.
view nested object [Optional] The view definition. writable
view.query string [Required] A query that BigQuery executes when the view is referenced.

Methods

The following methods are supported:

delete
Deletes the table specified by tableId from the dataset. If the table contains data, all the data will be deleted.
get
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.
insert
Creates a new, empty table in the dataset.
list
Lists all tables in the specified dataset. Requires the READER dataset role.
patch
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 patch semantics.
update
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.