[googledatastore] Support entity-grouping mode

Add support to allow users to group entities in two different ways, and add documentations for the overall googledatastore.properties file.

googledatastore/conf/googledatastore.properties

@@ -17,6 +17,76 @@
 # Sample property file for Google Cloud Datastore DB client 
 
 ## Mandatory parameters
+# See this link for instructions about setting up Google Cloud Datastore and
+# authentication:
+# https://cloud.google.com/datastore/docs/getstarted/start_java/
+#
+# After you setup your environment, you will have 3 pieces of information ready:
+# datasetId, service account email, and a private key file. These must be
+# configured via the properties below
+#
+# googledatastore.datasetId=<string id of your dataset>
+# googledatastore.privateKeyFile=<full path to your private key file>
+# googledatastore.serviceAccountEmail=<Your service account email>
+
+# Google Cloud Datastore's read and update APIs do not support
+# reading or updating a select subset of properties for an entity.
+# (as of version v1beta2-rev1-3.0.2)
+# Therefore, it's recommended that you set writeallfields and readallfields
+# to true to get stable and comparable performance numbers.
+writeallfields = true
+readallfields = true
 
 ## Optional parameters
+#
+# Decides the consistency level of read requests. Acceptable value is:
+# EVENTUAL, STRONG (default is EVENTUAL)
+#
+# googledatastore.readConsistency=EVENTUAL
 
+# Decides how we group entities into entity groups. In Google Datastore,
+# Entity Group is the unit in which the user can perform strongly
+# consistent query on multiple items; Meanwhile, Entity group also has
+# certain limitations in performance, especially with write QPS.
+#
+# We support two modes here:
+#
+# 1. [default] One entity per group (ONE_ENTITY_PER_GROUP)
+#
+# In this mode, every entity is a "root" entity and sits in one group,
+# and every entity group has only one entity. Write QPS is high in this
+# mode (and there is no documented limitation on this). But query across
+# multiple entities are eventually consistent.
+#
+# When this mode is set, every entity is created with no ancestor key (meaning 
+# the entity itself is the "root" entity).
+#
+# 2. Multiple entities per group (MULTI_ENTITY_PER_GROUP)
+#
+# In this mode, all entities in one benchmark run are placed under one
+# ancestor (root) node therefore inside one entity group. Query/scan
+# performed on these entities will be strongly consistent but write QPS
+# will be subject to documented limitation (current is at 1 QPS).
+#
+# Because of the write QPS limit, it's highly recommended that you rate
+# limit your benchmark's test rate to avoid excessive errors.
+#
+# The goal of this MULTI_ENTITY_PER_GROUP mode is to allow user to
+# benchmark and understand performance characteristics of a single entity
+# group of the Google Datastore.
+#
+# While in this mode, one can optionally specify a root key name. If not
+# specified, a default name will be used.
+#
+# googledatastore.entityGroupingMode=ONE_ENTITY_PER_GROUP
+
+# If you set the googledatastore.entityGroupingMode property to 
+# MULTI_ENTITY_PER_GROUP, you can optionally specify the name of the root entity
+#
+# googledatastore.rootEntityName="YCSB_ROOT_ENTITY"
+
+# Strongly recommended to set to uniform.
+# requestdistribution = uniform
+
+# Enable/disable debug message, default is false.
+# googledatastore.debug = false

googledatastore/src/main/java/com/yahoo/ycsb/db/GoogleDatastoreClient.java

@@ -61,6 +61,14 @@ public class GoogleDatastoreClient extends DB {
     DELETE
   }
 
+  /**
+   * Defines a EntityGroupingMode enum used in this class.
+   */
+  private enum EntityGroupingMode {
+    ONE_ENTITY_PER_GROUP,
+    MULTI_ENTITY_PER_GROUP
+  }
+
   private static Logger logger =
       Logger.getLogger(GoogleDatastoreClient.class);
 
@@ -68,6 +76,11 @@ public class GoogleDatastoreClient extends DB {
   // DB client, such as DynamoDB). User can override this via configure.
   private ReadConsistency readConsistency = ReadConsistency.EVENTUAL;
 
+  private EntityGroupingMode entityGroupingMode =
+      EntityGroupingMode.ONE_ENTITY_PER_GROUP;
+
+  private String rootEntityName;
+
   private Datastore datastore = null;
 
   public GoogleDatastoreClient() {}
@@ -123,6 +136,26 @@ public class GoogleDatastoreClient extends DB {
       }
     }
 
+    //
+    // Entity Grouping Mode (googledatastore.entitygroupingmode), see
+    // documentation in conf/googledatastore.properties.
+    //
+    String entityGroupingConfig = getProperties().getProperty(
+        "googledatastore.entityGroupingMode", null);
+    if (entityGroupingConfig != null) {
+      try {
+        this.entityGroupingMode = EntityGroupingMode.valueOf(
+            entityGroupingConfig.trim().toUpperCase());
+      } catch (IllegalArgumentException e) {
+        throw new DBException("Invalid entity grouping mode specified: " +
+            entityGroupingConfig + ". Expecting ONE_ENTITY_PER_GROUP or " +
+            "MULTI_ENTITY_PER_GROUP.");
+      }
+    }
+
+    this.rootEntityName = getProperties().getProperty(
+        "googledatastore.rootEntityName", "YCSB_ROOT_ENTITY");
+
     try {
       // Setup the connection to Google Cloud Datastore with the credentials
       // obtained from the configure.
@@ -227,9 +260,15 @@ public class GoogleDatastoreClient extends DB {
   }
 
   private Key.Builder buildPrimaryKey(String table, String key) {
-    return Key.newBuilder().addPathElement(
-        Key.PathElement.newBuilder()
-        .setKind(table)
+    Key.Builder result = Key.newBuilder();
+
+    if (this.entityGroupingMode == EntityGroupingMode.MULTI_ENTITY_PER_GROUP) {
+      // All entities are in side the same group when we are in this mode.
+      result.addPathElement(Key.PathElement.newBuilder().setKind(table).
+          setName(rootEntityName));
+    }
+
+    return result.addPathElement(Key.PathElement.newBuilder().setKind(table)
         .setName(key));
   }