Skip to content

Commit c59f31d

Browse files
tswasttswast
authored
Merge pull request googleapis#3180 from alixhami/bq-standardize-region-tags
BigQuery: Standardizes region tags and adds query snippets from java-docs-samples
2 parents d7b1451 + 1206737 commit c59f31d

File tree

14 files changed

+829
-421
lines changed

14 files changed

+829
-421
lines changed

‎google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java‎

Lines changed: 43 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -633,6 +633,7 @@ public int hashCode() {
633633
*
634634
* <p>Example of listing datasets, specifying the page size.
635635
* <pre> {@code
636+
* // List datasets in the default project
636637
* Page<Dataset> datasets = bigquery.listDatasets(DatasetListOption.pageSize(100));
637638
* for (Dataset dataset : datasets.iterateAll()) {
638639
* // do something with the dataset
@@ -653,6 +654,7 @@ public int hashCode() {
653654
* <p>Example of listing datasets in a project, specifying the page size.
654655
* <pre> {@code
655656
* String projectId = "my_project_id";
657+
* // List datasets in a specified project
656658
* Page<Dataset> datasets = bigquery.listDatasets(projectId, DatasetListOption.pageSize(100));
657659
* for (Dataset dataset : datasets.iterateAll()) {
658660
* // do something with the dataset
@@ -748,12 +750,12 @@ public int hashCode() {
748750
/**
749751
* Updates dataset information.
750752
*
751-
* <p>Example of updating a dataset by changing its friendly name.
753+
* <p>Example of updating a dataset by changing its description.
752754
* <pre> {@code
753755
* String datasetName = "my_dataset_name";
754-
* String newFriendlyName = "some_new_friendly_name";
756+
* String newDescription = "some_new_description";
755757
* Dataset oldDataset = bigquery.getDataset(datasetName);
756-
* DatasetInfo datasetInfo = oldDataset.toBuilder().setFriendlyName(newFriendlyName).build();
758+
* DatasetInfo datasetInfo = oldDataset.toBuilder().setDescription(newDescription).build();
757759
* Dataset newDataset = bigquery.update(datasetInfo);
758760
* }</pre>
759761
*
@@ -764,13 +766,13 @@ public int hashCode() {
764766
/**
765767
* Updates table information.
766768
*
767-
* <p>Example of updating a table by changing its friendly name.
769+
* <p>Example of updating a table by changing its description.
768770
* <pre> {@code
769771
* String datasetName = "my_dataset_name";
770772
* String tableName = "my_table_name";
771-
* String newFriendlyName = "new_friendly_name";
773+
* String newDescription = "new_description";
772774
* Table oldTable = bigquery.getTable(datasetName, tableName);
773-
* TableInfo tableInfo = oldTable.toBuilder().setFriendlyName(newFriendlyName).build();
775+
* TableInfo tableInfo = oldTable.toBuilder().setDescription(newDescription).build();
774776
* Table newTable = bigquery.update(tableInfo);
775777
* }</pre>
776778
*
@@ -974,8 +976,7 @@ TableResult listTableData(
974976
* or "EU", {@link #getJob(JobId, JobOption...)} must be used instead.
975977
*
976978
* <p>Example of getting a job.
977-
*
978-
* <pre>{@code
979+
* <pre> {@code
979980
* String jobName = "my_job_name";
980981
* Job job = bigquery.getJob(jobName);
981982
* if (job == null) {
@@ -992,8 +993,7 @@ TableResult listTableData(
992993
* or "EU", the {@code jobId} must specify the job location.
993994
*
994995
* <p>Example of getting a job.
995-
*
996-
* <pre>{@code
996+
* <pre> {@code
997997
* String jobName = "my_job_name";
998998
* JobId jobIdObject = JobId.of(jobName);
999999
* Job job = bigquery.getJob(jobIdObject);
@@ -1029,8 +1029,7 @@ TableResult listTableData(
10291029
* <p>If the location of the job is not "US" or "EU", {@link #cancel(JobId)} must be used instead.
10301030
*
10311031
* <p>Example of cancelling a job.
1032-
*
1033-
* <pre>{@code
1032+
* <pre> {@code
10341033
* String jobName = "my_job_name";
10351034
* boolean success = bigquery.cancel(jobName);
10361035
* if (success) {
@@ -1055,8 +1054,7 @@ TableResult listTableData(
10551054
* location.
10561055
*
10571056
* <p>Example of cancelling a job.
1058-
*
1059-
* <pre>{@code
1057+
* <pre> {@code
10601058
* String jobName = "my_job_name";
10611059
* JobId jobId = JobId.of(jobName);
10621060
* boolean success = bigquery.cancel(jobId);
@@ -1083,26 +1081,19 @@ TableResult listTableData(
10831081
* queries. Since dry-run queries are not actually executed, there's no way to retrieve results.
10841082
*
10851083
* <p>Example of running a query.
1086-
*
1087-
* <pre>{@code
1088-
* String query = "SELECT unique(corpus) FROM [bigquery-public-data:samples.shakespeare]";
1084+
* <pre> {@code
1085+
* // BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
1086+
* String query =
1087+
* "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
10891088
* QueryJobConfiguration queryConfig =
1090-
* QueryJobConfiguration.newBuilder(query).setUseLegacySql(true).build();
1089+
* QueryJobConfiguration.newBuilder(query).build();
1090+
*
1091+
* // Print the results.
10911092
* for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
1092-
* // do something with the data
1093-
* }
1094-
* }</pre>
1095-
*
1096-
* <p>Example of running a query with query parameters.
1097-
*
1098-
* <pre>{@code
1099-
* String query = "SELECT distinct(corpus) FROM `bigquery-public-data.samples.shakespeare` where word_count > @wordCount";
1100-
* // Note, standard SQL is required to use query parameters. Legacy SQL will not work.
1101-
* QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query)
1102-
* .addNamedParameter("wordCount", QueryParameterValue.int64(5))
1103-
* .build();
1104-
* for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
1105-
* // do something with the data
1093+
* for (FieldValue val : row) {
1094+
* System.out.printf("%s,", val.toString());
1095+
* }
1096+
* System.out.printf("\n");
11061097
* }
11071098
* }</pre>
11081099
*
@@ -1148,8 +1139,7 @@ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption...
11481139
* not in "US" or "EU", {@link #writer(JobId, WriteChannelConfiguration)} must be used instead.
11491140
*
11501141
* <p>Example of creating a channel with which to write to a table.
1151-
*
1152-
* <pre>{@code
1142+
* <pre> {@code
11531143
* String datasetName = "my_dataset_name";
11541144
* String tableName = "my_table_name";
11551145
* String csvData = "StringValue1\nStringValue2\n";
@@ -1159,31 +1149,33 @@ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption...
11591149
* .setFormatOptions(FormatOptions.csv())
11601150
* .build();
11611151
* TableDataWriteChannel writer = bigquery.writer(writeChannelConfiguration);
1162-
* // Write data to writer
1163-
* try {
1164-
* writer.write(ByteBuffer.wrap(csvData.getBytes(Charsets.UTF_8)));
1165-
* } finally {
1166-
* writer.close();
1167-
* }
1168-
* // Get load job
1169-
* Job job = writer.getJob();
1170-
* job = job.waitFor();
1171-
* LoadStatistics stats = job.getStatistics();
1172-
* return stats.getOutputRows();
1152+
* // Write data to writer
1153+
* try {
1154+
* writer.write(ByteBuffer.wrap(csvData.getBytes(Charsets.UTF_8)));
1155+
* } finally {
1156+
* writer.close();
1157+
* }
1158+
* // Get load job
1159+
* Job job = writer.getJob();
1160+
* job = job.waitFor();
1161+
* LoadStatistics stats = job.getStatistics();
1162+
* return stats.getOutputRows();
11731163
* }</pre>
11741164
*
11751165
* <p>Example of writing a local file to a table.
1176-
*
1177-
* <pre>{@code
1166+
* <pre> {@code
11781167
* String datasetName = "my_dataset_name";
11791168
* String tableName = "my_table_name";
11801169
* Path csvPath = FileSystems.getDefault().getPath(".", "my-data.csv");
1170+
* String location = "us";
11811171
* TableId tableId = TableId.of(datasetName, tableName);
11821172
* WriteChannelConfiguration writeChannelConfiguration =
11831173
* WriteChannelConfiguration.newBuilder(tableId)
11841174
* .setFormatOptions(FormatOptions.csv())
11851175
* .build();
1186-
* TableDataWriteChannel writer = bigquery.writer(writeChannelConfiguration);
1176+
* // The location must be specified; other fields can be auto-detected.
1177+
* JobId jobId = JobId.newBuilder().setLocation(location).build();
1178+
* TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
11871179
* // Write data to writer
11881180
* try (OutputStream stream = Channels.newOutputStream(writer)) {
11891181
* Files.copy(csvPath, stream);
@@ -1205,13 +1197,11 @@ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption...
12051197
* not in "US" or "EU", the {@code jobId} must contain the location of the job.
12061198
*
12071199
* <p>Example of creating a channel with which to write to a table.
1208-
*
1209-
* <pre>{@code
1200+
* <pre> {@code
12101201
* String datasetName = "my_dataset_name";
12111202
* String tableName = "my_table_name";
12121203
* String csvData = "StringValue1\nStringValue2\n";
1213-
* String csvData = "StringValue1\nStringValue2\n";
1214-
* String location = "asia-northeast1";
1204+
* String location = "us";
12151205
* TableId tableId = TableId.of(datasetName, tableName);
12161206
* WriteChannelConfiguration writeChannelConfiguration =
12171207
* WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
@@ -1230,6 +1220,7 @@ TableResult query(QueryJobConfiguration configuration, JobId jobId, JobOption...
12301220
* LoadStatistics stats = job.getStatistics();
12311221
* return stats.getOutputRows();
12321222
* }</pre>
1223+
*
12331224
*/
12341225
TableDataWriteChannel writer(JobId jobId, WriteChannelConfiguration writeChannelConfiguration);
12351226
}

‎google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Dataset.java‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -240,9 +240,7 @@ public boolean delete(DatasetDeleteOption... options) {
240240
* <p>Example of listing tables in the dataset.
241241
* <pre> {@code
242242
* Page<Table> tables = dataset.list();
243-
* Iterator<Table> tableIterator = tables.iterateAll();
244-
* while (tableIterator.hasNext()) {
245-
* Table table = tableIterator.next();
243+
* for (Table table : tables.iterateAll()) {
246244
* // do something with the table
247245
* }
248246
* }</pre>
@@ -278,7 +276,7 @@ public Table get(String tableId, TableOption... options) {
278276
* <pre> {@code
279277
* String tableName = “my_table”;
280278
* String fieldName = “my_field”;
281-
* Schema schema = Schema.of(Field.of(fieldName, Type.string()));
279+
* Schema schema = Schema.of(Field.of(fieldName, LegacySQLTypeName.STRING));
282280
* StandardTableDefinition definition = StandardTableDefinition.newBuilder()
283281
* .setSchema(schema)
284282
* .setTimePartitioning(TimePartitioning.of(TimePartitioning.Type.DAY))

‎google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java‎

Lines changed: 10 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -154,8 +154,7 @@ public Job build() {
154154
* Checks if this job exists.
155155
*
156156
* <p>Example of checking that a job exists.
157-
*
158-
* <pre>{@code
157+
* <pre> {@code
159158
* if (!job.exists()) {
160159
* // job doesn't exist
161160
* }
@@ -174,8 +173,7 @@ public boolean exists() {
174173
* not exist this method returns {@code true}.
175174
*
176175
* <p>Example of waiting for a job until it reports that it is done.
177-
*
178-
* <pre>{@code
176+
* <pre> {@code
179177
* while (!job.isDone()) {
180178
* Thread.sleep(1000L);
181179
* }
@@ -198,8 +196,7 @@ public boolean isDone() {
198196
* 12 hours as a total timeout and unlimited number of attempts.
199197
*
200198
* <p>Example usage of {@code waitFor()}.
201-
*
202-
* <pre>{@code
199+
* <pre> {@code
203200
* Job completedJob = job.waitFor();
204201
* if (completedJob == null) {
205202
* // job no longer exists
@@ -210,14 +207,12 @@ public boolean isDone() {
210207
* }
211208
* }</pre>
212209
*
213-
* <p>Example usage of {@code waitFor()} with non-jittered custom max delay and total timeout.
214-
*
215-
* <pre>{@code
210+
* <p>Example usage of {@code waitFor()} with checking period and timeout.
211+
* <pre> {@code
216212
* Job completedJob =
217213
* job.waitFor(
218-
* RetryOption.maxRetryDelay(Duration.ofSeconds(30)),
219-
* RetryOption.totalTimeout(Duration.ofMinutes(1)),
220-
* RetryOption.jittered(false));
214+
* RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
215+
* RetryOption.totalTimeout(Duration.ofMinutes(1)));
221216
* if (completedJob == null) {
222217
* // job no longer exists
223218
* } else if (completedJob.getStatus().getError() != null) {
@@ -257,16 +252,6 @@ public Job waitFor(RetryOption... waitOptions) throws InterruptedException {
257252
* the current {@code Job} instance is not updated. To get the new state, call {@link
258253
* #waitFor(RetryOption...)} or {@link #reload(JobOption...)}.
259254
*
260-
* <p>Example of getting the results of a query job.
261-
*
262-
* <pre>{@code
263-
* Job job = bigquery.create(queryJobInfo);
264-
* TableResult result = job.getQueryResults();
265-
* for (FieldValueList row : result.iterateAll()) {
266-
* // do something with the data
267-
* }
268-
* }</pre>
269-
*
270255
* @throws BigQueryException upon failure
271256
*/
272257
public TableResult getQueryResults(QueryResultsOption... options)
@@ -371,17 +356,15 @@ public boolean shouldRetry(Throwable prevThrowable, Job prevResponse) {
371356
* Fetches current job's latest information. Returns {@code null} if the job does not exist.
372357
*
373358
* <p>Example of reloading all fields until job status is DONE.
374-
*
375-
* <pre>{@code
359+
* <pre> {@code
376360
* while (job.getStatus().getState() != JobStatus.State.DONE) {
377361
* Thread.sleep(1000L);
378362
* job = job.reload();
379363
* }
380364
* }</pre>
381365
*
382366
* <p>Example of reloading status field until job status is DONE.
383-
*
384-
* <pre>{@code
367+
* <pre> {@code
385368
* while (job.getStatus().getState() != JobStatus.State.DONE) {
386369
* Thread.sleep(1000L);
387370
* job = job.reload(BigQuery.JobOption.fields(BigQuery.JobField.STATUS));
@@ -401,8 +384,7 @@ public Job reload(JobOption... options) {
401384
* Sends a job cancel request.
402385
*
403386
* <p>Example of cancelling a job.
404-
*
405-
* <pre>{@code
387+
* <pre> {@code
406388
* if (job.cancel()) {
407389
* return true; // job successfully cancelled
408390
* } else {

0 commit comments

Comments
 (0)