Getting Started

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]`.

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.

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:

Datastore datastore = DatastoreOptions.defaultInstance().service();

For other authentication options, see the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) page.

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:

Then add the following code to put an entity in Datastore.

KeyFactory keyFactory = datastore.newKeyFactory().kind("Person");

Key key = keyFactory.newKey("John Doe");

Entity entity = Entity.builder(key)

.set("age", 30)

.set("favorite_food", "pizza")

.build();

datastore.put(entity);

Later, if you want to get this entity back, add the following to your code:

Entity johnEntity = datastore.get("John Doe");

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`.

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:

import com.google.gcloud.datastore.Query;

import com.google.gcloud.datastore.QueryResults;

import com.google.gcloud.datastore.StructuredQuery;

import com.google.gcloud.datastore.StructuredQuery.PropertyFilter;

Then add the following code to your program:

Query<Entity> query = Query.entityQueryBuilder()

.kind("Person")

.filter(PropertyFilter.eq("favorite_food", "pizza"))

.build();

QueryResults<Entity> results = datastore.run(query);

while (results.hasNext()) {

Entity currentEntity = results.next();

}

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.

import com.google.gcloud.datastore.Datastore;

import com.google.gcloud.datastore.DatastoreOptions;

import com.google.gcloud.datastore.Entity;

import com.google.gcloud.datastore.Key;

import com.google.gcloud.datastore.KeyFactory;

import com.google.gcloud.datastore.Query;

import com.google.gcloud.datastore.QueryResults;

import com.google.gcloud.datastore.StructuredQuery;

import com.google.gcloud.datastore.StructuredQuery.PropertyFilter;

public class GcloudJavaDatastoreExample {

public static void main(String[] args) {

// Create datastore service object.

// By default, credentials are inferred from the runtime environment.

Datastore datastore = DatastoreOptions.defaultInstance().service();

// Add an entity to Datastore

KeyFactory keyFactory = datastore.newKeyFactory().kind("Person");

Key key = keyFactory.newKey("John Doe");

Entity entity = Entity.builder(key)

.set("age", 51)

.set("favorite_food", "pizza")

.build();

datastore.put(entity);

// Get an entity from Datastore

Entity johnEntity = datastore.get(key);

// Add a couple more entities to make the query results more interesting

Key janeKey = keyFactory.newKey("Jane Doe");

Entity janeEntity = Entity.builder(janeKey)

.set("age", 44)

.set("favorite_food", "pizza")

.build();

Key joeKey = keyFactory.newKey("Joe Shmoe");

Entity joeEntity = Entity.builder(joeKey)

.set("age", 27)

.set("favorite_food", "sushi")

.build();

datastore.put(janeEntity, joeEntity);

// Run a query

Query<Entity> query = Query.entityQueryBuilder()

.kind("Person")

.filter(PropertyFilter.eq("favorite_food", "pizza"))

.build();

QueryResults<Entity> results = datastore.run(query);

while (results.hasNext()) {

Entity currentEntity = results.next();

// Do something using the entity. (e.g. send an invite a pizza party)

}

}

public byte[] read(StorageObject from, Map<Option, ?> options, long position, int bytes)

throws StorageException {

MediaHttpDownloader downloader = req.getMediaHttpDownloader();

downloader.setContentRange(position, Ints.checkedCast(position + bytes - 1));

downloader.setDirectDownloadEnabled(true);

req.executeMediaAndDownloadTo(output);

return output.toByteArray();

byte[] read(StorageObject from, Map<Option, ?> options, long position, int bytes)

buffer = runWithRetries(new Callable<byte[]>() {

public byte[] call() {

return Objects.hash(serviceOptions, blob, requestOptions, position, isOpen, endOfStream,

chunkSize);