Jobs: query

Requires authorization

Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout. Try it now .

The query results from this method are saved to a temporary table that will be deleted about 24 hours after the query is run. You can read this results table by calling either bigquery.tabledata.list( table_id ) or bigquery.jobs.getQueryResults( job_reference ) . The table and dataset name are non-standard, and cannot be used in any other other APIs, as the behavior may be unpredictable. Query results are not shareable.

The number of rows returned is limited by the lesser of either the maximum page size or the maxResults property.

Required ACLs: To call this method, you must have one of the following sets of rights:

Dataset READ for the datasets being read + Project READ for the project being billed for the query.

Request

HTTP request

POST https://www.googleapis.com/bigquery/v2/projects/projectId/queries

Parameters

Parameter name	Value	Description
Path parameters
`projectId`	`string`	Project ID of the project billed for the query

Authorization

This request requires authorization with at least one of the following scopes ( read more about authentication and authorization ).

Scope
`https://www.googleapis.com/auth/bigquery`
`https://www.googleapis.com/auth/cloud-platform`

Request body

In the request body, supply data with the following structure:

{
  "kind": "bigquery#queryRequest",
  "query": string,
  "maxResults": unsigned integer,
  "defaultDataset": {
    "datasetId": string,
    "projectId": string
  },
  "timeoutMs": unsigned integer,
  "dryRun": boolean,
  "preserveNulls": boolean,
  "useQueryCache": boolean
}

Property name	Value	Description
`kind`	`string`	The resource type of the request.
`query`	`string`	[Required] A query string, following the BigQuery query syntax, of the query to execute. Example: "SELECT count(f1) FROM [myProjectId:myDatasetId.myTableId]".
`maxResults`	`unsigned integer`	[Optional] The maximum number of rows of data to return per page of results. Setting this flag to a small value such as 1000 and then paging through results might improve reliability when the query result set is large. In addition to this limit, responses are also limited to 10 MB. By default, there is no maximum row count, and only the byte limit applies.
`defaultDataset`	`nested object`	[Optional] Specifies the default datasetId and projectId to assume for any unqualified table names in the query. If not set, all table names in the query string must be qualified in the format 'datasetId.tableId'.
`defaultDataset. datasetId`	`string`	[Required] A unique ID for this dataset, without the project name.
`defaultDataset. projectId`	`string`	[Optional] The ID of the container project.
`timeoutMs`	`unsigned integer`	[Optional] How long to wait for the query to complete, in milliseconds, before the request times out and returns. Note that this is only a timeout for the request, not the query. If the query takes longer to run than the timeout value, the call returns without any results and with the 'jobComplete' flag set to false. You can call GetQueryResults() to wait for the query to complete and read the results. The default value is 10000 milliseconds (10 seconds).
`dryRun`	`boolean`	[Optional] If set, don't actually run the query. A valid query will return an empty response, while an invalid query will return the same error it would if it wasn't a dry run. The default value is false.
`preserveNulls`	`boolean`	[Deprecated] If set to false, maps null values in the query response to the column's default value. Only specify if you have older code that can not handle null values in the query response. The default value is true. This flag is deprecated and will be ignored in a future version of BigQuery.
`useQueryCache`	`boolean`	[Optional] Whether to look for the result in the query cache. The query cache is a best-effort cache that will be flushed whenever tables in the query are modified. The default value is true.

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "bigquery#queryResponse",
  "schema": {
    "fields": [
      {
        "name": string,
        "type": string,
        "mode": string,
        "fields": [
          (TableFieldSchema)
        ],
        "description": string
      }
    ]
  },
  "jobReference": {
    "projectId": string,
    "jobId": string
  },
  "totalRows": unsigned long,
  "pageToken": string,
  "rows": [
    {
      "f": [
        {
          "v": (value),
          "v": string,
          "v": string,
          "v": string,
          "v": string,
          "v": string,
          "v": string,
          "v": string,
          "v": string,
          "v": [
            (TableCell)
          ],
          "v": (TableRow)
        }
      ]
    }
  ],
  "totalBytesProcessed": long,
  "jobComplete": boolean,
  "cacheHit": boolean
}

Property name	Value	Description
`kind`	`bigquery#queryResults`	The resource type.
`schema`	`nested object`	The schema of the results. Present only when the query completes successfully.
`schema. fields[]`	`list`	Describes the fields in a table.
`schema.fields[]. name`	`string`	[Required] The field name.
`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).
`schema.fields[]. mode`	`string`	[Optional] The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.
`schema.fields[]. fields[]`	`list`	[Optional] Describes the nested schema fields if the type property is set to RECORD.
`jobReference`	`nested object`	Reference to the Job that was created to run the query. This field will be present even if the original request timed out, in which case GetQueryResults can be used to read the results once the query has completed. Since this API only returns the first page of results, subsequent pages can be fetched via the same mechanism (GetQueryResults).
`jobReference. projectId`	`string`	[Required] Project ID being billed for the job.
`jobReference. jobId`	`string`	[Required] ID of the job.
`totalRows`	`unsigned long`	The total number of rows in the complete query result set, which can be more than the number of rows in this single page of results.
`rows[]`	`list`	An object with as many results as can be contained within the maximum permitted reply size. To get any additional rows, you can call GetQueryResults and specify the jobReference returned above.
`rows[]. f[]`	`list`
`rows[].f[]. v`	`nested object`
`jobComplete`	`boolean`	Whether the query has completed or not. If rows or totalRows are present, this will always be true. If this is false, totalRows will not be available.
`pageToken`	`string`	A token used for paging results.
`totalBytesProcessed`	`long`	The total number of bytes processed for this query. If this query was a dry run, this is the number of bytes that would be processed if the query were run.
`cacheHit`	`boolean`	Whether the query result was fetched from the query cache.
`schema.fields[]. description`	`string`	[Optional] The field description.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Google BigQuery