.readme-partials.yaml

custom_content: |
  See the [Google Cloud Datastore docs][cloud-datastore-activation] for more details on how to activate
  Cloud Datastore for your project.

  See the [Datastore client library docs][datastore-client-lib-docs] to learn how to interact
  with the Cloud Datastore using this Client Library.

  #### Creating an authorized service object
  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:

  ```java
  import com.google.cloud.datastore.Datastore;
  import com.google.cloud.datastore.DatastoreOptions;

  Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
  ```

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

  #### Storing data
  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 email.  First, add the following imports at the top of your file:

  ```java
  import com.google.cloud.datastore.Entity;
  import com.google.cloud.datastore.Key;
  import com.google.cloud.datastore.KeyFactory;
  ```

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

  ```java
  KeyFactory keyFactory = datastore.newKeyFactory().setKind("Person");
  Key key = keyFactory.newKey("john.doe@gmail.com");
  Entity entity = Entity.newBuilder(key)
      .set("name", "John Doe")
      .set("age", 51)
      .set("favorite_food", "pizza")
      .build();
  datastore.put(entity);
  ```

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

  ```java
  Entity johnEntity = datastore.get(key);
  ```

  #### Running a query
  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. `google-cloud-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:

  ```java
  import com.google.cloud.datastore.Query;
  import com.google.cloud.datastore.QueryResults;
  import com.google.cloud.datastore.StructuredQuery;
  import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
  ```

  Then add the following code to your program:

  ```java
  Query<Entity> query = Query.newEntityQueryBuilder()
      .setKind("Person")
      .setFilter(PropertyFilter.eq("favorite_food", "pizza"))
      .build();
  QueryResults<Entity> results = datastore.run(query);
  while (results.hasNext()) {
    Entity currentEntity = results.next();
    System.out.println(currentEntity.getString("name") + ", you're invited to a pizza party!");
  }
  ```

  Cloud Datastore relies on indexing to run queries. Indexing is turned on by default for most types of properties. To read more about indexing, see the [Cloud Datastore Index Configuration documentation](https://cloud.google.com/datastore/docs/tools/indexconfig).

  #### Updating data
  Another thing you'll probably want to do is update your data. The following snippet shows how to update a Datastore entity if it exists.

  ```java
  KeyFactory keyFactory = datastore.newKeyFactory().setKind("keyKind");
  Key key = keyFactory.newKey("keyName");
  Entity entity = datastore.get(key);
  if (entity != null) {
    System.out.println("Updating access_time for " + entity.getString("name"));
    entity = Entity.newBuilder(entity)
        .set("access_time", DateTime.now())
        .build();
    datastore.update(entity);
  }
  ```

  The complete source code can be found at
  [UpdateEntity.java](https://github.com/googleapis/google-cloud-java/blob/2c1850d4f82f3fbd7b4a50582384c008085aa1a8/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/UpdateEntity.java).

  #### Complete source code

  In
  [AddEntitiesAndRunQuery.java](https://github.com/googleapis/google-cloud-java/blob/2c1850d4f82f3fbd7b4a50582384c008085aa1a8/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/AddEntitiesAndRunQuery.java)
  we put together all the code to store data and run queries into one program. The program assumes that you are
  running on Compute Engine or from your own desktop. To run the example on App Engine, simply move
  the code from the main method to your application's servlet class and change the print statements to
  display on your webpage.
  
  gRPC Java Datastore Client User Guide
  -------
  In this feature launch, the [Java Datastore client](https://github.com/googleapis/java-datastore) now offers gRPC as a transport layer option with experimental support. Using [gRPC connection pooling](https://grpc.io/docs/guides/performance/) enables distributing RPCs over multiple connections which may improve performance.
  
  #### Download Instructions
  Instructions:
  1. Clone the grpc-experimental branch from GitHub:
  ```python
  git clone -b grpc-experimental https://github.com/googleapis/java-datastore.git
  ```
  2. Run the following commands to build the library:
  ```python
  # Go to the directory the code was downloaded to
  cd java-datastore/
  
  # Build the library
  mvn clean install -DskipTests=true
  ```
  3. Add the following dependency to your project:
  ```xml
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-datastore</artifactId>
    <version>2.20.0-grpc-experimental-1-SNAPSHOT</version>
  </dependency>
  ```
  
  #### How to Use
  To opt-in to the gRPC transport behavior, simply add the below line of code (`setTransportOptions`) to your Datastore client instantiation.
  
  Example:
  ```java
  DatastoreOptions datastoreOptions =
       DatastoreOptions.newBuilder()
               .setProjectId("my-project")
               .setDatabaseId("my-database")
               .setTransportOptions(GrpcTransportOptions.newBuilder().build())
               .build();
  ```
  Setting the transport options explicitly to `GrpcTransportOptions` will signal the client to use gRPC instead of HTTP when making calls to the server.
  
  To revert back to the existing stable behavior and transport, simply remove the transport options line or replace it with `HttpTransportOptions`. Please note this will require an application rebuild and restart.
  Example:
  ```java
  // will default to existing HTTP transport behavior
  DatastoreOptions datastoreOptions = DatastoreOptions.newBuilder()
      .setProjectId("my-project")
      .setDatabaseId("my-database")
      .build();
  
  // will also default to existing HTTP transport behavior
  DatastoreOptions datastoreOptions =
              DatastoreOptions.newBuilder()
                .setProjectId("my-project")
                .setDatabaseId("my-database")
                .setTransportOptions(HttpTransportOptions.newBuilder()
                .setConnectTimeout(1000)
                .build()).build();
  ```
  
  Note: client instantiations that already use `setTransportOptions` with `HttpTransportOptions` will continue to have the same behavior. Only transports that are explicitly set to gRPC will change.
  
  #### Verify Datastore Transport Options Type
  To verify which type of TransportOptions you have successfully configured, you can use the below lines of code to compare transport options type:
  ```java
  // checks if using gRPC transport options
  boolean isGRPC = datastore.getOptions().getTransportOptions() instanceof GrpcTransportOptions;
  
  // checks if using HTTP transport options
  boolean isHTTP = datastore.getOptions().getTransportOptions() instanceof HTTPTransportOptions;
  ```
  
  #### New Features
  There are new gRPC specific features available to use in this update.
  
  ##### Channel Pooling
  To customize the number of channels your client uses, you can update the channel provider in the DatastoreOptions. 
  See [ChannelPoolSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.grpc.ChannelPoolSettings) and [Performance Best Practices](https://grpc.io/docs/guides/performance/) for more information on channel pools and best practices for performance.
  
  Example:
  ```java
  InstantiatingGrpcChannelProvider channelProvider =
        DatastoreSettings.defaultGrpcTransportProviderBuilder()
                .setChannelPoolSettings(
                       ChannelPoolSettings.builder()
                                .setInitialChannelCount(MIN_VAL)
                                .setMaxChannelCount(MAX_VAL)
                                .build())
                .build();
  
  DatastoreOptions options = DatastoreOptions.newBuilder()
                            .setProjectId("my-project")
                            .setChannelProvider(channelProvider)
                            .setTransportOptions(GrpcTransportOptions.newBuilder().build())
                            .build();
  ```
  Testing
  -------

  This library has tools to help write tests for code that uses the Datastore.
  
  #### On your machine

  You can test against a temporary local Datastore by following these steps:

  1. [Install Cloud SDK and start the emulator](https://cloud.google.com/datastore/docs/tools/datastore-emulator)

  To determine which host/port the emulator is running on:
  
  ```
  $ gcloud beta emulators datastore env-init
  
  # Sample output:
  #   export DATASTORE_EMULATOR_HOST=localhost:8759
  ```
  
  3. Point your client to the emulator
  
  ```java
  DatastoreOptions options = DatastoreOptions.newBuilder()
  .setProjectId(DatastoreOptions.getDefaultProjectId())
  .setHost(System.getenv("DATASTORE_EMULATOR_HOST"))
  .setCredentials(NoCredentials.getInstance())
  .setRetrySettings(ServiceOptions.getNoRetrySettings())
  .build();
  Datastore datastore = options.getService();
  ```
  4. Run your tests

  Example Applications
  --------------------
  - [`Bookshelf`](https://github.com/GoogleCloudPlatform/getting-started-java/tree/main/bookshelf) - An App Engine app that manages a virtual bookshelf.
    - This app uses `google-cloud` to interface with Cloud Datastore and Cloud Storage. It also uses Cloud SQL, another Google Cloud Platform service.
  - [`Flexible Environment/Datastore example`](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/main/flexible/datastore) - A simple app that uses Cloud Datastore to list the last 10 IP addresses that visited your site.
  - [`SparkDemo`](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/main/flexible/sparkjava) - An example of using `google-cloud-datastore` from within the SparkJava and App Engine Flexible Environment frameworks.
    - Read about how it works on the example's [README page](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/main/flexible/sparkjava#how-does-it-work).