Jobs: query

Requires authorization

Runs a BigQuery SQL query and returns 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 is deleted approximately 24 hours after the query is run. You can read this results table by calling either bigquery.tabledata.list(table_reference) or The table and dataset name are non-standard, and cannot be used in any other APIs, as the behavior may be unpredictable. Query results can't be shared.

The number of rows returned is limited by the maxResults property. For more information, see Paging through list results.

Access control: To call this method, you must have the following roles:

  • Can View for the project that contains the dataset.
  • READER for the dataset.
For more information, see access control.


HTTP request



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


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


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,
  "useLegacySql": boolean,
  "parameterMode": string,
  "queryParameters": [
      "name": string,
      "parameterType": {
        "type": string,
        "arrayType": (QueryParameterType),
        "structTypes": [
            "name": string,
            "type": (QueryParameterType),
            "description": string
      "parameterValue": {
        "value": string,
        "arrayValues": [
        "structValues": {
          (key): (QueryParameterValue)
Property name Value Description Notes
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. The ID must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_). The maximum length is 1,024 characters.
defaultDataset.projectId string [Optional] The ID of the project containing this dataset.
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 to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false.
preserveNulls boolean [Deprecated] This property is deprecated.
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. For more information, see query caching.
useLegacySql boolean Specifies whether to use BigQuery's legacy SQL dialect for this query. The default value is true. If set to false, the query will use BigQuery's standard SQL: When useLegacySql is set to false, the value of flattenResults is ignored; query will be run as if flattenResults is false.
parameterMode string Standard SQL only. Set to POSITIONAL to use positional (?) query parameters or to NAMED to use named (@myparam) query parameters in this query.
queryParameters[] list Query parameters for Standard SQL queries.
queryParameters[].name string [Optional] If unset, this is a positional parameter. Otherwise, should be unique within a query.
queryParameters[].parameterType nested object [Required] The type of this parameter.
queryParameters[].parameterType.type string [Required] The top level type of this field.
queryParameters[].parameterType.arrayType nested object [Optional] The type of the array's elements, if this is an array.
queryParameters[].parameterType.structTypes[] list [Optional] The types of the fields of this struct, in order, if this is a struct.
queryParameters[].parameterType.structTypes[].name string [Optional] The name of this field.
queryParameters[].parameterType.structTypes[].type nested object [Required] The type of this field.
queryParameters[].parameterType.structTypes[].description string [Optional] Human-oriented description of the field.
queryParameters[].parameterValue nested object [Required] The value of this parameter.
queryParameters[].parameterValue.value string [Optional] The value of this value, if a simple scalar type.
queryParameters[].parameterValue.arrayValues[] list [Optional] The array values, if this is an array type.
queryParameters[].parameterValue.structValues object [Optional] The struct field values, in order of the struct type's declaration.
queryParameters[].parameterValue.structValues.(key) nested object


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

  "kind": "bigquery#queryResponse",
  "schema": {
    "fields": [
        "name": string,
        "type": string,
        "mode": string,
        "fields": [
        "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": [
          "v": (TableRow)
  "totalBytesProcessed": long,
  "jobComplete": boolean,
  "errors": [
      "reason": string,
      "location": string,
      "debugInfo": string,
      "message": string
  "cacheHit": boolean,
  "numDmlAffectedRows": long
Property name Value Description Notes
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. 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, BYTES, INTEGER, INT64 (same as INTEGER), FLOAT, FLOAT64 (same as FLOAT), BOOLEAN, BOOL (same as BOOLEAN), TIMESTAMP, DATE, TIME, DATETIME, RECORD (where RECORD indicates that the field contains a nested schema) or STRUCT (same as RECORD).
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] The ID of the project containing this job.
jobReference.jobId string [Required] The ID of the job. The ID must contain only letters (a-z, A-Z), numbers (0-9), underscores (_), or dashes (-). The maximum length is 1,024 characters.
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 Represents a single row in the result set, consisting of one or more fields.
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. For more information, see query caching.
schema.fields[].description string [Optional] The field description. The maximum length is 1,024 characters.
errors[] list [Output-only] The first errors or warnings encountered during the running of the job. The final message includes the number of errors that caused the process to stop. Errors here do not necessarily mean that the job has completed or was unsuccessful.
errors[].reason string A short error code that summarizes the error.
errors[].location string Specifies where the error occurred, if present.
errors[].debugInfo string Debugging information. This property is internal to Google and should not be used.
errors[].message string A human-readable description of the error.
numDmlAffectedRows long [Output-only] The number of rows affected by a DML statement. Present only for DML statements INSERT, UPDATE or DELETE.

Try it!

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

Send feedback about...