The Road to GA - BigQuery Updates

src/BigQuery/Connection/Rest.php

@@ -246,12 +246,19 @@ private function resolveUploadOptions(array $args)
         $args += [
             'projectId' => null,
             'data' => null,
-            'configuration' => []
+            'configuration' => [],
+            'labels' => [],
+            'dryRun' => false,
+            'jobReference' => []
         ];
 
         $args['data'] = Psr7\stream_for($args['data']);
-        $args['metadata']['configuration'] = $args['configuration'];
-        unset($args['configuration']);
+        $args['metadata'] = $this->pluckArray([
+            'labels',
+            'dryRun',
+            'jobReference',
+            'configuration'
+        ], $args);
 
         $uploaderOptionKeys = [
             'restOptions',

src/BigQuery/CopyJobConfiguration.php

@@ -0,0 +1,154 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\BigQuery;
+
+/**
+ * Represents a configuration for a copy job. For more information on the
+ * available settings please see the
+ * [Jobs configuration API documentation](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration).
+ *
+ * Example:
+ * ```
+ * use Google\Cloud\BigQuery\BigQueryClient;
+ *
+ * $bigQuery = new BigQueryClient();
+ * $sourceTable = $bigQuery->dataset('my_dataset')
+ *     ->table('my_source_table');
+ * $destinationTable = $bigQuery->dataset('my_dataset')
+ *     ->table('my_destination_table');
+ *
+ * $copyJobConfig = $sourceTable->copy($destinationTable);
+ * ```
+ */
+class CopyJobConfiguration implements JobConfigurationInterface
+{
+    use JobConfigurationTrait;
+
+    /**
+     * @param string $projectId The project's ID.
+     * @param array $config A set of configuration options for a job.
+     */
+    public function __construct($projectId, array $config)
+    {
+        $this->jobConfigurationProperties($projectId, $config);
+    }
+
+    /**
+     * Set whether the job is allowed to create new tables. Creation, truncation
+     * and append actions occur as one atomic update upon job completion.
+     *
+     * Example:
+     * ```
+     * $copyJobConfig->createDisposition('CREATE_NEVER');
+     * ```
+     *
+     * @param string $createDisposition The create disposition. Acceptable
+     *        values include `"CREATED_IF_NEEDED"`, `"CREATE_NEVER"`. **Defaults
+     *        to** `"CREATE_IF_NEEDED"`.
+     * @return CopyJobConfiguration
+     */
+    public function createDisposition($createDisposition)
+    {
+        $this->config['configuration']['copy']['createDisposition'] = $createDisposition;
+
+        return $this;
+    }
+
+    /**
+     * Sets the custom encryption configuration (e.g., Cloud KMS keys).
+     *
+     * Example:
+     * ```
+     * $copyJobConfig->destinationEncryptionConfiguration([
+     *     'kmsKeyName' => 'my_key'
+     * ]);
+     * ```
+     *
+     * @param array $configuration Custom encryption configuration.
+     * @return CopyJobConfiguration
+     */
+    public function destinationEncryptionConfiguration(array $configuration)
+    {
+        $this->config['configuration']['copy']['destinationEncryptionConfiguration'] = $configuration;
+
+        return $this;
+    }
+
+    /**
+     * Sets the destination table.
+     *
+     * Example:
+     * ```
+     * $table = $bigQuery->dataset('my_dataset')
+     *     ->table('my_table');
+     * $copyJobConfig->destinationTable($table);
+     * ```
+     *
+     * @param Table $destinationTable The destination table.
+     * @return CopyJobConfiguration
+     */
+    public function destinationTable(Table $destinationTable)
+    {
+        $this->config['configuration']['copy']['destinationTable'] = $destinationTable->identity();
+
+        return $this;
+    }
+
+    /**
+     * Sets the source table to copy.
+     *
+     * Example:
+     * ```
+     * $table = $bigQuery->dataset('my_dataset')
+     *     ->table('source_table');
+     * $copyJobConfig->sourceTable($table);
+     * ```
+     *
+     * @param Table $sourceTable The destination table.
+     * @return CopyJobConfiguration
+     */
+    public function sourceTable(Table $sourceTable)
+    {
+        $this->config['configuration']['copy']['sourceTable'] = $sourceTable->identity();
+
+        return $this;
+    }
+
+    /**
+     * Sets the action that occurs if the destination table already exists. Each
+     * action is atomic and only occurs if BigQuery is able to complete the job
+     * successfully. Creation, truncation and append actions occur as one atomic
+     * update upon job completion.
+     *
+     * Example:
+     * ```
+     * $copyJobConfig->writeDisposition('WRITE_TRUNCATE');
+     * ```
+     *
+     * @param string $writeDisposition The write disposition. Acceptable values
+     *        include `"WRITE_TRUNCATE"`, `"WRITE_APPEND"`, `"WRITE_EMPTY"`.
+     *        **Defaults to** `"WRITE_EMPTY"`.
+     * @return CopyJobConfiguration
+     */
+    public function writeDisposition($writeDisposition)
+    {
+        $this->config['configuration']['copy']['writeDisposition'] = $writeDisposition;
+
+        return $this;
+    }
+}

src/BigQuery/Dataset.php

@@ -19,6 +19,7 @@
 
 use Google\Cloud\BigQuery\Connection\ConnectionInterface;
 use Google\Cloud\Core\ArrayTrait;
+use Google\Cloud\Core\ConcurrencyControlTrait;
 use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Core\Iterator\ItemIterator;
 use Google\Cloud\Core\Iterator\PageIterator;
@@ -30,6 +31,7 @@
 class Dataset
 {
     use ArrayTrait;
+    use ConcurrencyControlTrait;
 
     /**
      * @var ConnectionInterface Represents a connection to BigQuery.
@@ -98,6 +100,9 @@ public function exists()
     /**
      * Delete the dataset.
      *
+     * Please note that by default the library will not attempt to retry this
+     * call on your behalf.
+     *
      * Example:
      * ```
      * $dataset->delete();
@@ -115,12 +120,24 @@ public function exists()
      */
     public function delete(array $options = [])
     {
-        $this->connection->deleteDataset($options + $this->identity);
+        $this->connection->deleteDataset(
+            $options
+            + ['retries' => 0]
+            + $this->identity
+        );
     }
 
     /**
      * Update the dataset.
      *
+     * 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 this call will not automatically retry on
+     * your behalf unless an `etag` is set.
+     *
      * Example:
      * ```
      * $dataset->update([
@@ -129,17 +146,25 @@ public function delete(array $options = [])
      * ```
      *
      * @see https://cloud.google.com/bigquery/docs/reference/v2/datasets/patch Datasets patch API documentation.
+     * @see https://cloud.google.com/bigquery/docs/api-performance#patch Patch (Partial Update)
      *
      * @param array $metadata The available options for metadata are outlined
      *        at the [Dataset Resource API docs](https://cloud.google.com/bigquery/docs/reference/v2/datasets#resource)
      * @param array $options [optional] Configuration options.
      */
     public function update(array $metadata, array $options = [])
     {
-        $options += $metadata;
-        $this->info = $this->connection->patchDataset($options + $this->identity);
+        $options = $this->applyEtagHeader(
+            $options
+            + $metadata
+            + $this->identity
+        );
 
-        return $this->info;
+        if (!isset($options['etag']) && !isset($options['retries'])) {
+            $options['retries'] = 0;
+        }
+
+        return $this->info = $this->connection->patchDataset($options);
     }
 
     /**
@@ -220,6 +245,9 @@ function (array $table) {
     /**
      * Creates a table.
      *
+     * Please note that by default the library will not attempt to retry this
+     * call on your behalf.
+     *
      * Example:
      * ```
      * $table = $dataset->createTable('aTable');
@@ -243,11 +271,15 @@ public function createTable($id, array $options = [])
             unset($options['metadata']);
         }
 
-        $response = $this->connection->insertTable([
-            'projectId' => $this->identity['projectId'],
-            'datasetId' => $this->identity['datasetId'],
-            'tableReference' => $this->identity + ['tableId' => $id]
-        ] + $options);
+        $response = $this->connection->insertTable(
+            [
+                'projectId' => $this->identity['projectId'],
+                'datasetId' => $this->identity['datasetId'],
+                'tableReference' => $this->identity + ['tableId' => $id]
+            ]
+            + $options
+            + ['retries' => 0]
+        );
 
         return new Table(
             $this->connection,

src/BigQuery/Exception/JobException.php

@@ -0,0 +1,46 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\BigQuery\Exception;
+
+use Google\Cloud\BigQuery\Job;
+
+/**
+ * Exception thrown when a job fails to complete.
+ */
+class JobException extends \RuntimeException
+{
+    /**
+     * @param string $message
+     * @param Job $job
+     */
+    public function __construct($message, Job $job)
+    {
+        $this->job = $job;
+        parent::__construct($message, 0);
+    }
+
+    /**
+     * Returns the job instance associated with the failure.
+     *
+     * @return Job
+     */
+    public function getJob()
+    {
+        return $this->job;
+    }
+}