resultType,
/**
* Returns a new {@link StructuredQuery} builder for full (complete entities) queries.
+ *
+ * Example of creating and running an entity query.
+ *
{@code
+ * String kind = "my_kind";
+ * Query query = Query.entityQueryBuilder().kind(kind).build();
+ * QueryResults results = datastore.run(query);
+ * // Use results
+ * }
+ *
*/
public static EntityQuery.Builder entityQueryBuilder() {
return new EntityQuery.Builder();
@@ -206,6 +233,15 @@ public static EntityQuery.Builder entityQueryBuilder() {
/**
* Returns a new {@link StructuredQuery} builder for key only queries.
+ *
+ * Example of creating and running a key query.
+ *
{@code
+ * String kind = "my_kind";
+ * Query query = Query.keyQueryBuilder().kind(kind).build();
+ * QueryResults results = datastore.run(query);
+ * // Use results
+ * }
+ *
*/
public static KeyQuery.Builder keyQueryBuilder() {
return new KeyQuery.Builder();
@@ -213,6 +249,19 @@ public static KeyQuery.Builder keyQueryBuilder() {
/**
* Returns a new {@link StructuredQuery} builder for projection queries.
+ *
+ * Example of creating and running a projection entity query.
+ *
{@code
+ * String kind = "my_kind";
+ * String property = "my_property";
+ * Query query = Query.projectionEntityQueryBuilder()
+ * .kind(kind)
+ * .addProjection(property)
+ * .build();
+ * QueryResults results = datastore.run(query);
+ * // Use results
+ * }
+ *
*/
public static ProjectionEntityQuery.Builder projectionEntityQueryBuilder() {
return new ProjectionEntityQuery.Builder();
diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java
new file mode 100644
index 000000000000..b35437cbac9f
--- /dev/null
+++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java
@@ -0,0 +1,118 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Query's javadoc. Any change to this file should be reflected in
+ * Query's javadoc.
+ */
+
+package com.google.cloud.examples.datastore.snippets;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.ProjectionEntity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+
+/**
+ * This class contains a number of snippets for the {@link Query} class.
+ */
+public class QuerySnippets {
+
+ private final Datastore datastore;
+
+ public QuerySnippets(Datastore datastore) {
+ this.datastore = datastore;
+ }
+
+ /**
+ * Example of creating and running a GQL query.
+ */
+ // [TARGET gqlQueryBuilder(String)]
+ // [VARIABLE "my_kind"]
+ public QueryResults newQuery(String kind) {
+ // [START newQuery]
+ String gqlQuery = "select * from " + kind;
+ Query query = Query.gqlQueryBuilder(gqlQuery).build();
+ QueryResults results = datastore.run(query);
+ // Use results
+ // [END newQuery]
+ return results;
+ }
+
+ /**
+ * Example of creating and running a typed GQL query.
+ */
+ // [TARGET gqlQueryBuilder(ResultType, String)]
+ // [VARIABLE "my_kind"]
+ public QueryResults newTypedQuery(String kind) {
+ // [START newTypedQuery]
+ String gqlQuery = "select * from " + kind;
+ Query query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
+ QueryResults results = datastore.run(query);
+ // Use results
+ // [END newTypedQuery]
+ return results;
+ }
+
+ /**
+ * Example of creating and running an entity query.
+ */
+ // [TARGET entityQueryBuilder()]
+ // [VARIABLE "my_kind"]
+ public QueryResults newEntityQuery(String kind) {
+ // [START newEntityQuery]
+ Query query = Query.entityQueryBuilder().kind(kind).build();
+ QueryResults results = datastore.run(query);
+ // Use results
+ // [END newEntityQuery]
+ return results;
+ }
+
+ /**
+ * Example of creating and running a key query.
+ */
+ // [TARGET keyQueryBuilder()]
+ // [VARIABLE "my_kind"]
+ public QueryResults newKeyQuery(String kind) {
+ // [START newKeyQuery]
+ Query query = Query.keyQueryBuilder().kind(kind).build();
+ QueryResults results = datastore.run(query);
+ // Use results
+ // [END newKeyQuery]
+ return results;
+ }
+
+ /**
+ * Example of creating and running a projection entity query.
+ */
+ // [TARGET projectionEntityQueryBuilder()]
+ // [VARIABLE "my_kind"]
+ // [VARIABLE "my_property"]
+ public QueryResults newProjectionEntityQuery(String kind, String property) {
+ // [START newProjectionEntityQuery]
+ Query query = Query.projectionEntityQueryBuilder()
+ .kind(kind)
+ .addProjection(property)
+ .build();
+ QueryResults results = datastore.run(query);
+ // Use results
+ // [END newProjectionEntityQuery]
+ return results;
+ }
+}
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java
new file mode 100644
index 000000000000..d735c12c1f75
--- /dev/null
+++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.examples.datastore.snippets;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.ProjectionEntity;
+import com.google.cloud.datastore.QueryResults;
+import com.google.common.base.Function;
+import com.google.common.collect.Iterators;
+import com.google.common.collect.Sets;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.Timeout;
+
+import java.util.Set;
+import java.util.UUID;
+
+public class ITQuerySnippets {
+
+ private static Datastore datastore;
+ private static Entity entity1;
+ private static Entity entity2;
+ private static final String KIND = "kind_" + UUID.randomUUID().toString().replace("-", "");
+ private static final Function ENTITY_TO_DESCRIPTION_FUNCTION =
+ new Function() {
+ @Override
+ public String apply(ProjectionEntity entity) {
+ return entity.getString("description");
+ }
+ };
+
+ @Rule
+ public Timeout globalTimeout = Timeout.seconds(60);
+
+ @BeforeClass
+ public static void beforeClass() {
+ datastore = DatastoreOptions.defaultInstance().service();
+ Key key1 = Key.builder(datastore.options().projectId(), KIND, "key1").build();
+ Key key2 = Key.builder(datastore.options().projectId(), KIND, "key2").build();
+ entity1 = Entity.builder(key1).set("description", "entity1").build();
+ entity2 = Entity.builder(key2).set("description", "entity2").build();
+ datastore.put(entity1, entity2);
+ }
+
+ @AfterClass
+ public static void afterClass() {
+ datastore.delete(entity1.key(), entity2.key());
+ }
+
+ @Test
+ public void testNewQuery() throws InterruptedException {
+ QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+ QueryResults results = transactionSnippets.newQuery(KIND);
+ Set resultSet = Sets.newHashSet(results);
+ while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+ Thread.sleep(500);
+ resultSet = Sets.newHashSet(results);
+ }
+ }
+
+ @Test
+ public void testNewTypedQuery() throws InterruptedException {
+ QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+ QueryResults results = transactionSnippets.newTypedQuery(KIND);
+ Set resultSet = Sets.newHashSet(results);
+ while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+ Thread.sleep(500);
+ resultSet = Sets.newHashSet(results);
+ }
+ }
+
+ @Test
+ public void testNewEntityQuery() throws InterruptedException {
+ QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+ QueryResults results = transactionSnippets.newEntityQuery(KIND);
+ Set resultSet = Sets.newHashSet(results);
+ while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+ Thread.sleep(500);
+ resultSet = Sets.newHashSet(results);
+ }
+ }
+
+ @Test
+ public void testNewKeyQuery() throws InterruptedException {
+ QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+ QueryResults results = transactionSnippets.newKeyQuery(KIND);
+ Set resultSet = Sets.newHashSet(results);
+ while (!resultSet.contains(entity1.key()) || !resultSet.contains(entity2.key())) {
+ Thread.sleep(500);
+ resultSet = Sets.newHashSet(results);
+ }
+ }
+
+ @Test
+ public void testNewProjectionEntityQuery() throws InterruptedException {
+ QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+ QueryResults results =
+ transactionSnippets.newProjectionEntityQuery(KIND, "description");
+ Set resultSet =
+ Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
+ while (!resultSet.contains(entity1.getString("description"))
+ || !resultSet.contains(entity2.getString("description"))) {
+ Thread.sleep(500);
+ resultSet = Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
+ }
+ }
+}