Skip to content

Commit 2d1fc92

Browse files
mziccardmziccard
committed
Minor consistency fixes to Table snippets, add snippets to javadoc
1 parent 86f5e14 commit 2d1fc92

3 files changed

Lines changed: 251 additions & 282 deletions

File tree

  • google-cloud-bigquery/src/main/java/com/google/cloud/bigquery
  • google-cloud-examples/src

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

Lines changed: 65 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -139,10 +139,13 @@ public Table build() {
139139
/**
140140
* Checks if this table exists.
141141
*
142-
* <p>Example of ensuring that a table exists.
142+
* <p>Example of checking if the table exists.
143143
* <pre> {@code
144-
* if (!table.exists()) {
145-
* throw new RuntimeException("Table does not exist.");
144+
* boolean exists = table.exists();
145+
* if (exists) {
146+
* // the table exists
147+
* } else {
148+
* // the table was not found
146149
* }
147150
* }</pre>
148151
*
@@ -156,11 +159,15 @@ public boolean exists() {
156159
/**
157160
* Fetches current table's latest information. Returns {@code null} if the table does not exist.
158161
*
159-
* <p>Example of fetching a table's latest information, specifying particular table field options.
162+
* <p>Example of fetching the table's latest information, specifying particular table fields to
163+
* get.
160164
* <pre> {@code
161165
* TableField field1 = TableField.LAST_MODIFIED_TIME;
162166
* TableField field2 = TableField.NUM_ROWS;
163-
* Table reloaded = table.reload(TableOption.fields(field1, field2));
167+
* Table latestTable = table.reload(TableOption.fields(field1, field2));
168+
* if (latestTable == null) {
169+
* // the table was not found
170+
* }
164171
* }</pre>
165172
*
166173
* @param options table options
@@ -175,11 +182,9 @@ public Table reload(TableOption... options) {
175182
* Updates the table's information with this table's information. Dataset's and table's
176183
* user-defined ids cannot be changed. A new {@code Table} object is returned.
177184
*
178-
* <p>Example of updating a table's information, specifying particular table field options.
185+
* <p>Example of updating the table's information.
179186
* <pre> {@code
180-
* TableField field1 = TableField.LAST_MODIFIED_TIME;
181-
* TableField field2 = TableField.NUM_ROWS;
182-
* Table updated = table.update(TableOption.fields(field1, field2));
187+
* Table updatedTable = table.toBuilder().description("new description").build().update();
183188
* }</pre>
184189
*
185190
* @param options dataset options
@@ -193,9 +198,14 @@ public Table update(TableOption... options) {
193198
/**
194199
* Deletes this table.
195200
*
196-
* <p>Example of deleting a table.
201+
* <p>Example of deleting the table.
197202
* <pre> {@code
198-
* table.delete();
203+
* boolean deleted = table.delete();
204+
* if (deleted) {
205+
* // the table was deleted
206+
* } else {
207+
* // the table was not found
208+
* }
199209
* }</pre>
200210
*
201211
* @return {@code true} if table was deleted, {@code false} if it was not found
@@ -208,7 +218,7 @@ public boolean delete() {
208218
/**
209219
* Insert rows into the table.
210220
*
211-
* <p>Example of inserting rows into a table.
221+
* <p>Example of inserting rows into the table.
212222
* <pre> {@code
213223
* String rowId1 = "rowId1";
214224
* String rowId2 = "rowId2";
@@ -236,7 +246,7 @@ public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows)
236246
/**
237247
* Insert rows into the table.
238248
*
239-
* <p>Example of inserting rows into a table which ignores invalid rows.
249+
* <p>Example of inserting rows into the table, ignoring invalid rows.
240250
* <pre> {@code
241251
* String rowId1 = "rowId1";
242252
* String rowId2 = "rowId2";
@@ -273,10 +283,14 @@ public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows,
273283
/**
274284
* Returns the paginated list rows in this table.
275285
*
276-
* <p>Example of getting a paginated list of rows in a table.
286+
* <p>Example of listing rows in the table.
277287
* <pre> {@code
278288
* Page<List<FieldValue>> page = table.list(TableDataListOption.pageSize(100));
279-
* // do something with page
289+
* Iterator<List<FieldValue>> rowIterator = page.iterateAll();
290+
* while (rowIterator.hasNext()) {
291+
* List<FieldValue> row = rowIterator.next();
292+
* // do something with the row
293+
* }
280294
* }</pre>
281295
*
282296
* @param options table data list options
@@ -291,25 +305,23 @@ public Page<List<FieldValue>> list(TableDataListOption... options)
291305
* Starts a BigQuery Job to copy the current table to the provided destination table. Returns the
292306
* started {@link Job} object.
293307
*
294-
* <p>Example of copying a table to a destination table and dataset referenced by name.
308+
* <p>Example of copying the table to a destination table.
295309
* <pre> {@code
296310
* String datasetName = "my_dataset";
297311
* String tableName = "my_destination_table";
298312
* Job job = table.copy(datasetName, tableName);
299-
*
300313
* // Wait for the job to complete.
301314
* try {
302315
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
303-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
316+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
304317
* if (completedJob != null && completedJob.status().error() == null) {
305-
* // Job completed successfully.
318+
* // Job completed successfully
306319
* } else {
307-
* // Handle error case.
320+
* // Handle error case
308321
* }
309322
* } catch (InterruptedException | TimeoutException e) {
310-
* // Handle interrupted wait.
323+
* // Handle interrupted wait
311324
* }
312-
*
313325
* }</pre>
314326
*
315327
* @param destinationDataset the user-defined id of the destination dataset
@@ -326,26 +338,24 @@ public Job copy(String destinationDataset, String destinationTable, JobOption...
326338
* Starts a BigQuery Job to copy the current table to the provided destination table. Returns the
327339
* started {@link Job} object.
328340
*
329-
* <p>Example copying a table to a destination table referenced by table ID.
341+
* <p>Example copying the table to a destination table.
330342
* <pre> {@code
331343
* String dataset = "my_dataset";
332-
* String tableName = "copy_destination";
344+
* String tableName = "my_destination_table";
333345
* TableId destinationId = TableId.of(dataset, tableName);
334346
* JobOption options = JobOption.fields(JobField.STATUS, JobField.USER_EMAIL);
335-
*
336347
* Job job = table.copy(destinationId, options);
337-
*
338348
* // Wait for the job to complete.
339349
* try {
340350
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
341-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
351+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
342352
* if (completedJob != null && completedJob.status().error() == null) {
343353
* // Job completed successfully.
344354
* } else {
345355
* // Handle error case.
346356
* }
347357
* } catch (InterruptedException | TimeoutException e) {
348-
* // Handle interrupted wait.
358+
* // Handle interrupted wait
349359
* }
350360
* }</pre>
351361
*
@@ -366,20 +376,19 @@ public Job copy(TableId destinationTable, JobOption... options)
366376
* <p>Example extracting data to single Google Cloud Storage file.
367377
* <pre> {@code
368378
* String format = "CSV";
369-
* String gcsUrl = "gs://myapp.appspot.com/filename.csv";
379+
* String gcsUrl = "gs://my_bucket/filename.csv";
370380
* Job job = table.extract(format, gcsUrl);
371-
*
372-
* // Wait for the job to complete.
381+
* // Wait for the job to complete
373382
* try {
374383
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
375-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
384+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
376385
* if (completedJob != null && completedJob.status().error() == null) {
377-
* // Job completed successfully.
386+
* // Job completed successfully
378387
* } else {
379-
* // Handle error case.
388+
* // Handle error case
380389
* }
381390
* } catch (InterruptedException | TimeoutException e) {
382-
* // Handle interrupted wait.
391+
* // Handle interrupted wait
383392
* }
384393
* }</pre>
385394
*
@@ -398,28 +407,26 @@ public Job extract(String format, String destinationUri, JobOption... options)
398407
* Starts a BigQuery Job to extract the current table to the provided destination URIs. Returns
399408
* the started {@link Job} object.
400409
*
401-
* <p>Example extracting data to a list of Google Cloud Storage files.
410+
* <p>Example of partitioning data to a list of Google Cloud Storage files.
402411
* <pre> {@code
403412
* String format = "CSV";
404-
* String gcsUrl1 = "gs://myapp.appspot.com/PartitionA_*.csv";
405-
* String gcsUrl2 = "gs://myapp.appspot.com/PartitionB_*.csv";
413+
* String gcsUrl1 = "gs://my_bucket/PartitionA_*.csv";
414+
* String gcsUrl2 = "gs://my_bucket/PartitionB_*.csv";
406415
* List<String> destinationUris = new ArrayList<>();
407416
* destinationUris.add(gcsUrl1);
408417
* destinationUris.add(gcsUrl2);
409-
*
410418
* Job job = table.extract(format, destinationUris);
411-
*
412-
* // Wait for the job to complete.
419+
* // Wait for the job to complete
413420
* try {
414421
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
415-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
422+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
416423
* if (completedJob != null && completedJob.status().error() == null) {
417-
* // Job completed successfully.
424+
* // Job completed successfully
418425
* } else {
419-
* // Handle error case.
426+
* // Handle error case
420427
* }
421428
* } catch (InterruptedException | TimeoutException e) {
422-
* // Handle interrupted wait.
429+
* // Handle interrupted wait
423430
* }
424431
* }</pre>
425432
*
@@ -442,20 +449,19 @@ public Job extract(String format, List<String> destinationUris, JobOption... opt
442449
*
443450
* <p>Example loading data from a single Google Cloud Storage file.
444451
* <pre> {@code
445-
* String sourceUri = "gs://myapp.appspot.com/filename.csv";
452+
* String sourceUri = "gs://my_bucket/filename.csv";
446453
* Job job = table.load(FormatOptions.csv(), sourceUri);
447-
*
448-
* // Wait for the job to complete.
454+
* // Wait for the job to complete
449455
* try {
450456
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
451-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
457+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
452458
* if (completedJob != null && completedJob.status().error() == null) {
453-
* // Job completed successfully.
459+
* // Job completed successfully
454460
* } else {
455-
* // Handle error case.
461+
* // Handle error case
456462
* }
457463
* } catch (InterruptedException | TimeoutException e) {
458-
* // Handle interrupted wait.
464+
* // Handle interrupted wait
459465
* }
460466
* }</pre>
461467
*
@@ -476,25 +482,23 @@ public Job load(FormatOptions format, String sourceUri, JobOption... options)
476482
*
477483
* <p>Example loading data from a list of Google Cloud Storage files.
478484
* <pre> {@code
479-
* String gcsUrl1 = "gs://myapp.appspot.com/PartitionA_000000000000.csv";
480-
* String gcsUrl2 = "gs://myapp.appspot.com/PartitionB_000000000000.csv";
485+
* String gcsUrl1 = "gs://my_bucket/filename1.csv";
486+
* String gcsUrl2 = "gs://my_bucket/filename2.csv";
481487
* List<String> sourceUris = new ArrayList<>();
482488
* sourceUris.add(gcsUrl1);
483489
* sourceUris.add(gcsUrl2);
484-
*
485490
* Job job = table.load(FormatOptions.csv(), sourceUris);
486-
*
487-
* // Wait for the job to complete.
491+
* // Wait for the job to complete
488492
* try {
489493
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
490-
* WaitForOption.timeout(60, TimeUnit.SECONDS));
494+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
491495
* if (completedJob != null && completedJob.status().error() == null) {
492-
* // Job completed successfully.
496+
* // Job completed successfully
493497
* } else {
494-
* // Handle error case.
498+
* // Handle error case
495499
* }
496500
* } catch (InterruptedException | TimeoutException e) {
497-
* // Handle interrupted wait.
501+
* // Handle interrupted wait
498502
* }
499503
* }</pre>
500504
*

0 commit comments

Comments
 (0)