bq command-line tool reference
This document describes the syntax, commands, flags, and arguments for bq
,
the BigQuery command-line tool.
It is intended for users who are familiar with BigQuery, but want to
know how to use a particular bq command-line tool command.
For general information about how to use the bq command-line tool, see
Using the bq command-line tool.
Synopsis
The bq command-line tool uses the following format:
bq COMMAND [FLAGS] [ARGUMENTS]
Some flags can be used with multiple bq command-line tool commands; these flags are described in the Global flags section.
Other flags are command-specific; they can only be used with a particular bq command-line tool command. The command-specific flags are described in the command sections.
Boolean flags
Some bq command-line tool flags are boolean; you can set the flag's value to either
true
or false
.
The bq command-line tool accepts the following formats for setting boolean flags.
Value | Format | Example |
---|---|---|
true |
--FLAGNAME=true |
--debug_mode=true |
true |
--FLAGNAME |
--debug_mode |
false |
--FLAGNAME=false |
--debug_mode=false |
false |
--noFLAGNAME |
--nodebug_mode |
This document uses the --FLAGNAME=VALUE
format for boolean flags.
All boolean flags are optional; if a boolean flag is not present, then BigQuery uses the flag's default value.
Specifying values for flags
When you specify a value for a flag, the equals sign (=
) is optional. For
example, the following two commands are equivalent:
bq ls --format prettyjson myDataset bq ls --format=prettyjson myDataset
This document uses the equals sign for clarity.
Online help
Documentation is available in the bq command-line tool, as follows:
Description | Help command format | Example |
---|---|---|
List of all commands with examples | bq help |
bq help |
Description of global flags | bq --help |
bq --help |
Description of a particular command | bq help COMMAND |
bq help mk |
Resource specification
The format for specifying a resource depends on the context; in some cases the
separator between the project and dataset is a colon (:
) and in some cases, it
is a period (.
). The following table
describes how to specify a BigQuery table in different contexts.
Context | Format | Example |
---|---|---|
bq command-line tool | PROJECT:DATASET.TABLE |
myProject:myDataset.myTable |
GoogleSQL query | PROJECT.DATASET.TABLE |
myProject.myDataset.myTable |
Legacy SQL query | PROJECT:DATASET.TABLE |
myProject:myDataset.myTable |
If you don't specify a project, then BigQuery uses the current
project. For example, if the current project is myProject
, then
BigQuery interprets myDataset.myTable
as
myProject:myDataset.myTable
(or myProject.myDataset.myTable
).
Some resource identifiers must be quoted using back ticks (`
).
If your resource identifier begins with a letter or underscore character, and
contains only characters that are letters, numbers, and underscores, then you
don't need to quote it. However, if your resource identifier
contains other types of
characters, or reserved keywords, you need to surround the identifier (or the
part of the identifier with the special characters or reserved keywords) with
back ticks. For more information, see
Identifiers.
Global flags
You can use the following flags with any bq
command, where applicable:
--api=ENDPOINT
- Specifies the API endpoint to call. The default value is
https://www.googleapis.com
. --api_version=VERSION
- Specifies the API version to use. The default is
v2
. --apilog=FILE
Logs all API requests and responses to the file specified by
FILE
. Possible values are the following:- the path to a file - logs to the specified file
stdout
- logs to standard outputstderr
- logs to standard errorfalse
- API requests and responses are not logged (default)
--bigqueryrc=PATH
Specifies the path to the bq command-line tool configuration file. If you don't specify the
--bigqueryrc
flag, then the command uses theBIGQUERYRC
environment variable. If the environment variable is not set, then$HOME/.bigqueryrc
is used. If that file does not exist, then~/.bigqueryrc
is used. For more information, see Setting default values for command-line flags.--ca_certificates_file=PATH
Specifies the location of your Certificate Authority Service (CA) file.
--dataset_id=DATASET_ID
Specifies the default dataset to use with the command. This flag is ignored when not applicable. You can specify the
DATASET_ID
argument using the formatPROJECT:DATASET
orDATASET
. If thePROJECT
part is missing, then the default project is used. You can override the default project setting by specifying the--project_id
flag.--debug_mode={true|false}
If set to
true
, shows tracebacks on Python exceptions. The default value isfalse
.--disable_ssl_validation={true|false}
If set to
true
, enables HTTPS certificate validation. The default value isfalse
.--discovery_file=PATH
Specifies the JSON file to read for discovery.
--enable_gdrive={true|false}
If set to
false
, requests a new OAuth token without Google Drive scope. The default value istrue
; requests a new OAuth token with Drive scope.--fingerprint_job_id={true|false}
To use a job ID that is derived from a fingerprint of the job configuration, set to
true
. This prevents the same job from running multiple times accidentally. The default value isfalse
.--format=FORMAT
Specifies the format of the command's output. Use one of the following values:
pretty
: formatted table outputsparse
: simpler table outputprettyjson
: easy-to-read JSON formatjson
: maximally compact JSONcsv
: csv format with header
pretty
,sparse
, andprettyjson
are intended to be human-readable.json
andcsv
are intended to be used by another program. Ifnone
is specified, then the command produces no output. If the--format
flag is absent, then an appropriate output format is chosen based on the command.--headless={true|false}
To run the
bq
session without user interaction, set totrue
. For example,debug_mode
does not break into the debugger, and the frequency of informational printing is lowered. The default value isfalse
.--httplib2_debuglevel=DEBUG_LEVEL
Specifies whether to show HTTP debugging information. If
DEBUG_LEVEL
is greater than0
, then the command logs HTTP server requests and responses to stderr, in addition to error messages. IfDEBUG_LEVEL
is not > 0, or if the--httplib2_debuglevel
flag is not used, then only error messages are provided.For example:
--httplib2_debuglevel=1
--job_id=JOB_ID
Specifies a job identifier for a new job. This flag applies only to commands that create jobs:
cp
,extract
,load
, andquery
. If you don't use the--job_id
flag, then the commands generate a unique job identifier. For more information, see Running jobs programmatically.--job_property=KEY:VALUE
A key-value pair to include in the properties field of the job configuration. Repeat this flag to specify additional properties.
--location=LOCATION
A string corresponding to a region or multi-region location. The location flag is required for the
bq cancel
command and for thebq show
command when you use the--jobs
flag to show information about jobs. The location flag is optional for the following commands:query
cp
load
extract
partition
update
wait
mk
when you use the--dataset
,--reservation
,--capacity_commitment
, or--reservation_assignment
flagsls
when you use the--reservation
,--capacity_commitment
, or--reservation_assignment
flags
All other commands ignore the
--location
flag.--max_rows_per_request=MAX_ROWS
An integer that specifies the maximum number of rows to return per read.
--project_id=PROJECT
Specifies the project to use for commands.
--proxy_address=PROXY
Specifies the name or IP address of the proxy host to use for connecting to Google Cloud.
--proxy_password=PASSWORD
Specifies the password to use when authenticating with the proxy host.
--proxy_port=PORT
Specifies the port number to use to connect to the proxy host.
--proxy_username=USERNAME
Specifies the username to use when authenticating with the proxy host.
--quiet={true|false}
or-q={true|false}
To suppress status updates while jobs are running, set to
true
. The default value isfalse
.--synchronous_mode={true|false}
or-sync={true|false}
To create the job and immediately return, with a successful completion status as the error code, set to
false
. If set totrue
, then the command waits for the job to complete before returning, and returns the job completion status as the error code. The default value istrue
.--trace=token:TOKEN
Specifies a tracing token to include in API requests.
--use_regional_endpoints={true|false}
In preview. To connect to a regional endpoint, set the
--use_regional_endpoints
flag totrue
and the--location
flag to the region you want to connect to. The default value isfalse
.
Deprecated global flags
The following global flag for specifying bq command-line tool flags from a file
is
deprecated. To specify flags from a file, use the
--bigqueryrc
flag.
--flagfile=PATH
When specified, flag definitions from the supplied file are inserted
into
the bq command-line tool. The default value is ''
. For more information, see
Setting default values for command-line flags.
Commands
The following sections describe the bq command-line tool commands, along with their command-specific flags and arguments.
bq add-iam-policy-binding
Use the bq add-iam-policy-binding
command to retrieve the
Identity and Access Management (IAM) policy
for a table or view and add a binding to the
policy, in one step.
This command is an alternative to the following three-step process:
- Using the
bq get-iam-policy
command to retrieve the policy file (in JSON format). - Editing the policy file.
- Using the
bq set-iam-policy
command to update the policy with a new binding.
Synopsis
bq add-iam-policy-binding [FLAGS] --member=MEMBER_TYPE:MEMBER --role=ROLE [--table]