Stay organized with collections
Save and categorize content based on your preferences.
publicfinalclassDatastoreServiceConfig
User-configurable properties of the datastore.
Notes on usage:
The recommended way to instantiate a DatastoreServiceConfig object is to statically
import Builder.* and invoke a static creation method followed by an instance mutator (if
needed):
import staticcom.google.appengine.api.datastore.DatastoreServiceConfig.Builder.*;importcom.google.appengine.api.datastore.ReadPolicy.Consistency;...// eventually consistent readsDatastoreServiceConfigconfig=withReadPolicy(newReadPolicy(Consistency.EVENTUAL));// eventually consistent reads with a 5 second deadlineDatastoreServiceConfigconfig=withReadPolicy(newReadPolicy(Consistency.EVENTUAL)).deadline(5.0);
This is the name of a system property that determines how the Java SDK writes/reads empty lists
to/from Datastore.
Historically Datastore has not had the ability to represent an empty list in its persistent
store. Different SDKs have made different decisions on what to write to Datastore when a client
attempts to insert an empty list to the persistent store. The Java SDK has historically written
both empty lists and null values as null values to the persistent store.
With the release of this flag, Datastore can now represent empty lists within its persistent
store. This means that Datastore SDKs can distinguish between empty lists and null values. This
property controls whether this SDK writes an empty list as empty list or null to the persistent
store.
A note on queries: Null values can be indexed by Datastore which means they can interact
with queries. For example queries that find all entities with null values or order by a
property will include null values. Empty lists are not indexable by Datastore and so cannot
appear in similar queries.
Thus, if this flag was unset (the old behavior) and an empty list was stored into the
persistent store, it could appear in query results because it was really stored as a null
value.
If this flag is set (the new behavior) and an empty list is stored into the persistent
store, it will not appear it query results because it is stored as an empty list.
When this variable is set to anything other than "true" the system provides legacy behavior.
Null properties are written as null to Datastore
Empty collections are written as null to Datastore
A null is read as null from Datastore
An empty collection is read as null. Note that a read modify write of an entity with
an empty list will cause that list to be turned into a null value.
When this variable is set to "true":
Null properties are written as null to Datastore
Empty collections (#Collection#isEmpty()) are written as empty list to Datastore
A null is read as null from Datastore
An empty collection is read as null
When reading from Datastore an empty list is returned as an empty Collection.
It is strongly recommended that this property be set to true in order to provide
compatibility with other Datastore SDK's, as well as future versions of Datastore.
To set the flag:
System.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT,
Boolean.TRUE.toString());
Sets the maximum number of entity groups that can be represented in a single rpc.
For a non-transactional operation that involves more entity groups than the maximum, the
operation will be performed by executing multiple, asynchronous rpcs to the datastore, each of
which has no more entity groups represented than the maximum. So, if a put() operation has 8
entity groups and the maximum is 3, we will send 3 rpcs, 2 with 3 entity groups and 1 with 2
entity groups. This is a performance optimization - in many cases multiple, small, asynchronous
rpcs will finish faster than a single large asynchronous rpc. The optimal value for this
property will be application-specific, so experimentation is encouraged.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003e\u003ccode\u003eDatastoreServiceConfig\u003c/code\u003e allows users to configure properties for the datastore, including read policies, deadlines, and transaction management.\u003c/p\u003e\n"],["\u003cp\u003eThe recommended method for creating a \u003ccode\u003eDatastoreServiceConfig\u003c/code\u003e object is through static imports from \u003ccode\u003eBuilder\u003c/code\u003e and using static creation methods.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eDATASTORE_EMPTY_LIST_SUPPORT\u003c/code\u003e property controls how empty lists are handled, where setting it to "true" enables empty lists to be distinct from null values in the persistent store.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eDatastoreServiceConfig\u003c/code\u003e can be used to set a deadline for all RPCs initiated by the associated \u003ccode\u003eDatastoreService\u003c/code\u003e, which is specified in seconds.\u003c/p\u003e\n"],["\u003cp\u003eThe maximum number of entity groups per RPC can be set via \u003ccode\u003emaxEntityGroupsPerRpc()\u003c/code\u003e, impacting the performance of operations involving many entity groups by allowing for multiple asynchronous RPCs.\u003c/p\u003e\n"]]],[],null,["# Class DatastoreServiceConfig (2.0.0)\n\n public final class DatastoreServiceConfig\n\nUser-configurable properties of the datastore.\n\nNotes on usage: \n\nThe recommended way to instantiate a `DatastoreServiceConfig` object is to statically\nimport Builder.\\* and invoke a static creation method followed by an instance mutator (if\nneeded): \n\n\n import static com.google.appengine.api.datastore.DatastoreServiceConfig.Builder.*;\n import com.google.appengine.api.datastore.ReadPolicy.Consistency;\n\n ...\n\n // eventually consistent reads\n DatastoreServiceConfig config = withReadPolicy(new ReadPolicy(Consistency.EVENTUAL));\n\n // eventually consistent reads with a 5 second deadline\n DatastoreServiceConfig config =\n withReadPolicy(new ReadPolicy(Consistency.EVENTUAL)).deadline(5.0);\n \nInheritance\n-----------\n\n[java.lang.Object](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html) \\\u003e DatastoreServiceConfig \n\nInherited Members\n-----------------\n\n[Object.clone()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--) \n[Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-) \n[Object.finalize()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--) \n[Object.getClass()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--) \n[Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--) \n[Object.notify()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--) \n[Object.notifyAll()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--) \n[Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--) \n[Object.wait()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--) \n[Object.wait(long)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-) \n[Object.wait(long,int)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-)\n\nStatic Fields\n-------------\n\n### DATASTORE_EMPTY_LIST_SUPPORT\n\n public static final String DATASTORE_EMPTY_LIST_SUPPORT\n\nThis is the name of a system property that determines how the Java SDK writes/reads empty lists\nto/from Datastore.\n\nHistorically Datastore has not had the ability to represent an empty list in its persistent\nstore. Different SDKs have made different decisions on what to write to Datastore when a client\nattempts to insert an empty list to the persistent store. The Java SDK has historically written\nboth empty lists and null values as null values to the persistent store.\n\nWith the release of this flag, Datastore can now represent empty lists within its persistent\nstore. This means that Datastore SDKs can distinguish between empty lists and null values. This\nproperty controls whether this SDK writes an empty list as empty list or null to the persistent\nstore.\n\nA note on queries: Null values can be indexed by Datastore which means they can interact\nwith queries. For example queries that find all entities with null values or order by a\nproperty will include null values. Empty lists are not indexable by Datastore and so cannot\nappear in similar queries.\n\nThus, if this flag was unset (the old behavior) and an empty list was stored into the\npersistent store, it could appear in query results because it was really stored as a null\nvalue.\n\nIf this flag is set (the new behavior) and an empty list is stored into the persistent\nstore, it will not appear it query results because it is stored as an empty list.\n\nWhen this variable is set to anything other than \"true\" the system provides legacy behavior.\n\n- Null properties are written as null to Datastore\n- Empty collections are written as null to Datastore\n- A null is read as null from Datastore\n- An empty collection is read as null. **Note that a read modify write of an entity with\n an empty list will cause that list to be turned into a null value.**\n\nWhen this variable is set to \"true\":\n\n- Null properties are written as null to Datastore\n- Empty collections (#Collection#isEmpty()) are written as empty list to Datastore\n- A null is read as null from Datastore\n- An empty collection is read as null\n- When reading from Datastore an empty list is returned as an empty [Collection](https://docs.oracle.com/javase/8/docs/api/java/util/Collection.html).\n\nIt is strongly recommended that this property be set to true in order to provide\ncompatibility with other Datastore SDK's, as well as future versions of Datastore.\n\nTo set the flag: `\nSystem.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT,\nBoolean.TRUE.toString());\n`\n\nStatic Methods\n--------------\n\n### getEmptyListSupport()\n\n public static boolean getEmptyListSupport()\n\nReturns whether or not empty list support is enabled; see [#DATASTORE_EMPTY_LIST_SUPPORT](/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.DatastoreServiceConfig#com_google_appengine_api_datastore_DatastoreServiceConfig_DATASTORE_EMPTY_LIST_SUPPORT).\n\nMethods\n-------\n\n### deadline(double deadline)\n\n public DatastoreServiceConfig deadline(double deadline)\n\nSets the deadline, in seconds, for all rpcs initiated by the [DatastoreService](/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.datastore.DatastoreService) with\nwhich this config is associated.\n\n### getDeadline()\n\n public Double getDeadline()\n\nReturns the deadline, in seconds, to use. Can be `null`.\n\n### getImplicitTransactionManagementPolicy()\n\n public ImplicitTransactionManagementPolicy getImplicitTransactionManagementPolicy()\n\nReturns the `ImplicitTransactionManagementPolicy` to use.\n\n### getMaxEntityGroupsPerRpc()\n\n public Integer getMaxEntityGroupsPerRpc()\n\nReturns the maximum number of entity groups per rpc.\n\n### getReadPolicy()\n\n public ReadPolicy getReadPolicy()\n\nReturns the `ReadPolicy` to use.\n\n### implicitTransactionManagementPolicy(ImplicitTransactionManagementPolicy p)\n\n public DatastoreServiceConfig implicitTransactionManagementPolicy(ImplicitTransactionManagementPolicy p)\n\nSets the implicit transaction management policy.\n\n### maxEntityGroupsPerRpc(int maxEntityGroupsPerRpc)\n\n public DatastoreServiceConfig maxEntityGroupsPerRpc(int maxEntityGroupsPerRpc)\n\nSets the maximum number of entity groups that can be represented in a single rpc.\n\nFor a non-transactional operation that involves more entity groups than the maximum, the\noperation will be performed by executing multiple, asynchronous rpcs to the datastore, each of\nwhich has no more entity groups represented than the maximum. So, if a put() operation has 8\nentity groups and the maximum is 3, we will send 3 rpcs, 2 with 3 entity groups and 1 with 2\nentity groups. This is a performance optimization - in many cases multiple, small, asynchronous\nrpcs will finish faster than a single large asynchronous rpc. The optimal value for this\nproperty will be application-specific, so experimentation is encouraged.\n\n### readPolicy(ReadPolicy readPolicy)\n\n public DatastoreServiceConfig readPolicy(ReadPolicy readPolicy)\n\nSets the read policy."]]
