Skip to content

Commit 1f12a83

Browse files
nithinsujirpongad
nithinsujir
authored and
pongad
committed
spanner: Add snippets for Spanner, BatchClient and BatchReadOnlyTransaction (#3611)
1 parent 997d2a3 commit 1f12a83

File tree

5 files changed

+379
-0
lines changed

5 files changed

+379
-0
lines changed

‎google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/BatchClient.java

+13
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ public interface BatchClient {
3838
* {@link BatchReadOnlyTransaction}.
3939
*
4040
* @param bound the timestamp bound at which to perform the read
41+
*
42+
* <!--SNIPPET batch_client_strong_read-->
43+
* <pre>{@code
44+
* BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(TimestampBound.strong());
45+
* }</pre>
46+
* <!--SNIPPET batch_client_strong_read-->
4147
*/
4248
BatchReadOnlyTransaction batchReadOnlyTransaction(TimestampBound bound);
4349

@@ -52,6 +58,13 @@ public interface BatchClient {
5258
*
5359
* @param batchTransactionId to re-initialize the transaction, re-using the timestamp for
5460
* successive read/query.
61+
*
62+
* <!--SNIPPET batch_client_read_with_id-->
63+
* <pre>{@code
64+
* BatchTransactionId txnId = my_txn.getBatchTransactionId();
65+
* BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
66+
* }</pre>
67+
* <!--SNIPPET batch_client_read_with_id-->
5568
*/
5669
BatchReadOnlyTransaction batchReadOnlyTransaction(BatchTransactionId batchTransactionId);
5770
}

‎google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/BatchReadOnlyTransaction.java

+96
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,29 @@ public interface BatchReadOnlyTransaction extends ReadOnlyTransaction {
5454
* @param columns the columns to read
5555
* @param options the options to configure the read, supported values are
5656
* {@link Options#prefetchChunks()}
57+
*
58+
* <!--SNIPPET partition_read-->
59+
* <pre>{@code
60+
* final BatchReadOnlyTransaction txn =
61+
* batchClient.batchReadOnlyTransaction(TimestampBound.strong());
62+
* List<Partition> partitions =
63+
* txn.partitionRead(
64+
* PartitionOptions.getDefaultInstance(),
65+
* "Singers",
66+
* KeySet.all(),
67+
* Arrays.asList("SingerId", "FirstName", "LastName"));
68+
* for (final Partition p : partitions) {
69+
* try (ResultSet results = txn.execute(p)) {
70+
* while (results.next()) {
71+
* long singerId = results.getLong(0);
72+
* String firstName = results.getString(1);
73+
* String lastName = results.getString(2);
74+
* System.out.println("P2 [" + singerId + "] " + firstName + " " + lastName);
75+
* }
76+
* }
77+
* }
78+
* }</pre>
79+
* <!--SNIPPET partition_read-->
5780
*/
5881
List<Partition> partitionRead(
5982
PartitionOptions partitionOptions,
@@ -76,6 +99,30 @@ List<Partition> partitionRead(
7699
* rows are returned in the natural key order of the index.
77100
* @param columns the columns to read
78101
* @param options the options to configure the read
102+
*
103+
* <!--SNIPPET partition_read_using_index-->
104+
* <pre>{@code
105+
* final BatchReadOnlyTransaction txn =
106+
* batchClient.batchReadOnlyTransaction(TimestampBound.strong());
107+
* List<Partition> partitions =
108+
* txn.partitionReadUsingIndex(
109+
* PartitionOptions.getDefaultInstance(),
110+
* "Singers",
111+
* "SingerId",
112+
* KeySet.all(),
113+
* Arrays.asList("FirstName"));
114+
* BatchTransactionId txnID = txn.getBatchTransactionId();
115+
* int numRowsRead = 0;
116+
* for (Partition p : partitions) {
117+
* BatchReadOnlyTransaction batchTxnOnEachWorker = batchClient.batchReadOnlyTransaction(txnID);
118+
* try (ResultSet results = batchTxnOnEachWorker.execute(p)) {
119+
* while (results.next()) {
120+
* System.out.println(results.getString(0));
121+
* }
122+
* }
123+
* }
124+
* }</pre>
125+
* <!--SNIPPET partition_read_using_index-->
79126
*/
80127
List<Partition> partitionReadUsingIndex(
81128
PartitionOptions partitionOptions,
@@ -95,6 +142,26 @@ List<Partition> partitionReadUsingIndex(
95142
* @param partitionOptions configuration for size and count of partitions returned
96143
* @param statement the query statement to execute
97144
* @param options the options to configure the query
145+
*
146+
* <!--SNIPPET partition_query-->
147+
* <pre>{@code
148+
* final BatchReadOnlyTransaction txn =
149+
* batchClient.batchReadOnlyTransaction(TimestampBound.strong());
150+
* List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
151+
* Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
152+
*
153+
* for (final Partition p : partitions) {
154+
* try (ResultSet results = txn.execute(p)) {
155+
* while (results.next()) {
156+
* long singerId = results.getLong(0);
157+
* String firstName = results.getString(1);
158+
* String lastName = results.getString(2);
159+
* System.out.println("[" + singerId + "] " + firstName + " " + lastName);
160+
* }
161+
* }
162+
* }
163+
* }</pre>
164+
* <!--SNIPPET partition_query-->
98165
*/
99166
List<Partition> partitionQuery(
100167
PartitionOptions partitionOptions, Statement statement, QueryOption... options)
@@ -103,12 +170,41 @@ List<Partition> partitionQuery(
103170
/**
104171
* Execute the partition to return {@link ResultSet}. The result returned could be zero or more
105172
* rows. The row metadata may be absent if no rows are returned.
173+
*
174+
* <!--SNIPPET partition_query-->
175+
* <pre>{@code
176+
* final BatchReadOnlyTransaction txn =
177+
* batchClient.batchReadOnlyTransaction(TimestampBound.strong());
178+
* List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
179+
* Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
180+
*
181+
* for (final Partition p : partitions) {
182+
* try (ResultSet results = txn.execute(p)) {
183+
* while (results.next()) {
184+
* long singerId = results.getLong(0);
185+
* String firstName = results.getString(1);
186+
* String lastName = results.getString(2);
187+
* System.out.println("[" + singerId + "] " + firstName + " " + lastName);
188+
* }
189+
* }
190+
* }
191+
* }</pre>
192+
* <!--SNIPPET partition_query-->
193+
*
106194
*/
107195
ResultSet execute(Partition partition) throws SpannerException;
108196

109197
/**
110198
* Returns a {@link BatchTransactionId} to be re-used across several machines/processes. This
111199
* BatchTransactionId guarantees the subsequent read/query to be executed at the same timestamp.
200+
*
201+
* <!--SNIPPET batch_client_read_with_id-->
202+
* <pre>{@code
203+
* BatchTransactionId txnId = my_txn.getBatchTransactionId();
204+
* BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
205+
* }</pre>
206+
* <!--SNIPPET batch_client_read_with_id-->
207+
*
112208
*/
113209
BatchTransactionId getBatchTransactionId();
114210
}

‎google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/Spanner.java

+44
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,45 @@
2626
*/
2727
public interface Spanner extends Service<SpannerOptions> {
2828
/** Returns a {@code DatabaseAdminClient} to do admin operations on Cloud Spanner databases. */
29+
/*
30+
* <!--SNIPPET get_dbadmin_client-->
31+
* <pre>{@code
32+
* SpannerOptions options = SpannerOptions.newBuilder().build();
33+
* Spanner spanner = options.getService();
34+
* DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();
35+
* }</pre>
36+
* <!--SNIPPET get_dbadmin_client-->
37+
*/
2938
DatabaseAdminClient getDatabaseAdminClient();
3039

3140
/** Returns an {@code InstanceAdminClient} to do admin operations on Cloud Spanner instances. */
41+
/*
42+
* <!--SNIPPET get_instance_admin_client-->
43+
* <pre>{@code
44+
* SpannerOptions options = SpannerOptions.newBuilder().build();
45+
* Spanner spanner = options.getService();
46+
* InstanceAdminClient instanceAdminClient = spanner.getInstanceAdminClient();
47+
* }</pre>
48+
* <!--SNIPPET get_instance_admin_client-->
49+
*/
3250
InstanceAdminClient getInstanceAdminClient();
3351

3452
/**
3553
* Returns a {@code DatabaseClient} for the given database. It uses a pool of sessions to talk to
3654
* the database.
55+
*
56+
* <!--SNIPPET get_db_client-->
57+
* <pre>{@code
58+
* SpannerOptions options = SpannerOptions.newBuilder().build();
59+
* Spanner spanner = options.getService();
60+
* final String project = "test-project";
61+
* final String instance = "test-instance";
62+
* final String database = "example-db";
63+
* DatabaseId db =
64+
* DatabaseId.of("span-cloud-testing", "nsujir-ins", "example-db");
65+
* DatabaseClient dbClient = spanner.getDatabaseClient(db);
66+
* }</pre>
67+
* <!--SNIPPET get_db_client-->
3768
*/
3869
DatabaseClient getDatabaseClient(DatabaseId db);
3970

@@ -45,6 +76,19 @@ public interface Spanner extends Service<SpannerOptions> {
4576
* yet at the same snapshot.
4677
*
4778
* <p> For all other use cases, {@code DatabaseClient} is more appropriate and performant.
79+
*
80+
* <!--SNIPPET get_batch_client-->
81+
* <pre>{@code
82+
* SpannerOptions options = SpannerOptions.newBuilder().build();
83+
* Spanner spanner = options.getService();
84+
* final String project = "test-project";
85+
* final String instance = "test-instance";
86+
* final String database = "example-db";
87+
* DatabaseId db =
88+
* DatabaseId.of("span-cloud-testing", "nsujir-ins", "example-db");
89+
* BatchClient batchClient = spanner.getBatchClient(db);
90+
* }</pre>
91+
* <!--SNIPPET get_batch_client-->
4892
*/
4993
BatchClient getBatchClient(DatabaseId db);
5094

‎google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/BatchClientSnippets.java

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/*
2+
* Copyright 2018 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/*
18+
* EDITING INSTRUCTIONS
19+
* This file is referenced in spanner/BatchClient's javadoc. Any change
20+
* to this file should be reflected in spanner/BatchClient's javadoc.
21+
*/
22+
23+
package com.google.cloud.examples.spanner.snippets;
24+
25+
import com.google.cloud.spanner.BatchClient;
26+
import com.google.cloud.spanner.BatchReadOnlyTransaction;
27+
import com.google.cloud.spanner.BatchTransactionId;
28+
import com.google.cloud.spanner.KeySet;
29+
import com.google.cloud.spanner.Partition;
30+
import com.google.cloud.spanner.PartitionOptions;
31+
import com.google.cloud.spanner.ResultSet;
32+
import com.google.cloud.spanner.Statement;
33+
import com.google.cloud.spanner.TimestampBound;
34+
import java.util.Arrays;
35+
import java.util.List;
36+
37+
/**
38+
* This class contains snippets for {@link com.google.cloud.spanner.BatchClient} interface.
39+
*/
40+
public class BatchClientSnippets {
41+
42+
private final BatchClient batchClient;
43+
44+
public BatchClientSnippets(BatchClient batchClient) {
45+
this.batchClient = batchClient;
46+
}
47+
48+
/**
49+
* Example to do a batch strong read.
50+
*/
51+
BatchReadOnlyTransaction readStrong() {
52+
// [START batch_client_strong_read]
53+
BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(TimestampBound.strong());
54+
// [END batch_client_strong_read]
55+
return txn;
56+
}
57+
58+
/**
59+
* Example to do a batch read with txn id.
60+
*/
61+
BatchReadOnlyTransaction readWithId(BatchReadOnlyTransaction my_txn) {
62+
// [START batch_client_read_with_id]
63+
BatchTransactionId txnId = my_txn.getBatchTransactionId();
64+
BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
65+
// [END batch_client_read_with_id]
66+
67+
return txn;
68+
}
69+
70+
void partitionQuery() {
71+
// [START partition_query]
72+
final BatchReadOnlyTransaction txn =
73+
batchClient.batchReadOnlyTransaction(TimestampBound.strong());
74+
List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
75+
Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
76+
77+
for (final Partition p : partitions) {
78+
try (ResultSet results = txn.execute(p)) {
79+
while (results.next()) {
80+
long singerId = results.getLong(0);
81+
String firstName = results.getString(1);
82+
String lastName = results.getString(2);
83+
System.out.println("[" + singerId + "] " + firstName + " " + lastName);
84+
}
85+
}
86+
}
87+
// [END partition_query]
88+
89+
}
90+
91+
void partitionRead() {
92+
// [START partition_read]
93+
final BatchReadOnlyTransaction txn =
94+
batchClient.batchReadOnlyTransaction(TimestampBound.strong());
95+
List<Partition> partitions =
96+
txn.partitionRead(
97+
PartitionOptions.getDefaultInstance(),
98+
"Singers",
99+
KeySet.all(),
100+
Arrays.asList("SingerId", "FirstName", "LastName"));
101+
for (final Partition p : partitions) {
102+
try (ResultSet results = txn.execute(p)) {
103+
while (results.next()) {
104+
long singerId = results.getLong(0);
105+
String firstName = results.getString(1);
106+
String lastName = results.getString(2);
107+
System.out.println("P2 [" + singerId + "] " + firstName + " " + lastName);
108+
}
109+
}
110+
}
111+
// [END partition_read]
112+
}
113+
114+
void partitionReadUsingIndex() {
115+
// [START partition_read_using_index]
116+
final BatchReadOnlyTransaction txn =
117+
batchClient.batchReadOnlyTransaction(TimestampBound.strong());
118+
List<Partition> partitions =
119+
txn.partitionReadUsingIndex(
120+
PartitionOptions.getDefaultInstance(),
121+
"Singers",
122+
"SingerId",
123+
KeySet.all(),
124+
Arrays.asList("FirstName"));
125+
BatchTransactionId txnID = txn.getBatchTransactionId();
126+
int numRowsRead = 0;
127+
for (Partition p : partitions) {
128+
BatchReadOnlyTransaction batchTxnOnEachWorker = batchClient.batchReadOnlyTransaction(txnID);
129+
try (ResultSet results = batchTxnOnEachWorker.execute(p)) {
130+
while (results.next()) {
131+
System.out.println(results.getString(0));
132+
}
133+
}
134+
}
135+
// [END partition_read_using_index]
136+
}
137+
}
138+

0 commit comments

Comments
 (0)