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