Database Reference
In-Depth Information
like “latest,” because it enables running multiple versions side by side and
means that new versions can be added without breaking old ones.
Path
The path to get to a REST object should mirror the object hierarchy. For
example, in BigQuery, tables belong to datasets, which belong to projects.
So the path portion of the URL to read table
latest
in dataset
logs
in
project
bigquery-e2e
looks like
projects/bigquery-e2e/datsets/
logs/tables/latest
. The pattern, as you may notice from the table
URL, is usually
collection name
/
object name
/
sub collection
name
/
object name
. Although it may seem redundant to pass the
collection name each time, it makes it easy to add new collections at various
levels of the hierarchy and can resolve ambiguity. In addition, the collection
names in the URL path serve as a way of self-documenting the URL, at the
expense of only a few bytes in the request.
Method
The method portion of the URL is an optional component that tells
BigQuery what operation to perform. The method is not present in pure
REST requests because REST API calls specify the operation to perform
via the HTTP verb:
GET
,
PUT
,
POST
,
DELETE
, and so on. Some BigQuery
operations don't fit well in a REST model, so they use custom methods. An
example of this is the
Jobs.query()
operation, which is a shortcut for
inserting a job in the Jobs collection, waiting for the job to complete, and
reading the results. The path and method portion of the
Jobs.query()
operation URL looks like
projects/{
project ID
}/query
.
Operations that have a method name are often referred to as RPC methods
to distinguish them from pure REST calls. Some of them use HTTP
GET
, but
most of them use the HTTP
POST
verb because
GET
requests are supposed
to be
nullipotent
, meaning they do not change any state. Perhaps
surprisingly, the
Jobs.query()
RPC method is a
POST
for reasons that are
described in Chapter 7.
Query
The final portion of the URL is the query string. This should not be confused
with a BigQuery query. The query string is used only for HTTP
GET
requests
