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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Name	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`config`	`Google\Cloud\BigQuery\JobConfigurationInterface` The job configuration.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`Google\Cloud\BigQuery\LoadJobConfiguration`

loadFromStorage

Example:

$object = $storage->bucket('myBucket')->object('important-data.csv');
$loadJobConfig = $table->loadFromStorage($object);

Parameters
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`array`

reload

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

Example:

$table->reload();
$info = $table->info();
echo $info['selfLink'];

Parameter
Name	Description
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`array`

id

Retrieves the table's ID.

Example:

echo $table->id();

Returns
Type	Description
`string`

identity

Retrieves the table's identity.

An identity provides a description of a nested resource.

Example:

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

Returns
Type	Description
`array`

iam

Manage the table's IAM policy.

Example:

$iam = $table->iam();

Returns
Type	Description
`Google\Cloud\Core\Iam\Iam`

Constants

MAX_RETRIES

Value: 100

INSERT_CREATE_MAX_DELAY_MICROSECONDS

Value: 60000000