BigQuery Client - Class Table (1.27.0)

Reference documentation and code samples for the BigQuery Client class Table.

Tables are a standard two-dimensional table with individual records organized in rows, and a data type assigned to each column (also called a field).

Namespace

Google \ Cloud \ BigQuery

Methods

__construct

Parameters
NameDescription
connection Google\Cloud\BigQuery\Connection\ConnectionInterface

Represents a connection to BigQuery.

id string

The table's id.

datasetId string

The dataset's id.

projectId string

The project's id.

mapper Google\Cloud\BigQuery\ValueMapper

Maps values between PHP and BigQuery.

info array

[optional] The table's metadata.

location string|null

[optional] A default geographic location, used when no table metadata exists.

exists

Check whether or not the table exists.

Example:

if ($table->exists()) {
    echo 'Table exists!';
}
Returns
TypeDescription
bool

delete

Delete the table.

Please note that by default the library will not attempt to retry this call on your behalf.

Example:

$table->delete();
Parameter
NameDescription
options array

[optional] Configuration options.

update

Update the table.

Providing an etag key as part of $metadata will enable simultaneous update protection. This is useful in preventing override of modifications made by another user. The resource's current etag can be obtained via a GET request on the resource.

Please note that by default the library will not automatically retry this call on your behalf unless an etag is set.

Example:

$table->update([
    'friendlyName' => 'A friendly name.'
]);
Parameters
NameDescription
metadata array

The available options for metadata are outlined at the Table Resource API docs

options array

[optional] Configuration options.

rows

Retrieves the rows associated with the table and merges them together with the schema.

Example:

$rows = $table->rows();

foreach ($rows as $row) {
    echo $row['name'] . PHP_EOL;
}
Parameters
NameDescription
options array

Configuration options.

↳ maxResults int

Maximum number of results to return per page.

↳ resultLimit int

Limit the number of results returned in total. Defaults to 0 (return all results).

↳ pageToken string

A previously-returned page token used to resume the loading of results from a specific point.

↳ startIndex int

Zero-based index of the starting row.

Returns
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator

runJob

Starts a job in an synchronous fashion, waiting for the job to complete before returning.

Example:

$job = $table->runJob($jobConfig);
echo $job->isComplete(); // true
Parameters
NameDescription
config Google\Cloud\BigQuery\JobConfigurationInterface

The job configuration.

options array

Configuration options.

↳ maxRetries int

The number of times to retry, checking if the job has completed. Defaults to 100.

Returns
TypeDescription
Google\Cloud\BigQuery\Job

startJob

Starts a job in an asynchronous fashion. In this case, it will be required to manually trigger a call to wait for job completion.

Example:

$job = $table->startJob($jobConfig);
Parameters
NameDescription
config Google\Cloud\BigQuery\JobConfigurationInterface

The job configuration.

options array

[optional] Configuration options.

Returns
TypeDescription
Google\Cloud\BigQuery\Job

copy

Returns a copy job configuration to be passed to either BigQueryClient::runJob() or BigQueryClient::startJob(). A configuration can be built using fluent setters or by providing a full set of options at once. This method can be used to create copy, snapshot and clone of the sourceTable as well as can also be used to restore snapshots by passing the following options: $options = [ 'configuration' => [ 'copy' => [ 'operationType' => ('COPY' | 'SNAPSHOT' | 'CLONE' | 'RESTORE') ] ] ]

Example:

$sourceTable = $bigQuery->dataset('myDataset')
    ->table('mySourceTable');
$destinationTable = $bigQuery->dataset('myDataset')
    ->table('myDestinationTable');

$copyJobConfig = $sourceTable->copy($destinationTable);
Parameters
NameDescription
destination Google\Cloud\BigQuery\Table

The destination table.

options array

Configuration options.

↳ configuration array

Job configuration. Please see the API documentation for the available options.

↳ configuration array

.copy Copy job configuration. Please see the documentation for the available options.

Returns
TypeDescription
Google\Cloud\BigQuery\CopyJobConfiguration

extract

Returns an extract job configuration to be passed to either BigQueryClient::runJob() or BigQueryClient::startJob(). A configuration can be built using fluent setters or by providing a full set of options at once.

Example:

$destinationObject = $storage->bucket('myBucket')->object('tableOutput');
$extractJobConfig = $table->extract($destinationObject);
Parameters
NameDescription
destination string|Google\Cloud\Storage\StorageObject

The destination object. May be a Google\Cloud\Storage\StorageObject or a URI pointing to a Google Cloud Storage object in the format of gs://{bucket-name}/{object-name}.

options array

Configuration options.

↳ configuration array

Job configuration. Please see the API documentation for the available options.

↳ configuration array

.extract Extract job configuration. Please see the documentation for the available options.

Returns
TypeDescription
Google\Cloud\BigQuery\ExtractJobConfiguration

load

Returns a load job configuration to be passed to either BigQueryClient::runJob() or BigQueryClient::startJob(). A configuration can be built using fluent setters or by providing a full set of options at once.

Example:

$loadJobConfig = $table->load(fopen('/path/to/my/data.csv', 'r'));
Parameters
NameDescription
data string|resource|Psr\Http\Message\StreamInterface

The data to load.

options array

Configuration options.

↳ configuration array

Job configuration. Please see the API documentation for the available options.

↳ configuration array

.load Load job configuration. Please see the documentation for the available options.

Returns
TypeDescription
Google\Cloud\BigQuery\LoadJobConfiguration

loadFromStorage

Returns a load job configuration to be passed to either BigQueryClient::runJob() or BigQueryClient::startJob(). A configuration can be built using fluent setters or by providing a full set of options at once.

Example:

$object = $storage->bucket('myBucket')->object('important-data.csv');
$loadJobConfig = $table->loadFromStorage($object);
Parameters
NameDescription
object string|Google\Cloud\Storage\StorageObject

The object to load data from. May be a Google\Cloud\Storage\StorageObject or a URI pointing to a Google Cloud Storage object in the format of gs://{bucket-name}/{object-name}.

options array

Configuration options.

↳ configuration array

Job configuration. Please see the API documentation for the available options.

↳ configuration array

.load Load job configuration. Please see the documentation for the available options.

Returns
TypeDescription
Google\Cloud\BigQuery\LoadJobConfiguration

insertRow

Insert a record into the table without running a load job.

Please note that by default the library will not automatically retry this call on your behalf unless an insertId is set.

Example:

$row = [
    'city' => 'Detroit',
    'state' => 'MI'
];

$insertResponse = $table->insertRow($row, [
    'insertId' => '1'
]);

if (!$insertResponse->isSuccessful()) {
    $row = $insertResponse->failedRows()[0];

    print_r($row['rowData']);

    foreach ($row['errors'] as $error) {
        echo $error['reason'] . ': ' . $error['message'] . PHP_EOL;
    }
}
Parameters
NameDescription
row array

Key/value set of data matching the table's schema.

options array

Please see Google\Cloud\BigQuery\Table::insertRows() for the other available configuration options.

↳ insertId string

Used to ensure data consistency.

Returns
TypeDescription
Google\Cloud\BigQuery\InsertResponse

insertRows

Insert records into the table without running a load job.

Please note that by default the library will not automatically retry this call on your behalf unless an insertId is set.

Example:

$rows = [
    [
        'insertId' => '1',
        'data' => [
            'city' => 'Detroit',
            'state' => 'MI'
        ]
    ],
    [
        'insertId' => '2',
        'data' => [
            'city' => 'New York',
            'state' => 'NY'
        ]
    ]
];

$insertResponse = $table->insertRows($rows);

if (!$insertResponse->isSuccessful()) {
    foreach ($insertResponse->failedRows() as $row) {
        print_r($row['rowData']);

        foreach ($row['errors'] as $error) {
            echo $error['reason'] . ': ' . $error['message'] . PHP_EOL;
        }
    }
}
Parameters
NameDescription
rows array

The rows to insert. Each item in the array must contain a data key which is to hold a key/value array with data matching the schema of the table. Optionally, one may also provide an insertId key which will be used to ensure data consistency.

options array

Configuration options.

↳ autoCreate bool

Whether or not to attempt to automatically create the table in the case it does not exist. Please note, it will be required to provide a schema through $tableMetadata['schema'] in the case the table does not already exist. Defaults to false.

↳ tableMetadata array

Metadata to apply to table to be created. The full set of metadata are outlined at the Table Resource API docs. Only applies when autoCreate is true.

↳ maxRetries int

The maximum number of times to attempt creating the table in the case of failure. Please note, each retry attempt may take up to two minutes. Only applies when autoCreate is true. Defaults to 100.

↳ skipInvalidRows bool

Insert all valid rows of a request, even if invalid rows exist. The default value is false, which causes the entire request to fail if any invalid rows exist. Defaults to false.

↳ ignoreUnknownValues bool

Accept rows that contain values that do not match the schema. The unknown values are ignored. The default value is false, which treats unknown values as errors. Defaults to false.

↳ templateSuffix string

If specified, treats the destination table as a base template, and inserts the rows into an instance table named "{destination}{templateSuffix}". BigQuery will manage creation of the instance table, using the schema of the base template table. See Creating tables automatically using template tables for considerations when working with templates tables.

Returns
TypeDescription
Google\Cloud\BigQuery\InsertResponse

info

Retrieves the table's details. If no table data is cached a network request will be made to retrieve it.

Example:

$info = $table->info();
echo $info['selfLink'];
Parameter
NameDescription
options array

[optional] Configuration options.

Returns
TypeDescription
array

reload

Triggers a network request to reload the table's details.

Example:

$table->reload();
$info = $table->info();
echo $info['selfLink'];
Parameter
NameDescription
options array

[optional] Configuration options.

Returns
TypeDescription
array

id

Retrieves the table's ID.

Example:

echo $table->id();
Returns
TypeDescription
string

identity

Retrieves the table's identity.

An identity provides a description of a nested resource.

Example:

echo $table->identity()['projectId'];
Returns
TypeDescription
array

iam

Manage the table's IAM policy.

Example:

$iam = $table->iam();
Returns
TypeDescription
Google\Cloud\Core\Iam\Iam

Constants

MAX_RETRIES

Value: 100

INSERT_CREATE_MAX_DELAY_MICROSECONDS

Value: 60000000