Skip to content

Commit 6743dc0

Browse files
mziccardmziccard
authored
Merge pull request #1272 from mziccard/table-snippets
Add snippets to BigQuery Table class and tests
2 parents 4fe00dd + 2d1fc92 commit 6743dc0

File tree

3 files changed

+820
-1
lines changed
  • google-cloud-bigquery/src/main/java/com/google/cloud/bigquery
  • google-cloud-examples/src

3 files changed

+820
-1
lines changed

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

Lines changed: 203 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,16 @@ public Table build() {
139139
/**
140140
* Checks if this table exists.
141141
*
142+
* <p>Example of checking if the table exists.
143+
* <pre> {@code
144+
* boolean exists = table.exists();
145+
* if (exists) {
146+
* // the table exists
147+
* } else {
148+
* // the table was not found
149+
* }
150+
* }</pre>
151+
*
142152
* @return {@code true} if this table exists, {@code false} otherwise
143153
* @throws BigQueryException upon failure
144154
*/
@@ -149,6 +159,17 @@ public boolean exists() {
149159
/**
150160
* Fetches current table's latest information. Returns {@code null} if the table does not exist.
151161
*
162+
* <p>Example of fetching the table's latest information, specifying particular table fields to
163+
* get.
164+
* <pre> {@code
165+
* TableField field1 = TableField.LAST_MODIFIED_TIME;
166+
* TableField field2 = TableField.NUM_ROWS;
167+
* Table latestTable = table.reload(TableOption.fields(field1, field2));
168+
* if (latestTable == null) {
169+
* // the table was not found
170+
* }
171+
* }</pre>
172+
*
152173
* @param options table options
153174
* @return a {@code Table} object with latest information or {@code null} if not found
154175
* @throws BigQueryException upon failure
@@ -161,6 +182,11 @@ public Table reload(TableOption... options) {
161182
* Updates the table's information with this table's information. Dataset's and table's
162183
* user-defined ids cannot be changed. A new {@code Table} object is returned.
163184
*
185+
* <p>Example of updating the table's information.
186+
* <pre> {@code
187+
* Table updatedTable = table.toBuilder().description("new description").build().update();
188+
* }</pre>
189+
*
164190
* @param options dataset options
165191
* @return a {@code Table} object with updated information
166192
* @throws BigQueryException upon failure
@@ -172,6 +198,16 @@ public Table update(TableOption... options) {
172198
/**
173199
* Deletes this table.
174200
*
201+
* <p>Example of deleting the table.
202+
* <pre> {@code
203+
* boolean deleted = table.delete();
204+
* if (deleted) {
205+
* // the table was deleted
206+
* } else {
207+
* // the table was not found
208+
* }
209+
* }</pre>
210+
*
175211
* @return {@code true} if table was deleted, {@code false} if it was not found
176212
* @throws BigQueryException upon failure
177213
*/
@@ -182,6 +218,23 @@ public boolean delete() {
182218
/**
183219
* Insert rows into the table.
184220
*
221+
* <p>Example of inserting rows into the table.
222+
* <pre> {@code
223+
* String rowId1 = "rowId1";
224+
* String rowId2 = "rowId2";
225+
* List<RowToInsert> rows = new ArrayList<>();
226+
* Map<String, Object> row1 = new HashMap<>();
227+
* row1.put("stringField", "value1");
228+
* row1.put("booleanField", true);
229+
* Map<String, Object> row2 = new HashMap<>();
230+
* row2.put("stringField", "value2");
231+
* row2.put("booleanField", false);
232+
* rows.add(RowToInsert.of(rowId1, row1));
233+
* rows.add(RowToInsert.of(rowId2, row2));
234+
* InsertAllResponse response = table.insert(rows);
235+
* // do something with response
236+
* }</pre>
237+
*
185238
* @param rows rows to be inserted
186239
* @throws BigQueryException upon failure
187240
*/
@@ -193,6 +246,23 @@ public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows)
193246
/**
194247
* Insert rows into the table.
195248
*
249+
* <p>Example of inserting rows into the table, ignoring invalid rows.
250+
* <pre> {@code
251+
* String rowId1 = "rowId1";
252+
* String rowId2 = "rowId2";
253+
* List<RowToInsert> rows = new ArrayList<>();
254+
* Map<String, Object> row1 = new HashMap<>();
255+
* row1.put("stringField", 1);
256+
* row1.put("booleanField", true);
257+
* Map<String, Object> row2 = new HashMap<>();
258+
* row2.put("stringField", "value2");
259+
* row2.put("booleanField", false);
260+
* rows.add(RowToInsert.of(rowId1, row1));
261+
* rows.add(RowToInsert.of(rowId2, row2));
262+
* InsertAllResponse response = table.insert(rows, true, true);
263+
* // do something with response
264+
* }</pre>
265+
*
196266
* @param rows rows to be inserted
197267
* @param skipInvalidRows whether to insert all valid rows, even if invalid rows exist. If not set
198268
* the entire insert operation will fail if rows to be inserted contain an invalid row
@@ -202,7 +272,7 @@ public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows)
202272
* @throws BigQueryException upon failure
203273
*/
204274
public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows,
205-
boolean skipInvalidRows, boolean ignoreUnknownValues) throws BigQueryException {
275+
boolean skipInvalidRows, boolean ignoreUnknownValues) throws BigQueryException {
206276
InsertAllRequest request = InsertAllRequest.builder(tableId(), rows)
207277
.skipInvalidRows(skipInvalidRows)
208278
.ignoreUnknownValues(ignoreUnknownValues)
@@ -213,6 +283,16 @@ public InsertAllResponse insert(Iterable<InsertAllRequest.RowToInsert> rows,
213283
/**
214284
* Returns the paginated list rows in this table.
215285
*
286+
* <p>Example of listing rows in the table.
287+
* <pre> {@code
288+
* Page<List<FieldValue>> page = table.list(TableDataListOption.pageSize(100));
289+
* Iterator<List<FieldValue>> rowIterator = page.iterateAll();
290+
* while (rowIterator.hasNext()) {
291+
* List<FieldValue> row = rowIterator.next();
292+
* // do something with the row
293+
* }
294+
* }</pre>
295+
*
216296
* @param options table data list options
217297
* @throws BigQueryException upon failure
218298
*/
@@ -225,6 +305,25 @@ public Page<List<FieldValue>> list(TableDataListOption... options)
225305
* Starts a BigQuery Job to copy the current table to the provided destination table. Returns the
226306
* started {@link Job} object.
227307
*
308+
* <p>Example of copying the table to a destination table.
309+
* <pre> {@code
310+
* String datasetName = "my_dataset";
311+
* String tableName = "my_destination_table";
312+
* Job job = table.copy(datasetName, tableName);
313+
* // Wait for the job to complete.
314+
* try {
315+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
316+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
317+
* if (completedJob != null && completedJob.status().error() == null) {
318+
* // Job completed successfully
319+
* } else {
320+
* // Handle error case
321+
* }
322+
* } catch (InterruptedException | TimeoutException e) {
323+
* // Handle interrupted wait
324+
* }
325+
* }</pre>
326+
*
228327
* @param destinationDataset the user-defined id of the destination dataset
229328
* @param destinationTable the user-defined id of the destination table
230329
* @param options job options
@@ -239,6 +338,27 @@ public Job copy(String destinationDataset, String destinationTable, JobOption...
239338
* Starts a BigQuery Job to copy the current table to the provided destination table. Returns the
240339
* started {@link Job} object.
241340
*
341+
* <p>Example copying the table to a destination table.
342+
* <pre> {@code
343+
* String dataset = "my_dataset";
344+
* String tableName = "my_destination_table";
345+
* TableId destinationId = TableId.of(dataset, tableName);
346+
* JobOption options = JobOption.fields(JobField.STATUS, JobField.USER_EMAIL);
347+
* Job job = table.copy(destinationId, options);
348+
* // Wait for the job to complete.
349+
* try {
350+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
351+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
352+
* if (completedJob != null && completedJob.status().error() == null) {
353+
* // Job completed successfully.
354+
* } else {
355+
* // Handle error case.
356+
* }
357+
* } catch (InterruptedException | TimeoutException e) {
358+
* // Handle interrupted wait
359+
* }
360+
* }</pre>
361+
*
242362
* @param destinationTable the destination table of the copy job
243363
* @param options job options
244364
* @throws BigQueryException upon failure
@@ -253,6 +373,25 @@ public Job copy(TableId destinationTable, JobOption... options)
253373
* Starts a BigQuery Job to extract the current table to the provided destination URI. Returns the
254374
* started {@link Job} object.
255375
*
376+
* <p>Example extracting data to single Google Cloud Storage file.
377+
* <pre> {@code
378+
* String format = "CSV";
379+
* String gcsUrl = "gs://my_bucket/filename.csv";
380+
* Job job = table.extract(format, gcsUrl);
381+
* // Wait for the job to complete
382+
* try {
383+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
384+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
385+
* if (completedJob != null && completedJob.status().error() == null) {
386+
* // Job completed successfully
387+
* } else {
388+
* // Handle error case
389+
* }
390+
* } catch (InterruptedException | TimeoutException e) {
391+
* // Handle interrupted wait
392+
* }
393+
* }</pre>
394+
*
256395
* @param format the format of the extracted data
257396
* @param destinationUri the fully-qualified Google Cloud Storage URI (e.g. gs://bucket/path)
258397
* where the extracted table should be written
@@ -268,6 +407,29 @@ public Job extract(String format, String destinationUri, JobOption... options)
268407
* Starts a BigQuery Job to extract the current table to the provided destination URIs. Returns
269408
* the started {@link Job} object.
270409
*
410+
* <p>Example of partitioning data to a list of Google Cloud Storage files.
411+
* <pre> {@code
412+
* String format = "CSV";
413+
* String gcsUrl1 = "gs://my_bucket/PartitionA_*.csv";
414+
* String gcsUrl2 = "gs://my_bucket/PartitionB_*.csv";
415+
* List<String> destinationUris = new ArrayList<>();
416+
* destinationUris.add(gcsUrl1);
417+
* destinationUris.add(gcsUrl2);
418+
* Job job = table.extract(format, destinationUris);
419+
* // Wait for the job to complete
420+
* try {
421+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
422+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
423+
* if (completedJob != null && completedJob.status().error() == null) {
424+
* // Job completed successfully
425+
* } else {
426+
* // Handle error case
427+
* }
428+
* } catch (InterruptedException | TimeoutException e) {
429+
* // Handle interrupted wait
430+
* }
431+
* }</pre>
432+
*
271433
* @param format the format of the exported data
272434
* @param destinationUris the fully-qualified Google Cloud Storage URIs (e.g. gs://bucket/path)
273435
* where the extracted table should be written
@@ -285,6 +447,24 @@ public Job extract(String format, List<String> destinationUris, JobOption... opt
285447
* Starts a BigQuery Job to load data into the current table from the provided source URI. Returns
286448
* the started {@link Job} object.
287449
*
450+
* <p>Example loading data from a single Google Cloud Storage file.
451+
* <pre> {@code
452+
* String sourceUri = "gs://my_bucket/filename.csv";
453+
* Job job = table.load(FormatOptions.csv(), sourceUri);
454+
* // Wait for the job to complete
455+
* try {
456+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
457+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
458+
* if (completedJob != null && completedJob.status().error() == null) {
459+
* // Job completed successfully
460+
* } else {
461+
* // Handle error case
462+
* }
463+
* } catch (InterruptedException | TimeoutException e) {
464+
* // Handle interrupted wait
465+
* }
466+
* }</pre>
467+
*
288468
* @param format the format of the data to load
289469
* @param sourceUri the fully-qualified Google Cloud Storage URI (e.g. gs://bucket/path) from
290470
* which to load the data
@@ -300,6 +480,28 @@ public Job load(FormatOptions format, String sourceUri, JobOption... options)
300480
* Starts a BigQuery Job to load data into the current table from the provided source URIs.
301481
* Returns the started {@link Job} object.
302482
*
483+
* <p>Example loading data from a list of Google Cloud Storage files.
484+
* <pre> {@code
485+
* String gcsUrl1 = "gs://my_bucket/filename1.csv";
486+
* String gcsUrl2 = "gs://my_bucket/filename2.csv";
487+
* List<String> sourceUris = new ArrayList<>();
488+
* sourceUris.add(gcsUrl1);
489+
* sourceUris.add(gcsUrl2);
490+
* Job job = table.load(FormatOptions.csv(), sourceUris);
491+
* // Wait for the job to complete
492+
* try {
493+
* Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
494+
* WaitForOption.timeout(3, TimeUnit.MINUTES));
495+
* if (completedJob != null && completedJob.status().error() == null) {
496+
* // Job completed successfully
497+
* } else {
498+
* // Handle error case
499+
* }
500+
* } catch (InterruptedException | TimeoutException e) {
501+
* // Handle interrupted wait
502+
* }
503+
* }</pre>
504+
*
303505
* @param format the format of the exported data
304506
* @param sourceUris the fully-qualified Google Cloud Storage URIs (e.g. gs://bucket/path) from
305507
* which to load the data

0 commit comments

Comments
 (0)