Skip to content

Commit b48d163

Browse files
aozarovaozarov
committed
Merge pull request #399 from ajkannan/fix-docs
Add step-by-step datastore guide
2 parents bbf3cb6 + 424f144 commit b48d163

File tree

1 file changed

+122
-19
lines changed

1 file changed

+122
-19
lines changed

‎gcloud-java-datastore/README.md

+122-19
Original file line numberDiff line numberDiff line change
@@ -56,33 +56,136 @@ Cloud Datastore for your project.
5656
See the ``gcloud-java`` API [datastore documentation][datastore-api] to learn how to interact
5757
with the Cloud Datastore using this Client Library.
5858

59-
Here is a code snippet showing a simple usage example from within Compute/App Engine. Note that you must [supply credentials](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) and a project ID if running this snippet elsewhere.
59+
Getting Started
60+
---------------
61+
#### Prerequisites
62+
For this tutorial, you will need a [Google Developers Console](https://console.developers.google.com/) project with the Datastore API enabled. [Follow these instructions](https://cloud.google.com/docs/authentication#preparation) to get your project set up. You will also need to set up the local development environment by [installing the Google Cloud SDK](https://cloud.google.com/sdk/) and running the following commands in command line: `gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`.
63+
64+
#### Installation and setup
65+
You'll need to obtain the `gcloud-java-datastore` library. See the [Quickstart](#quickstart) section to add `gcloud-java-datastore` as a dependency in your code.
66+
67+
#### Creating an authorized service object
68+
To make authenticated requests to Google Cloud Datastore, you must create a service object with credentials. You can then make API calls by calling methods on the Datastore service object. The simplest way to authenticate is to use [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). These credentials are automatically inferred from your environment, so you only need the following code to create your service object:
6069

6170
```java
6271
import com.google.gcloud.datastore.Datastore;
6372
import com.google.gcloud.datastore.DatastoreOptions;
64-
import com.google.gcloud.datastore.DateTime;
73+
74+
Datastore datastore = DatastoreOptions.defaultInstance().service();
75+
```
76+
77+
For other authentication options, see the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) page.
78+
79+
#### Storing data
80+
Objects in Datastore are known as entities. Entities are grouped by "kind" and have keys for easy access. In this code snippet, we will create a new entity representing a person and store that data by the person's name. First, add the following imports at the top of your file:
81+
82+
```java
6583
import com.google.gcloud.datastore.Entity;
6684
import com.google.gcloud.datastore.Key;
6785
import com.google.gcloud.datastore.KeyFactory;
86+
```
6887

69-
Datastore datastore = DatastoreOptions.defaultInstance().service();
70-
KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
71-
Key key = keyFactory.newKey(keyName);
72-
Entity entity = datastore.get(key);
73-
if (entity == null) {
74-
entity = Entity.builder(key)
75-
.set("name", "John Do")
76-
.set("age", 30)
77-
.set("access_time", DateTime.now())
78-
.build();
79-
datastore.put(entity);
80-
} else {
81-
System.out.println("Updating access_time for " + entity.getString("name"));
82-
entity = Entity.builder(entity)
83-
.set("access_time", DateTime.now())
84-
.build();
85-
datastore.update(entity);
88+
Then add the following code to put an entity in Datastore.
89+
90+
```java
91+
KeyFactory keyFactory = datastore.newKeyFactory().kind("Person");
92+
Key key = keyFactory.newKey("John Doe");
93+
Entity entity = Entity.builder(key)
94+
.set("age", 51)
95+
.set("favorite_food", "pizza")
96+
.build();
97+
datastore.put(entity);
98+
```
99+
100+
Later, if you want to get this entity back, add the following to your code:
101+
102+
```java
103+
Entity johnEntity = datastore.get(key);
104+
```
105+
106+
#### Running a query
107+
In addition to retrieving entities by their keys, you can perform queries to retrieve entities by the values of their properties. A typical query includes an entity kind, filters to select entities with matching values, and sort orders to sequence the results. `gcloud-java-datastore` supports two types of queries: `StructuredQuery` (that allows you to construct query elements) and `GqlQuery` (which operates using [GQL syntax](https://cloud.google.com/datastore/docs/apis/gql/gql_reference)) in string format. In this tutorial, we will use a simple `StructuredQuery`.
108+
109+
Suppose that you've added more people to Datastore, and now you want to find all people whose favorite food is pizza. Import the following:
110+
111+
```java
112+
import com.google.gcloud.datastore.Query;
113+
import com.google.gcloud.datastore.QueryResults;
114+
import com.google.gcloud.datastore.StructuredQuery;
115+
import com.google.gcloud.datastore.StructuredQuery.PropertyFilter;
116+
```
117+
118+
Then add the following code to your program:
119+
120+
```java
121+
Query<Entity> query = Query.entityQueryBuilder()
122+
.kind("Person")
123+
.filter(PropertyFilter.eq("favorite_food", "pizza"))
124+
.build();
125+
QueryResults<Entity> results = datastore.run(query);
126+
while (results.hasNext()) {
127+
Entity currentEntity = results.next();
128+
}
129+
```
130+
131+
#### Complete source code
132+
133+
Here we put together all the code shown above into one program. This program assumes that you are running on Compute Engine or from your own desktop. To run this example on App Engine, simply move the code from the main method to your application's servlet class.
134+
135+
```java
136+
import com.google.gcloud.datastore.Datastore;
137+
import com.google.gcloud.datastore.DatastoreOptions;
138+
import com.google.gcloud.datastore.Entity;
139+
import com.google.gcloud.datastore.Key;
140+
import com.google.gcloud.datastore.KeyFactory;
141+
import com.google.gcloud.datastore.Query;
142+
import com.google.gcloud.datastore.QueryResults;
143+
import com.google.gcloud.datastore.StructuredQuery;
144+
import com.google.gcloud.datastore.StructuredQuery.PropertyFilter;
145+
146+
public class GcloudJavaDatastoreExample {
147+
148+
public static void main(String[] args) {
149+
// Create datastore service object.
150+
// By default, credentials are inferred from the runtime environment.
151+
Datastore datastore = DatastoreOptions.defaultInstance().service();
152+
153+
// Add an entity to Datastore
154+
KeyFactory keyFactory = datastore.newKeyFactory().kind("Person");
155+
Key key = keyFactory.newKey("John Doe");
156+
Entity entity = Entity.builder(key)
157+
.set("age", 51)
158+
.set("favorite_food", "pizza")
159+
.build();
160+
datastore.put(entity);
161+
162+
// Get an entity from Datastore
163+
Entity johnEntity = datastore.get(key);
164+
165+
// Add a couple more entities to make the query results more interesting
166+
Key janeKey = keyFactory.newKey("Jane Doe");
167+
Entity janeEntity = Entity.builder(janeKey)
168+
.set("age", 44)
169+
.set("favorite_food", "pizza")
170+
.build();
171+
Key joeKey = keyFactory.newKey("Joe Shmoe");
172+
Entity joeEntity = Entity.builder(joeKey)
173+
.set("age", 27)
174+
.set("favorite_food", "sushi")
175+
.build();
176+
datastore.put(janeEntity, joeEntity);
177+
178+
// Run a query
179+
Query<Entity> query = Query.entityQueryBuilder()
180+
.kind("Person")
181+
.filter(PropertyFilter.eq("favorite_food", "pizza"))
182+
.build();
183+
QueryResults<Entity> results = datastore.run(query);
184+
while (results.hasNext()) {
185+
Entity currentEntity = results.next();
186+
// Do something using the entity. (e.g. send an invite a pizza party)
187+
}
188+
}
86189
}
87190
```
88191

0 commit comments

Comments
 (0)