From 46f7958e2f39848469f7aa8537da42d707ed3585 Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Tue, 5 Jan 2016 09:18:34 +0100
Subject: [PATCH] Document delay in table creation when insertAll is used with
 templateSuffix

---
 .../gcloud/bigquery/InsertAllRequest.java     | 22 +++++++++++++++++--
 .../gcloud/bigquery/ITBigQueryTest.java       |  2 +-
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java b/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java
index 8b6f573b1e3c..bd86f208480f 100644
--- a/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java
+++ b/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java
@@ -236,7 +236,16 @@ public Builder ignoreUnknownValues(boolean ignoreUnknownValues) {
     /**
      * If specified, the destination table is treated as a base template. Rows are inserted into an
      * instance table named "{destination}{templateSuffix}". BigQuery will manage the creation of
-     * the instance table, using the schema of the base template table.
+     * the instance table, using the schema of the base template table. Table creation might take
+     * some time. To obtain table's information after {@link BigQuery#insertAll(InsertAllRequest)}
+     * is called use:
+     * <pre> {@code
+     * String suffixTableId = ...;
+     * BaseTableInfo suffixTable = bigquery.getTable(DATASET, suffixTableId);
+     * while (suffixTable == null) {
+     *   Thread.sleep(1000L);
+     *   suffixTable = bigquery.getTable(DATASET, suffixTableId);
+     * }}</pre>
      *
      * @see <a
      *     href="https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables">
@@ -293,7 +302,16 @@ public Boolean skipInvalidRows() {
   /**
    * If specified, the destination table is treated as a base template. Rows are inserted into an
    * instance table named "{destination}{templateSuffix}". BigQuery will manage the creation of the
-   * instance table, using the schema of the base template table.
+   * instance table, using the schema of the base template table. Table creation might take some
+   * time. To obtain table's information after {@link BigQuery#insertAll(InsertAllRequest)} is
+   * called use:
+   * <pre> {@code
+   * String suffixTableId = ...;
+   * BaseTableInfo suffixTable = bigquery.getTable(DATASET, suffixTableId);
+   * while (suffixTable == null) {
+   *   Thread.sleep(1000L);
+   *   suffixTable = bigquery.getTable(DATASET, suffixTableId);
+   * }}</pre>
    *
    * @see <a
    *     href="https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables">
diff --git a/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java b/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java
index c07aa9f05f4c..798973149d20 100644
--- a/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java
+++ b/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java
@@ -506,11 +506,11 @@ public void testInsertAllWithSuffix() throws InterruptedException {
     assertEquals(0, response.insertErrors().size());
     String newTableName = tableName + "_suffix";
     BaseTableInfo suffixTable = bigquery.getTable(DATASET, newTableName, TableOption.fields());
+    // wait until the new table is created. If the table is never created the test will time-out
     while (suffixTable == null) {
       Thread.sleep(1000L);
       suffixTable = bigquery.getTable(DATASET, newTableName, TableOption.fields());
     }
-    assertNotNull(suffixTable);
     assertTrue(bigquery.delete(TableId.of(DATASET, tableName)));
     assertTrue(bigquery.delete(TableId.of(DATASET, newTableName)));
   }