Skip to content

Commit 13b1b0e

Browse files
mziccardmziccard
committed
Minor fixes to QueryStage
- Add javadoc to QueryStep - Rename QueryStep.kind to name - Make QueryStep.substeps an empty list if not set - Document that QueryStatistics.queryPlan can return null - Add check for query plan in ITBigQueryTest.testQueryJob - Add unit tests for QueryStep - Better javadoc for QueryPlan getters
1 parent 4aa8a97 commit 13b1b0e

4 files changed

Lines changed: 52 additions & 32 deletions

File tree

‎gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/JobStatistics.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -339,10 +339,10 @@ public Long totalBytesProcessed() {
339339
}
340340

341341
/**
342-
* Returns the query plan as a list of stages. Each stage involves a number of steps that read
343-
* from data sources, perform a series of transformations on the input, and emit an output to a
344-
* future stage (or the final result). The query plan is available for a completed query job and
345-
* is retained for 7 days.
342+
* Returns the query plan as a list of stages or {@code null} if a query plan is not available.
343+
* Each stage involves a number of steps that read from data sources, perform a series of
344+
* transformations on the input, and emit an output to a future stage (or the final result). The
345+
* query plan is available for a completed query job and is retained for 7 days.
346346
*
347347
* @see <a href="https://cloud.google.com/bigquery/query-plan-explanation">Query Plan</a>
348348
*/

‎gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/QueryStage.java‎

Lines changed: 38 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -78,33 +78,42 @@ public ExplainQueryStep apply(QueryStep stage) {
7878
};
7979
private static final long serialVersionUID = 8663444604771794411L;
8080

81-
private final String kind;
81+
private final String name;
8282
private final List<String> substeps;
8383

84-
QueryStep(String kind, List<String> substeps) {
85-
this.kind = kind;
84+
QueryStep(String name, List<String> substeps) {
85+
this.name = name;
8686
this.substeps = substeps;
8787
}
8888

89-
public String kind() {
90-
return kind;
89+
/**
90+
* Returns a machine-readable name for the operation.
91+
*
92+
* @see <a href="https://cloud.google.com/bigquery/query-plan-explanation#steps_metadata">Steps
93+
* Metadata</a>
94+
*/
95+
public String name() {
96+
return name;
9197
}
9298

99+
/**
100+
* Returns a list of human-readable stage descriptions.
101+
*/
93102
public List<String> substeps() {
94103
return substeps;
95104
}
96105

97106
@Override
98107
public String toString() {
99108
return MoreObjects.toStringHelper(this)
100-
.add("kind", kind)
109+
.add("name", name)
101110
.add("substeps", substeps)
102111
.toString();
103112
}
104113

105114
@Override
106115
public int hashCode() {
107-
return Objects.hash(kind, substeps);
116+
return Objects.hash(name, substeps);
108117
}
109118

110119
@Override
@@ -113,20 +122,16 @@ public boolean equals(Object obj) {
113122
return false;
114123
}
115124
QueryStep other = (QueryStep) obj;
116-
return Objects.equals(kind, other.kind)
117-
&& Objects.equals(substeps, other.substeps);
125+
return Objects.equals(name, other.name) && Objects.equals(substeps, other.substeps);
118126
}
119127

120128
ExplainQueryStep toPb() {
121-
return new ExplainQueryStep().setKind(kind).setSubsteps(substeps);
129+
return new ExplainQueryStep().setKind(name).setSubsteps(substeps);
122130
}
123131

124132
static QueryStep fromPb(com.google.api.services.bigquery.model.ExplainQueryStep stepPb) {
125-
List<String> substeps = null;
126-
if (stepPb.getSubsteps() != null) {
127-
substeps = ImmutableList.copyOf(stepPb.getSubsteps());
128-
}
129-
return new QueryStep(stepPb.getKind(), substeps);
133+
return new QueryStep(stepPb.getKind(), ImmutableList.copyOf(stepPb.getSubsteps() != null
134+
? stepPb.getSubsteps() : ImmutableList.<String>of()));
130135
}
131136
}
132137

@@ -249,14 +254,16 @@ QueryStage build() {
249254
}
250255

251256
/**
252-
* Returns the relative amount of time the average shard spent on CPU-bound tasks.
257+
* Returns the time the average worker spent CPU-bound, divided by the longest time spent by any
258+
* worker in any segment.
253259
*/
254260
public double computeRatioAvg() {
255261
return computeRatioAvg;
256262
}
257263

258264
/**
259-
* Returns the relative amount of time the slowest shard spent on CPU-bound tasks.
265+
* Returns the time the slowest worker spent CPU-bound, divided by the longest time spent by any
266+
* worker in any segment.
260267
*/
261268
public double computeRatioMax() {
262269
return computeRatioMax;
@@ -277,28 +284,30 @@ public String name() {
277284
}
278285

279286
/**
280-
* Returns the relative amount of time the average shard spent reading input.
287+
* Returns the time the average worker spent reading input data, divided by the longest time spent
288+
* by any worker in any segment.
281289
*/
282290
public double readRatioAvg() {
283291
return readRatioAvg;
284292
}
285293

286294
/**
287-
* Returns the relative amount of time the slowest shard spent reading input.
295+
* Returns the time the slowest worker spent reading input data, divided by the longest time spent
296+
* by any worker in any segment.
288297
*/
289298
public double readRatioMax() {
290299
return readRatioMax;
291300
}
292301

293302
/**
294-
* Returns the number of records read into the stage.
303+
* Returns the number of rows (top-level records) read by the stage.
295304
*/
296305
public long recordsRead() {
297306
return recordsRead;
298307
}
299308

300309
/**
301-
* Returns the number of records written by the stage.
310+
* Returns the number of rows (top-level records) written by the stage.
302311
*/
303312
public long recordsWritten() {
304313
return recordsWritten;
@@ -312,28 +321,32 @@ public List<QueryStep> steps() {
312321
}
313322

314323
/**
315-
* Returns the relative amount of time the average shard spent waiting to be scheduled.
324+
* Returns the time the average worker spent waiting to be scheduled, divided by the longest time
325+
* spent by any worker in any segment.
316326
*/
317327
public double waitRatioAvg() {
318328
return waitRatioAvg;
319329
}
320330

321331
/**
322-
* Returns the relative amount of time the slowest shard spent waiting to be scheduled.
332+
* Returns the time the slowest worker spent waiting to be scheduled, divided by the longest time
333+
* spent by any worker in any segment.
323334
*/
324335
public double waitRatioMax() {
325336
return waitRatioMax;
326337
}
327338

328339
/**
329-
* Returns the relative amount of time the average shard spent on writing output.
340+
* Returns the time the average worker spent writing output data, divided by the longest time
341+
* spent by any worker in any segment.
330342
*/
331343
public double writeRatioAvg() {
332344
return writeRatioAvg;
333345
}
334346

335347
/**
336-
* Returns the relative amount of time the slowest shard spent on writing output.
348+
* Returns the time the slowest worker spent writing output data, divided by the longest time
349+
* spent by any worker in any segment.
337350
*/
338351
public double writeRatioMax() {
339352
return writeRatioMax;

‎gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -771,6 +771,8 @@ public void testQueryJob() throws InterruptedException {
771771
}
772772
assertEquals(2, rowCount);
773773
assertTrue(bigquery.delete(DATASET, tableName));
774+
QueryJobInfo queryJob = bigquery.getJob(remoteJob.jobId());
775+
assertNotNull(queryJob.statistics().queryPlan());
774776
}
775777

776778
@Test

‎gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/QueryStageTest.java‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818

1919
import static org.junit.Assert.assertEquals;
2020

21+
import com.google.api.services.bigquery.model.ExplainQueryStep;
2122
import com.google.common.collect.ImmutableList;
2223
import com.google.gcloud.bigquery.QueryStage.QueryStep;
2324

@@ -62,8 +63,8 @@ public class QueryStageTest {
6263

6364
@Test
6465
public void testQueryStepConstructor() {
65-
assertEquals("KIND", QUERY_STEP1.kind());
66-
assertEquals("KIND", QUERY_STEP2.kind());
66+
assertEquals("KIND", QUERY_STEP1.name());
67+
assertEquals("KIND", QUERY_STEP2.name());
6768
assertEquals(SUBSTEPS1, QUERY_STEP1.substeps());
6869
assertEquals(SUBSTEPS2, QUERY_STEP2.substeps());
6970
}
@@ -90,6 +91,10 @@ public void testToAndFromPb() {
9091
compareQueryStep(QUERY_STEP1, QueryStep.fromPb(QUERY_STEP1.toPb()));
9192
compareQueryStep(QUERY_STEP2, QueryStep.fromPb(QUERY_STEP2.toPb()));
9293
compareQueryStage(QUERY_STAGE, QueryStage.fromPb(QUERY_STAGE.toPb()));
94+
ExplainQueryStep stepPb = new ExplainQueryStep();
95+
stepPb.setKind("KIND");
96+
stepPb.setSubsteps(null);
97+
compareQueryStep(new QueryStep("KIND", ImmutableList.<String>of()), QueryStep.fromPb(stepPb));
9398
}
9499

95100
@Test
@@ -119,7 +124,7 @@ private void compareQueryStage(QueryStage expected, QueryStage value) {
119124

120125
private void compareQueryStep(QueryStep expected, QueryStep value) {
121126
assertEquals(expected, value);
122-
assertEquals(expected.kind(), value.kind());
127+
assertEquals(expected.name(), value.name());
123128
assertEquals(expected.substeps(), value.substeps());
124129
assertEquals(expected.hashCode(), value.hashCode());
125130
}

0 commit comments

Comments
 (0)