Database Reference
In-Depth Information
Query API Methods
There are two ways to run queries using the BigQuery HTTP API: You
can call
Jobs.insert()
to add a Query job to the Jobs REST collection,
or you can use the
Jobs.query()
and
Jobs.getQueryResults()
RPC
methods. The former method is a bit more complex; you need to insert the
Query job, poll for completion, and then read the results. The latter can be
simpler when you want to do simple things; you can run a query and get
results back in a single API call. That said, by the time you account for large
query results, queries that take more than a few seconds, or error handling,
the two methods may involve the same amount of code.
When Should You Use Jobs.query() Versus
Jobs.insert() to Run Queries?
The difference between the
Jobs.query()
and the
Jobs.insert()
method is sometimes referred to as “porcelain” versus “plumbing.” The
Jobs.insert()
“plumbing” API enables you do anything the
Jobs.query()
API does and more but may have fewer conveniences;
the
Jobs.query()
“porcelain” method is simpler and easier to use.
The
Jobs.query()
method should generally be preferred whenever it
can be used, for example, when you won't need to save the results in a
named destination table, when you won't need large (>128 MB) query
results, and when you expect the query to run quickly. One advantage
of
Jobs.query()
is that it waits for results before returning. This
saves you from having to poll for query completion.
The
Jobs.insert()
method, conversely, should be used whenever
you need to control your destination table, query priority, or when you
need large query results. It is also useful when you're writing code that
needs to work with all kinds of jobs, rather than just query jobs.
The following Python command shows running a simple query via the
Jobs.query()
API:
$
python
>>>
import auth
