openapi: 3.1.0 info: title: Google BigQuery API description: >- The BigQuery API provides programmatic access to Google BigQuery for creating, managing, and querying datasets, tables, jobs, models, and routines. It enables developers to run SQL queries over petabytes of data, load and export data, manage access control, and orchestrate analytics workloads using serverless infrastructure. version: '2' contact: name: Google Cloud Support url: https://cloud.google.com/bigquery/docs/support termsOfService: https://cloud.google.com/terms externalDocs: description: BigQuery API Documentation url: https://cloud.google.com/bigquery/docs/reference/rest servers: - url: https://bigquery.googleapis.com/bigquery/v2 description: Production Server tags: - name: Datasets description: Operations for managing BigQuery datasets - name: Jobs description: Operations for managing query and load jobs - name: Models description: Operations for managing BigQuery ML models - name: Projects description: Operations for listing projects and service accounts - name: Routines description: Operations for managing routines (functions and procedures) - name: Tabledata description: Operations for reading and inserting table rows - name: Tables description: Operations for managing tables within datasets security: - oauth2: [] paths: /projects: get: operationId: listProjects summary: Google BigQuery List projects description: >- Lists all projects to which the user has been granted any project role. tags: - Projects parameters: - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ProjectList' '401': description: Unauthorized '403': description: Forbidden /projects/{projectId}/datasets: get: operationId: listDatasets summary: Google BigQuery List datasets description: >- Lists all datasets in the specified project to which the user has been granted the READER dataset role. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' - name: all in: query description: Whether to list all datasets, including hidden ones schema: type: boolean - name: filter in: query description: Filter expression for filtering datasets by label schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DatasetList' '401': description: Unauthorized '404': description: Project not found post: operationId: insertDataset summary: Google BigQuery Create a dataset description: >- Creates a new empty dataset in the specified project. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Dataset' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Bad request '401': description: Unauthorized '409': description: Dataset already exists /projects/{projectId}/datasets/{datasetId}: get: operationId: getDataset summary: Google BigQuery Get dataset description: >- Returns the dataset specified by datasetId. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Dataset' '401': description: Unauthorized '404': description: Dataset not found patch: operationId: patchDataset summary: Google BigQuery Partially update dataset description: >- Updates information in an existing dataset. The update method replaces the entire dataset resource, whereas the patch method only replaces fields that are provided in the submitted dataset resource. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Dataset' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Dataset' '401': description: Unauthorized '404': description: Dataset not found put: operationId: updateDataset summary: Google BigQuery Update dataset description: >- Updates information in an existing dataset by replacing the entire dataset resource. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Dataset' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Dataset' '401': description: Unauthorized '404': description: Dataset not found delete: operationId: deleteDataset summary: Google BigQuery Delete dataset description: >- Deletes the dataset specified by the datasetId value. Before you can delete a dataset, you must delete all its tables. tags: - Datasets parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: deleteContents in: query description: If true, delete all the tables in the dataset schema: type: boolean responses: '204': description: Successfully deleted '401': description: Unauthorized '404': description: Dataset not found /projects/{projectId}/datasets/{datasetId}/tables: get: operationId: listTables summary: Google BigQuery List tables description: >- Lists all tables in the specified dataset. tags: - Tables parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TableList' '401': description: Unauthorized '404': description: Dataset not found post: operationId: insertTable summary: Google BigQuery Create a table description: >- Creates a new empty table in the specified dataset. tags: - Tables parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Table' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Table' '400': description: Bad request '401': description: Unauthorized '409': description: Table already exists /projects/{projectId}/datasets/{datasetId}/tables/{tableId}: get: operationId: getTable summary: Google BigQuery Get table description: >- Gets the specified table resource by table ID. tags: - Tables parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/tableId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Table' '401': description: Unauthorized '404': description: Table not found patch: operationId: patchTable summary: Google BigQuery Partially update table description: >- Updates information in an existing table, replacing only the fields provided in the submitted table resource. tags: - Tables parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/tableId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Table' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Table' '401': description: Unauthorized '404': description: Table not found delete: operationId: deleteTable summary: Google BigQuery Delete table description: >- Deletes the table specified by tableId from the dataset. tags: - Tables parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/tableId' responses: '204': description: Successfully deleted '401': description: Unauthorized '404': description: Table not found /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/data: get: operationId: listTabledata summary: Google BigQuery List table rows description: >- Lists the rows of a table, returning rows in the response body. tags: - Tabledata parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/tableId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' - name: startIndex in: query description: Zero-based index of the starting row to read schema: type: integer format: int64 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TableDataList' '401': description: Unauthorized '404': description: Table not found /projects/{projectId}/datasets/{datasetId}/tables/{tableId}/insertAll: post: operationId: insertAllTabledata summary: Google BigQuery Insert rows description: >- Streams data into BigQuery one record at a time without needing to run a load job. tags: - Tabledata parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/tableId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TableDataInsertAllRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/TableDataInsertAllResponse' '400': description: Bad request '401': description: Unauthorized /projects/{projectId}/jobs: get: operationId: listJobs summary: Google BigQuery List jobs description: >- Lists all jobs that you started in the specified project. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' - name: projection in: query description: Restricts information returned to a set of selected fields schema: type: string enum: - full - minimal - name: stateFilter in: query description: Filter for job state schema: type: array items: type: string enum: - done - pending - running responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/JobList' '401': description: Unauthorized post: operationId: insertJob summary: Google BigQuery Submit a job description: >- Starts a new asynchronous job such as a query, load, extract, or copy job. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Job' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Job' '400': description: Bad request '401': description: Unauthorized /projects/{projectId}/jobs/{jobId}: get: operationId: getJob summary: Google BigQuery Get job description: >- Returns information about a specific job. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/jobId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Job' '401': description: Unauthorized '404': description: Job not found delete: operationId: deleteJob summary: Google BigQuery Delete job description: >- Requests the deletion of the metadata of a job. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/jobId' responses: '204': description: Successfully deleted '401': description: Unauthorized '404': description: Job not found /projects/{projectId}/jobs/{jobId}/cancel: post: operationId: cancelJob summary: Google BigQuery Cancel job description: >- Requests that a job be cancelled. This call will return immediately, and the client will need to poll for the job status to see if the cancel completed successfully. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/jobId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/JobCancelResponse' '401': description: Unauthorized '404': description: Job not found /projects/{projectId}/queries: post: operationId: queryJobs summary: Google BigQuery Execute query description: >- Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/QueryResponse' '400': description: Bad request '401': description: Unauthorized /projects/{projectId}/queries/{jobId}: get: operationId: getQueryResults summary: Google BigQuery Get query results description: >- Retrieves the results of a query job. tags: - Jobs parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/jobId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' - name: startIndex in: query description: Zero-based index of the starting row schema: type: integer format: int64 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/QueryResponse' '401': description: Unauthorized '404': description: Job not found /projects/{projectId}/datasets/{datasetId}/models: get: operationId: listModels summary: Google BigQuery List models description: >- Lists all models in the specified dataset. tags: - Models parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ModelList' '401': description: Unauthorized '404': description: Dataset not found /projects/{projectId}/datasets/{datasetId}/models/{modelId}: get: operationId: getModel summary: Google BigQuery Get model description: >- Gets the specified model resource by model ID. tags: - Models parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: modelId in: path required: true description: The ID of the model schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Model' '401': description: Unauthorized '404': description: Model not found patch: operationId: patchModel summary: Google BigQuery Update model description: >- Patch specific fields in the specified model. tags: - Models parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: modelId in: path required: true description: The ID of the model schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Model' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Model' '401': description: Unauthorized '404': description: Model not found delete: operationId: deleteModel summary: Google BigQuery Delete model description: >- Deletes the model specified by modelId from the dataset. tags: - Models parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: modelId in: path required: true description: The ID of the model schema: type: string responses: '204': description: Successfully deleted '401': description: Unauthorized '404': description: Model not found /projects/{projectId}/datasets/{datasetId}/routines: get: operationId: listRoutines summary: Google BigQuery List routines description: >- Lists all routines in the specified dataset. tags: - Routines parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - $ref: '#/components/parameters/maxResults' - $ref: '#/components/parameters/pageToken' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/RoutineList' '401': description: Unauthorized post: operationId: insertRoutine summary: Google BigQuery Create a routine description: >- Creates a new routine in the specified dataset. tags: - Routines parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Routine' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Routine' '400': description: Bad request '401': description: Unauthorized /projects/{projectId}/datasets/{datasetId}/routines/{routineId}: get: operationId: getRoutine summary: Google BigQuery Get routine description: >- Gets the specified routine resource by routine ID. tags: - Routines parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: routineId in: path required: true description: The ID of the routine schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Routine' '401': description: Unauthorized '404': description: Routine not found put: operationId: updateRoutine summary: Google BigQuery Update routine description: >- Updates information in an existing routine by replacing the entire routine resource. tags: - Routines parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: routineId in: path required: true description: The ID of the routine schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Routine' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Routine' '401': description: Unauthorized '404': description: Routine not found delete: operationId: deleteRoutine summary: Google BigQuery Delete routine description: >- Deletes the routine specified by routineId from the dataset. tags: - Routines parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/datasetId' - name: routineId in: path required: true description: The ID of the routine schema: type: string responses: '204': description: Successfully deleted '401': description: Unauthorized '404': description: Routine not found components: securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://accounts.google.com/o/oauth2/auth tokenUrl: https://oauth2.googleapis.com/token scopes: https://www.googleapis.com/auth/bigquery: Full access to BigQuery https://www.googleapis.com/auth/bigquery.readonly: Read-only access to BigQuery parameters: projectId: name: projectId in: path required: true description: The ID of the project schema: type: string datasetId: name: datasetId in: path required: true description: The ID of the dataset schema: type: string tableId: name: tableId in: path required: true description: The ID of the table schema: type: string jobId: name: jobId in: path required: true description: The ID of the job schema: type: string maxResults: name: maxResults in: query description: Maximum number of results to return schema: type: integer format: int32 pageToken: name: pageToken in: query description: Page token for pagination schema: type: string schemas: Dataset: type: object properties: kind: type: string description: The resource type, always bigquery#dataset id: type: string description: The fully-qualified unique name of the dataset datasetReference: $ref: '#/components/schemas/DatasetReference' friendlyName: type: string description: A descriptive name for the dataset description: type: string description: A user-friendly description of the dataset labels: type: object additionalProperties: type: string description: Labels associated with this dataset location: type: string description: The geographic location where the dataset should reside creationTime: type: string description: The time when this dataset was created in milliseconds since epoch lastModifiedTime: type: string description: The date when this dataset was last modified in milliseconds since epoch DatasetReference: type: object properties: projectId: type: string description: The ID of the project containing the dataset datasetId: type: string description: The ID of the dataset DatasetList: type: object properties: kind: type: string description: The resource type datasets: type: array items: $ref: '#/components/schemas/Dataset' description: An array of dataset resources nextPageToken: type: string description: A token to request the next page of results Table: type: object properties: kind: type: string description: The resource type, always bigquery#table id: type: string description: The fully-qualified unique name of the table tableReference: $ref: '#/components/schemas/TableReference' friendlyName: type: string description: A descriptive name for the table description: type: string description: A user-friendly description of the table schema: $ref: '#/components/schemas/TableSchema' numRows: type: string description: The number of rows in the table numBytes: type: string description: The size of the table in bytes type: type: string description: The type of the table enum: - TABLE - VIEW - MATERIALIZED_VIEW - EXTERNAL - SNAPSHOT creationTime: type: string description: The time when this table was created expirationTime: type: string description: The time when this table expires labels: type: object additionalProperties: type: string description: Labels associated with this table TableReference: type: object properties: projectId: type: string description: The ID of the project containing the table datasetId: type: string description: The ID of the dataset containing the table tableId: type: string description: The ID of the table TableSchema: type: object properties: fields: type: array items: $ref: '#/components/schemas/TableFieldSchema' description: Describes the fields in a table TableFieldSchema: type: object required: - name - type properties: name: type: string description: The field name type: type: string description: The field data type enum: - STRING - BYTES - INTEGER - INT64 - FLOAT - FLOAT64 - NUMERIC - BIGNUMERIC - BOOLEAN - BOOL - TIMESTAMP - DATE - TIME - DATETIME - GEOGRAPHY - RECORD - STRUCT - JSON mode: type: string description: The field mode enum: - NULLABLE - REQUIRED - REPEATED description: type: string description: The field description fields: type: array items: $ref: '#/components/schemas/TableFieldSchema' description: Nested fields for RECORD type TableList: type: object properties: kind: type: string description: The resource type tables: type: array items: $ref: '#/components/schemas/Table' description: Tables in the requested dataset nextPageToken: type: string description: A token to request the next page of results totalItems: type: integer description: The total number of tables in the dataset TableDataList: type: object properties: kind: type: string description: The resource type rows: type: array items: type: object description: Rows of results pageToken: type: string description: A token to request the next page of results totalRows: type: string description: The total number of rows in the table TableDataInsertAllRequest: type: object properties: kind: type: string description: The resource type skipInvalidRows: type: boolean description: Whether to insert rows that contain values that do not match the schema ignoreUnknownValues: type: boolean description: Whether to accept rows with fields not matching the schema rows: type: array items: type: object properties: insertId: type: string description: A unique ID for deduplication json: type: object description: A JSON object with a row of data description: The rows to insert TableDataInsertAllResponse: type: object properties: kind: type: string description: The resource type insertErrors: type: array items: type: object properties: index: type: integer description: The index of the row with the error errors: type: array items: $ref: '#/components/schemas/ErrorProto' description: Insert errors for individual rows Job: type: object properties: kind: type: string description: The resource type, always bigquery#job id: type: string description: The fully-qualified unique name of the job jobReference: $ref: '#/components/schemas/JobReference' configuration: $ref: '#/components/schemas/JobConfiguration' status: $ref: '#/components/schemas/JobStatus' statistics: type: object description: Output only statistics about the job JobReference: type: object properties: projectId: type: string description: The ID of the project containing the job jobId: type: string description: The ID of the job location: type: string description: The geographic location of the job JobConfiguration: type: object properties: jobType: type: string description: The type of the job query: type: object description: Configuration for a query job properties: query: type: string description: SQL query text destinationTable: $ref: '#/components/schemas/TableReference' useLegacySql: type: boolean description: Whether to use legacy SQL dialect load: type: object description: Configuration for a load job extract: type: object description: Configuration for an extract job copy: type: object description: Configuration for a copy job JobStatus: type: object properties: state: type: string description: Running state of the job enum: - PENDING - RUNNING - DONE errorResult: $ref: '#/components/schemas/ErrorProto' errors: type: array items: $ref: '#/components/schemas/ErrorProto' description: The first errors encountered during the running of the job JobList: type: object properties: kind: type: string description: The resource type jobs: type: array items: $ref: '#/components/schemas/Job' description: List of jobs nextPageToken: type: string description: A token to request the next page of results JobCancelResponse: type: object properties: kind: type: string description: The resource type job: $ref: '#/components/schemas/Job' QueryRequest: type: object required: - query properties: query: type: string description: A query string to execute using GoogleSQL or legacy SQL maxResults: type: integer description: The maximum number of rows of data to return per page defaultDataset: $ref: '#/components/schemas/DatasetReference' useLegacySql: type: boolean description: Whether to use legacy SQL dialect timeoutMs: type: integer description: Timeout in milliseconds for the query to complete dryRun: type: boolean description: If true, the query is not executed QueryResponse: type: object properties: kind: type: string description: The resource type schema: $ref: '#/components/schemas/TableSchema' rows: type: array items: type: object description: Result rows totalRows: type: string description: The total number of rows in the complete query result set pageToken: type: string description: A token to request the next page of results jobComplete: type: boolean description: Whether the query has completed jobReference: $ref: '#/components/schemas/JobReference' totalBytesProcessed: type: string description: The total number of bytes processed by the query Model: type: object properties: modelReference: type: object properties: projectId: type: string description: The ID of the project datasetId: type: string description: The ID of the dataset modelId: type: string description: The ID of the model modelType: type: string description: The type of the model friendlyName: type: string description: A descriptive name for the model description: type: string description: A user-friendly description of the model labels: type: object additionalProperties: type: string description: Labels associated with this model creationTime: type: string description: The time when this model was created ModelList: type: object properties: models: type: array items: $ref: '#/components/schemas/Model' description: Models in the requested dataset nextPageToken: type: string description: A token to request the next page of results Routine: type: object properties: routineReference: type: object properties: projectId: type: string description: The ID of the project datasetId: type: string description: The ID of the dataset routineId: type: string description: The ID of the routine routineType: type: string description: The type of the routine enum: - SCALAR_FUNCTION - PROCEDURE - TABLE_VALUED_FUNCTION language: type: string description: The language of the routine definitionBody: type: string description: The body of the routine description: type: string description: A user-friendly description of the routine creationTime: type: string description: The time when this routine was created RoutineList: type: object properties: routines: type: array items: $ref: '#/components/schemas/Routine' description: Routines in the requested dataset nextPageToken: type: string description: A token to request the next page of results ProjectList: type: object properties: kind: type: string description: The resource type projects: type: array items: type: object properties: id: type: string description: The project ID friendlyName: type: string description: A descriptive name for the project projectReference: type: object properties: projectId: type: string description: The ID of the project description: Projects to which the user has at least READ access nextPageToken: type: string description: A token to request the next page of results totalItems: type: integer description: The total number of projects ErrorProto: type: object properties: reason: type: string description: A short error code that summarizes the error location: type: string description: Specifies where the error occurred message: type: string description: A human-readable description of the error