This page provides an overview of the App Engine memcache service. Highperformance scalable web applications often use a distributed in-memory datacache in front of or in place of robust persistent storage for some tasks. AppEngine includes a memory cache service for this purpose. To learn how toconfigure, monitor, and use the memcache service, readUsing Memcache.

When to use a memory cache

One use of a memory cache is to speed up common datastore queries. If manyrequests make the same query with the same parameters, and changes to theresults do not need to appear on the web site right away, the application cancache 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 other data returned by queries for web pagesare good candidates for caching.

Memcache can be useful for other temporary values. However, when consideringwhether to store a value solely in the memcache and not backed by otherpersistent storage, be sure that your application behaves acceptably when thevalue is suddenly not available. Values can expire from the memcache at anytime, and can be expired prior to the expiration deadline set for the value. Forexample, if the sudden absence of a user's session data would cause the sessionto malfunction, that data should probably be stored in the datastore in additionto the memcache.

Service levels

App Engine supports two levels of the memcache service:

• Shared memcache is the free default for App Engine applications. Itprovides cache capacity on a best-effort basis and is subject to the overalldemand of all the App Engine applications using the shared memcache service.

• Dedicated memcache provides a fixed cache capacity assigned exclusivelyto your application. It's billed by the GB-hour of cache size and requiresbilling to be enabled. Having control over cache size means your app canperform more predictably and with fewer reads from more costly durablestorage.

Both memcache service levels use the same API. To configure the memcache servicefor your application, seeUsing Memcache.

Dedicated memcache billing is charged in 15 minute increments. If you pay in a currency other than USD, the prices listed in your currency onCloud Platform SKUs apply.

If your app needs more memcache capacity,contact our Sales team.

Limits

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

• The maximum size of a cached data value is 1 MB (10^6bytes).
• A keycannot be larger than 250 bytes. In the Python runtime, keys that are stringslonger than 250 bytes will be hashed. (Other runtimes behavedifferently.)
• The "multi" batch operations can have any number of elements. The total sizeof the call and the total size of the data fetched must not exceed 32megabytes.
• A memcache key cannot contain a null byte.

Recommendations and best practices

When using Memcache, we recommend that you design your applications to:

• Handle the case where a cached value is not always available.

  • Memcache is not durable storage. According to theeviction policy, keys are evicted when thecache fills up. Changes in the cache configuration or datacentermaintenance events can also flush some or all of the cache.
  • Memcache may experience temporary unavailability. Memcache operationscan fail for various reasons including changes in cache configuration ordatacenter maintenance events. Applications should be designed to catchfailed operations without exposing these errors to end users. Thisguidance applies especially to Set operations.

• Use the batching capability of the API when possible.

  • Doing so increases the performance and efficiency of your app,especially for small items.

• Distribute load across your memcache keyspace.

  • Having a single or small set of memcache items represent adisproportionate amount of traffic will hinder your app from scaling.This guidance applies to both operations/sec and bandwidth. You canoften alleviate this problem by explicitly sharding your data.

    For example, you can split a frequently updated counter among severalkeys, reading them back and summing only when you need a total.Likewise, you can split a 500K piece of data that must be read on everyHTTP request across multiple keys and read them back using a singlebatch API call. (Even better would be to cache the value in instancememory.) For dedicated memcache, the peak access rate on a single keyshould be 1-2 orders of magnitude less than the per-GB rating.

• Retain your own keys in order to retrieve values from the cache.

  • Memcache does not provide a method to list keys. Due to the nature ofthe cache, it is not possible to list keys without disrupting the cache.Additionally, some languages, like Python, hash long keys, and theoriginal keys are only known to the application.

How cached data expires

Memcache contains key/value pairs. The pairs in memory at any time change asitems are written and retrieved from the cache.

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

The app can provide an expiration time when a value is stored, as either anumber of seconds relative to when the value is added, or as an absolute Unixepoch time in the future (a number of seconds from midnight January 1,1970). The value is evicted no later than this time, though it can beevicted earlier for other reasons. Incrementing the value stored for an existingkey does not update its expiration time.

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

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

You can erase an application's entire cache via the API or in the memcachesection ofGoogle Cloud console.

Key logical components of compare and set

If you're updating the value of a memcache key that might receive otherconcurrent write requests, you must use the memcacheClient object, whichstores certain state information that's used by the methodsthat support compare and set. You cannot use the memcache functionsget() orset(), because they are stateless. TheClient class itself is notthread-safe, so you should not use the sameClient object in more than onethread.

When you retrieve keys, you must use the memcacheClient methods that supportcompare and set:gets() orget_multi() with thefor_cas parameter set toTrue.

When you update a key, you must use the memcacheClient methods that supportcompare and set:cas() orcas_multi().

The other key logical component is the App Engine memcache service and itsbehavior with regard to compare and set. The App Engine memcache service itselfbehaves atomically. That is, when two concurrent requests (for the same app id)use memcache, they will go to the same memcache service instance, and thememcache service has enough internal locking so that concurrent requests for thesame key are properly serialized. In particular this means that twocas()requests for the same key do not actually run in parallel -- the service handlesthe first request that came in until completion (that is, updating the value andtimestamp) before it starts handling the second request.

To learn how to use compare and set in Python, readHandling concurrent writes.

What's next

• Learn how to configure, monitor, and use memcache inUsing Memcache.
• Look throughMemcache Examples.