diff --git a/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Dataset.java b/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Dataset.java index d9d6d4ce0866..02bec14de6b9 100644 --- a/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Dataset.java +++ b/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Dataset.java @@ -19,6 +19,7 @@ import static com.google.common.base.Preconditions.checkNotNull; import com.google.cloud.Page; +import com.google.cloud.bigquery.BigQuery.DatasetDeleteOption; import com.google.cloud.bigquery.BigQuery.DatasetOption; import com.google.cloud.bigquery.BigQuery.TableListOption; import com.google.cloud.bigquery.BigQuery.TableOption; @@ -144,6 +145,16 @@ public Dataset build() { /** * Checks if this dataset exists. * + *

Example of checking whether a dataset exists. + *

 {@code
+   * boolean exists = dataset.exists();
+   * if (exists) {
+   *   // the dataset exists
+   * } else {
+   *   // the dataset was not found
+   * }
+   * }
+ * * @return {@code true} if this dataset exists, {@code false} otherwise * @throws BigQueryException upon failure */ @@ -155,6 +166,14 @@ public boolean exists() { * Fetches current dataset's latest information. Returns {@code null} if the dataset does not * exist. * + *

Example of reloading a dataset. + *

 {@code
+   * Dataset latestDataset = dataset.reload();
+   * if (latestDataset == null) {
+   *   // The dataset was not found
+   * }
+   * }
+ * * @param options dataset options * @return a {@code Dataset} object with latest information or {@code null} if not found * @throws BigQueryException upon failure @@ -167,6 +186,14 @@ public Dataset reload(DatasetOption... options) { * Updates the dataset's information with this dataset's information. Dataset's user-defined id * cannot be changed. A new {@code Dataset} object is returned. * + *

Example of updating a dataset. + *

 {@code
+   * String friendlyName = "my_friendly_name";
+   * Builder builder = dataset.toBuilder();
+   * builder.friendlyName(friendlyName);
+   * Dataset updatedDataset = builder.build().update();
+   * }
+ * * @param options dataset options * @return a {@code Dataset} object with updated information * @throws BigQueryException upon failure @@ -178,16 +205,36 @@ public Dataset update(DatasetOption... options) { /** * Deletes this dataset. * + *

Example of deleting a dataset. + *

 {@code
+   * boolean deleted = dataset.delete();
+   * if (deleted) {
+   *   // The dataset was deleted
+   * } else {
+   *   // The dataset was not found
+   * }
+   * }
+ * * @return {@code true} if dataset was deleted, {@code false} if it was not found * @throws BigQueryException upon failure */ - public boolean delete() { - return bigquery.delete(datasetId()); + public boolean delete(DatasetDeleteOption... options) { + return bigquery.delete(datasetId(), options); } /** * Returns the paginated list of tables in this dataset. * + *

Example of listing tables in the dataset. + *

 {@code
+   * Page tables = dataset.list();
+   * Iterator
tableIterator = tables.iterateAll(); + * while (tableIterator.hasNext()) { + * Table table = tableIterator.next(); + * // do something with the table + * } + * } + * * @param options options for listing tables * @throws BigQueryException upon failure */ @@ -198,6 +245,12 @@ public Page
list(TableListOption... options) { /** * Returns the requested table in this dataset or {@code null} if not found. * + *

Example of getting a table in the dataset. + *

 {@code
+   * String tableName = “my_table”;
+   * Table table = dataset.get(tableName);
+   * }
+ * * @param table user-defined id of the requested table * @param options table options * @throws BigQueryException upon failure @@ -209,6 +262,18 @@ public Table get(String table, TableOption... options) { /** * Creates a new table in this dataset. * + *

Example of creating a table in the dataset with schema and time partitioning. + *

 {@code
+   * String tableName = “my_table”;
+   * String fieldName = “my_field”;
+   * Schema schema = Schema.of(Field.of(fieldName, Type.string()));
+   * StandardTableDefinition definition = StandardTableDefinition.builder()
+   *     .schema(schema)
+   *     .timePartitioning(TimePartitioning.of(TimePartitioning.Type.DAY))
+   *     .build();
+   * Table table = dataset.create(tableName, definition);
+   * }
+ * * @param table the table's user-defined id * @param definition the table's definition * @param options options for table creation diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/bigquery/snippets/DatasetSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/bigquery/snippets/DatasetSnippets.java new file mode 100644 index 000000000000..a44c7f6f166c --- /dev/null +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/bigquery/snippets/DatasetSnippets.java @@ -0,0 +1,153 @@ +/* + * Copyright 2016 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. + */ + +/* + * EDITING INSTRUCTIONS + * This file is referenced in Dataset’s javadoc. Any change to this file should be reflected in + * Dataset’s javadoc. +*/ + +package com.google.cloud.examples.bigquery.snippets; + +import com.google.cloud.Page; +import com.google.cloud.bigquery.Dataset; +import com.google.cloud.bigquery.Dataset.Builder; +import com.google.cloud.bigquery.Field; +import com.google.cloud.bigquery.Field.Type; +import com.google.cloud.bigquery.Schema; +import com.google.cloud.bigquery.StandardTableDefinition; +import com.google.cloud.bigquery.Table; +import com.google.cloud.bigquery.TimePartitioning; + +import java.util.Iterator; + +/** + * This class contains a number of snippets for the {@link Dataset} interface. + */ +public class DatasetSnippets { + + private final Dataset dataset; + + public DatasetSnippets(Dataset dataset) { + this.dataset = dataset; + } + + /** + * Example of checking whether a dataset exists. + */ + // [TARGET exists()] + public boolean doesDatasetExist() { + // [START exists] + boolean exists = dataset.exists(); + if (exists) { + // the dataset exists + } else { + // the dataset was not found + } + // [END exists] + return exists; + } + + /** + * Example of reloading a dataset. + */ + // [TARGET reload(DatasetOption...)] + public Dataset reloadDataset() { + // [START reload] + Dataset latestDataset = dataset.reload(); + if (latestDataset == null) { + // The dataset was not found + } + // [END reload] + return latestDataset; + } + + /** + * Example of updating a dataset. + */ + // [TARGET update(DatasetOption...)] + // [VARIABLE "my_friendly_name"] + public Dataset updateDataset(String friendlyName) { + // [START update] + Builder builder = dataset.toBuilder(); + builder.friendlyName(friendlyName); + Dataset updatedDataset = builder.build().update(); + // [END update] + return updatedDataset; + } + + /** + * Example of deleting a dataset. + */ + // [TARGET delete(DatasetDeleteOption...)] + public boolean deleteDataset() { + // [START delete] + boolean deleted = dataset.delete(); + if (deleted) { + // The dataset was deleted + } else { + // The dataset was not found + } + // [END delete] + return deleted; + } + + /** + * Example of listing tables in the dataset. + */ + // [TARGET list(TableListOption...)] + public Page
list() { + // [START list] + Page
tables = dataset.list(); + Iterator
tableIterator = tables.iterateAll(); + while (tableIterator.hasNext()) { + Table table = tableIterator.next(); + // do something with the table + } + // [END list] + return tables; + } + + /** + * Example of getting a table in the dataset. + */ + // [TARGET get(String, TableOption...)] + // [VARIABLE “my_table”] + public Table getTable(String tableName) { + // [START getTable] + Table table = dataset.get(tableName); + // [END getTable] + return table; + } + + /** + * Example of creating a table in the dataset with schema and time partitioning. + */ + // [TARGET create(String, TableDefinition, TableOption...)] + // [VARIABLE “my_table”] + // [VARIABLE “my_field”] + public Table createTable(String tableName, String fieldName) { + // [START createTable] + Schema schema = Schema.of(Field.of(fieldName, Type.string())); + StandardTableDefinition definition = StandardTableDefinition.builder() + .schema(schema) + .timePartitioning(TimePartitioning.of(TimePartitioning.Type.DAY)) + .build(); + Table table = dataset.create(tableName, definition); + // [END createTable] + return table; + } +} diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/bigquery/snippets/ITDatasetSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/bigquery/snippets/ITDatasetSnippets.java new file mode 100644 index 000000000000..7ac2773b0aee --- /dev/null +++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/bigquery/snippets/ITDatasetSnippets.java @@ -0,0 +1,172 @@ +/* + * Copyright 2016 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. + */ + +package com.google.cloud.examples.bigquery.snippets; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNotNull; +import static org.junit.Assert.assertNull; +import static org.junit.Assert.assertTrue; + +import com.google.cloud.Page; +import com.google.cloud.bigquery.BigQuery; +import com.google.cloud.bigquery.BigQuery.DatasetDeleteOption; +import com.google.cloud.bigquery.Dataset; +import com.google.cloud.bigquery.Dataset.Builder; +import com.google.cloud.bigquery.DatasetInfo; +import com.google.cloud.bigquery.Field; +import com.google.cloud.bigquery.StandardTableDefinition; +import com.google.cloud.bigquery.Table; +import com.google.cloud.bigquery.testing.RemoteBigQueryHelper; + +import org.junit.AfterClass; +import org.junit.Before; +import org.junit.BeforeClass; +import org.junit.Test; + +import java.util.Iterator; + +public class ITDatasetSnippets { + + private static final String DATASET = RemoteBigQueryHelper.generateDatasetName(); + private static final String NON_EXISTING_DATASET = RemoteBigQueryHelper.generateDatasetName(); + private static final String FRIENDLY_NAME = "some_friendly_name"; + + private static BigQuery bigquery; + private static Dataset nonExistingDataset; + private static Dataset dataset; + private static DatasetSnippets datasetSnippets; + private static DatasetSnippets nonExistingDatasetSnippets; + + @BeforeClass + public static void beforeClass() { + bigquery = RemoteBigQueryHelper.create().options().service(); + dataset = bigquery.create(DatasetInfo.builder(DATASET).build()); + nonExistingDataset = bigquery.create(DatasetInfo.builder(NON_EXISTING_DATASET).build()); + nonExistingDataset.delete(DatasetDeleteOption.deleteContents()); + } + + @Before + public void before() { + datasetSnippets = new DatasetSnippets(dataset); + nonExistingDatasetSnippets = new DatasetSnippets(nonExistingDataset); + } + + @AfterClass + public static void afterClass() { + bigquery.delete(DATASET, DatasetDeleteOption.deleteContents()); + } + + @Test + public void testExistsNonExistingDataset() { + assertFalse(nonExistingDatasetSnippets.doesDatasetExist()); + } + + @Test + public void testExists() { + assertTrue(datasetSnippets.doesDatasetExist()); + } + + @Test + public void testReloadNonExistingDataset() { + assertNull(nonExistingDatasetSnippets.reloadDataset()); + } + + @Test + public void testReload() { + assertNull(dataset.friendlyName()); + + Builder builder = dataset.toBuilder(); + builder.friendlyName(FRIENDLY_NAME); + builder.build().update(); + + Dataset reloadedDataset = datasetSnippets.reloadDataset(); + assertEquals(FRIENDLY_NAME, reloadedDataset.friendlyName()); + } + + @Test + public void testUpdate() { + assertNull(dataset.friendlyName()); + + Dataset updatedDataset = datasetSnippets.updateDataset(FRIENDLY_NAME); + assertEquals(FRIENDLY_NAME, updatedDataset.friendlyName()); + } + + @Test + public void testDeleteNonExistingDataset() { + assertFalse(nonExistingDatasetSnippets.deleteDataset()); + } + + @Test + public void testDelete() { + String datasetName = RemoteBigQueryHelper.generateDatasetName(); + DatasetInfo dataset = DatasetInfo.builder(datasetName).build(); + DatasetSnippets datasetSnippets = new DatasetSnippets(bigquery.create(dataset)); + assertTrue(datasetSnippets.deleteDataset()); + } + + @Test + public void testListTablesEmpty() { + Page
tables = datasetSnippets.list(); + assertFalse(tables.iterateAll().hasNext()); + } + + @Test + public void testListTablesNotEmpty() { + String expectedTableName = "test_table"; + + dataset.create(expectedTableName, StandardTableDefinition.builder().build()); + Page
tables = datasetSnippets.list(); + Iterator
iterator = tables.iterateAll(); + assertTrue(iterator.hasNext()); + + Table actualTable = iterator.next(); + assertEquals(expectedTableName, actualTable.tableId().table()); + assertFalse(iterator.hasNext()); + + bigquery.delete(DATASET, expectedTableName); + } + + @Test + public void testGetTable() { + String expectedTableName = "test_table"; + + dataset.create(expectedTableName, StandardTableDefinition.builder().build()); + Table actualTable = datasetSnippets.getTable(expectedTableName); + + assertNotNull(actualTable); + assertEquals(expectedTableName, actualTable.tableId().table()); + + bigquery.delete(DATASET, expectedTableName); + } + + @Test + public void testCreateTable() { + String expectedTableName = "test_table"; + String expectedFieldName = "test_field"; + + Table actualTable = datasetSnippets.createTable(expectedTableName, expectedFieldName); + assertNotNull(actualTable); + assertEquals(expectedTableName, actualTable.tableId().table()); + assertEquals(1, actualTable.definition().schema().fields().size()); + + Field actualField = actualTable.definition().schema().fields().get(0); + assertEquals(expectedFieldName, actualField.name()); + + bigquery.delete(DATASET, expectedTableName); + } +}