update tests/docs and add copy/load

Author: dwsupplee

src/BigQuery/BigQueryClient.php

@@ -21,6 +21,7 @@
 use Google\Cloud\BigQuery\Connection\Rest;
 use Google\Cloud\BigQuery\Exception\JobException;
 use Google\Cloud\BigQuery\Job;
+use Google\Cloud\Core\ArrayTrait;
 use Google\Cloud\Core\ClientTrait;
 use Google\Cloud\Core\Int64;
 use Google\Cloud\Core\Iterator\ItemIterator;
@@ -42,6 +43,7 @@
  */
 class BigQueryClient
 {
+    use ArrayTrait;
     use ClientTrait;
 
     const VERSION = '0.2.2';
@@ -111,10 +113,10 @@ public function __construct(array $config = [])
      * set of options at once.
      *
      * Unless otherwise specified, all configuration options will default based
-     * on the
-     * [Jobs configuration API documentation](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration)
-     * except for `configuration.query.useLegacy`, which defaults to `false` in
-     * this client.
+     * on the [Jobs configuration API documentation]
+     * (https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration)
+     * except for `configuration.query.useLegacySql`, which defaults to `false`
+     * in this client.
      *
      * Example:
      * ```
@@ -127,7 +129,7 @@ public function __construct(array $config = [])
      * // Set create disposition using fluent setters.
      * $queryJobConfig = $bigQuery->query(
      *     'SELECT commit FROM `bigquery-public-data.github_repos.commits` LIMIT 100'
-     * )->createDisposition(QueryJobConfiguration::CREATE_DISPOSITION_CREATE_NEVER);
+     * )->createDisposition('CREATE_NEVER');
      * ```
      *
      * ```
@@ -138,7 +140,7 @@ public function __construct(array $config = [])
      *     [
      *         'configuration' => [
      *             'query' => [
-     *                 'createDisposition' => QueryJobConfiguration::CREATE_DISPOSITION_CREATE_NEVER
+     *                 'createDisposition' => 'CREATE_NEVER'
      *             ]
      *         ]
      *     ]
@@ -233,7 +235,7 @@ public function query($query, array $options = [])
      *
      * @see https://cloud.google.com/bigquery/docs/reference/v2/jobs/query Query API documentation.
      *
-     * @param QueryJobConfiguration $query A BigQuery SQL query.
+     * @param QueryJobConfiguration $query A BigQuery SQL query configuration.
      * @param array $options [optional] {
      *     Configuration options.
      *
@@ -251,7 +253,7 @@ public function query($query, array $options = [])
      * @throws JobException If the maximum number of retries while waiting for
      *         query completion has been exceeded.
      */
-    public function runQuery(QueryJobConfiguration $query, array $options = [])
+    public function runQuery(JobConfigurationInterface $query, array $options = [])
     {
         $queryResultsOptions = $this->pluckArray([
             'maxResults',
@@ -289,11 +291,11 @@ public function runQuery(QueryJobConfiguration $query, array $options = [])
      *
      * @see https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert Jobs insert API documentation.
      *
-     * @param QueryJobConfiguration $query A BigQuery SQL query.
+     * @param QueryJobConfiguration $query A BigQuery SQL query configuration.
      * @param array $options [optional] Configuration options.
      * @return Job
      */
-    public function startQuery(QueryJobConfiguration $query, array $options = [])
+    public function startQuery(JobConfigurationInterface $query, array $options = [])
     {
         $config = $query->toArray();
         $response = $this->connection->insertJob($config + $options);

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;
+    }
+}