data consistency

Data Consistency in Datastore Queries

Not applicable to this runtime.

Data consistency levels

Cloud Datastore queries can deliver their results at either of two consistency levels:

Strongly consistent queries guarantee the freshest results, but may take longer to complete.
Eventually consistent queries generally run faster, but may occasionally return stale results.

In an eventually consistent query, the indexes used to gather the results are also accessed with eventual consistency. Consequently, such queries may sometimes return entities that no longer match the original query criteria, while strongly consistent queries are always transactionally consistent.

Datastore query data consistency

Queries return their results with different levels of consistency guarantee, depending on the nature of the query:

Ancestor queries (those within an entity group) are strongly consistent by default, but can instead be made eventually consistent by setting the Datastore read policy (see below).
Non-ancestor queries are always eventually consistent.

Fetching an entity by key, which is also called "lookup by key", is strongly consistent.

Setting the Datastore read policy

To improve performance, you can set the Datastore read policy so that all reads and queries are eventually consistent. (The API also allows you to explicitly set a strong consistency policy, but this setting will have no practical effect, since non-ancestor queries are always eventually consistent regardless of policy.)

You can also set the Datastore call deadline, which is the maximum time, in seconds, that the application will wait for {{ datastore_name_short }} to return a result before aborting with an error. The default deadline is 60 seconds; it is not currently possible to set it higher, but you can adjust it downward to ensure that a particular operation fails quickly (for instance, to return a faster response to the user).

To set the Datastore read policy in Java, you construct a Datastore service configuration (DatastoreServiceConfig), using the nested helper class DatastoreServiceConfig.Builder, and pass it an instance of class ReadPolicy. The following example shows how to set the read policy, the call deadline, or both:

double deadline = 5.0;

// Construct a read policy for eventual consistency
ReadPolicy policy = new ReadPolicy(ReadPolicy.Consistency.EVENTUAL);

// Set the read policy
DatastoreServiceConfig eventuallyConsistentConfig =
    DatastoreServiceConfig.Builder.withReadPolicy(policy);

// Set the call deadline
DatastoreServiceConfig deadlineConfig = DatastoreServiceConfig.Builder.withDeadline(deadline);

// Set both the read policy and the call deadline
DatastoreServiceConfig datastoreConfig =
    DatastoreServiceConfig.Builder.withReadPolicy(policy).deadline(deadline);

// Get Datastore service with the given configuration
DatastoreService datastore = DatastoreServiceFactory.getDatastoreService(datastoreConfig);

What's next?

Learn how to specify what a query returns and further control query results. * Learn the common restrictions for queries on Datastore. * Learn about query cursors, which allow an application to retrieve a query's results in convenient batches. * Learn the basic syntax and structure of queries for Datastore.

We recommend using the NDB Client Library for Datastore, which has several benefits compared to this client library, such as automatic entity caching via the Memcache API. If you are currently using the older DB Client Library, see the DB to NDB Migration Guide.

data consistency

Data Consistency in Datastore Queries