Google App Engine

Memcache Java API Overview

Python |Java |PHP |Go
High performance scalable web applications often use a distributed in-memory data cache in front of or in place of robust persistent storage for some tasks. App Engine includes a memory cache service for this purpose.

  1. Caching data with the Low-Level API
  2. Caching data with JCache
  3. When to use a memory cache
  4. Safely handling concurrent memcache updates
  5. How cached data expires
  6. Statistics
  7. Limits
  8. Configuring memcache

Caching data with the Low-Level API

The Low-Level API provides MemcacheService and AsyncMemcacheService for accessing memcache service. This API is richer than the one provided by JCache. For more details see Low-Level API.

// ...
    String key = ..
    byte[] value;

    // Using the synchronous cache
    MemcacheService syncCache = MemcacheServiceFactory.getMemcacheService();
    value = (byte[]) syncCache.get(key); // read from cache
    if (value == null) {
      // get value from other source
      // ........

      syncCache.put(key, value); // populate cache

    // Using the asynchronous cache
    AsyncMemcacheService asyncCache = MemcacheServiceFactory.getAsyncMemcacheService();
    Future<Object> futureValue = asyncCache.get(key); // read from cache
    // ... do other work in parallel to cache retrieval
    value = (byte[]) futureValue.get();
    if (value == null) {
      // get value from other source
      // ........

      // asynchronously populate the cache
      // Returns a Future<Void> which can be used to block until completion
      asyncCache.put(key, value);

Caching data with JCache

The App Engine Java SDK supports the JCache API. JCache provides a map-like interface to cached data. You store and retrieve values in the cache using keys. Keys and values can be of any Serializable type or class. For more details, see Using JCache.

When to use a memory cache

One use of a memory cache is to speed up common datastore queries. If many requests make the same query with the same parameters, and changes to the results do not need to appear on the web site right away, the app can cache the results in the memcache. Subsequent requests can check the memcache, and only perform the datastore query if the results are absent or expired. Session data, user preferences, and any other queries performed on most pages of a site are good candidates for caching.

Memcache may be useful for other temporary values. However, when considering whether to store a value solely in the memcache and not backed by other persistent storage, be sure that your application behaves acceptably when the value is suddenly not available. Values can expire from the memcache at any time, and may be expired prior to the expiration deadline set for the value. For example, if the sudden absence of a user's session data would cause the session to malfunction, that data should probably be stored in the datastore in addition to the memcache.

Safely handling concurrent memcache updates

The putIfUntouched and getIdentifiable methods of the memcache service can be used to provide a way to safely make key-value updates to memcache in scenarios where multiple requests are being handled concurrently that need to update the same memcache key in an atomic fashion. (It is possible to get race conditions in those scenarios.)

How cached data expires

By default, values stored in memcache are retained as long as possible. Values may be evicted from the cache when a new value is added to the cache if the cache is low on memory. When values are evicted due to memory pressure, the least recently used values are evicted first.

The app can provide an expiration time when a value is stored, as either a number of seconds relative to when the value is added, or as an absolute Unix epoch time in the future (a number of seconds from midnight January 1, 1970). The value will be evicted no later than this time, though it may be evicted for other reasons.

Under rare circumstances, values may also disappear from the cache prior to expiration for reasons other than memory pressure. While memcache is resilient to server failures, memcache values are not saved to disk, so a service failure may cause values to become unavailable.

In general, an application should not expect a cached value to always be available.

You can erase an application's entire cache via the API or via the Admin Console (under Memcache Viewer).


Memcache maintains statistics about the amount of data cached for an application, the cache hit rate, and the age of cache items. You can view these statistics using the API or in the Administration Console, under Memcache Viewer.


The following limits apply to the use of the memcache service:

  • The maximum size of a cached data value is 1 MB minus the size of the key minus an implementation-dependent overhead which is approximately 96 bytes.
  • A key cannot be larger than 250 bytes. In the Java runtime, keys that are objects or strings longer than 250 bytes will be hashed. (Other runtimes behave differently.)
  • The "multi" batch operations can have any number of elements. The total size of the call and the total size of the data fetched must not exceed 32 megabytes.

Configuring memcache

The memcache service provides best-effort cache space by default. Apps with billing enabled may opt to use dedicated memcache which provides a fixed cache size assigned exclusively to your app. The service is configured via memcache settings on the Admin Console.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.