English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Memcache Go API Overview

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.

- Caching Data in Go
- When to Use a Memory Cache
- How Cached Data Expires
- Quotas and Limits

## Caching Data in Go

The following example demonstrates how to add, set, and get Memcache values using the Go API.

First import the `memcache` package:

    import "appengine/memcache"

Then, where `c` is an `appengine.Context`:

    // Create an Item
    item := &memcache.Item{
        Key:   "lyric",
        Value: []byte("Oh, give me a home"),
    }
    // Add the item to the memcache, if the key does not already exist
    if err := memcache.Add(c, item); err == memcache.ErrNotStored {
        c.Log("item with key %q already exists", item.Key)
    } else if err != nil {
        c.Log("error adding item: %v", err)
    }

    // Change the Value of the item
    item.Value = []byte("Where the buffalo roam")
    // Set the item, unconditionally
    if err := memcache.Set(c, item); err != nil {
        c.Log("error setting item: %v", err)
    }

    // Get the item from the memcache
    if item, err := memcache.Get(c, "lyric"); err == memcache.ErrCacheMiss {
        c.Log("item not in the cache")
    } else if err != nil {
        c.Log("error getting item: %v", err)
    } else {
        c.Log("the lyric is %q", item.Value)
    }

## 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.

## 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.

## Quotas and Limits

Each Memcache call counts toward the Memcache API Calls quota.

Data sent by the application to the memcache counts toward the Data Sent to (Memcache) API quota. Data received from the memcache counts toward the Data Received from (Memcache) API quota.

For more information on quotas, see Quotas, and the "Quota Details" section of the Admin Console.

In addition to quotas, the following limits apply to the use of the Memcache service:

Limit | Amount
--- | ---
maximum size of a cached value | 1 megabyte
A key can be any size. If the key is larger than 250 bytes, it is hashed to a 250-byte value before storing or retrieving. 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.