Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Memcached Basics

Keys, Values, Flags and Serialization

Learn Memcached's rules for keys (250 bytes, no spaces), values (1 MB), flags, compression and serialization, plus a key-naming convention that avoids collisions.

An item in Memcached has four parts you control: a key, a value, flags and an expiry. Most cache bugs that are not about invalidation come from getting one of the first three wrong: a key with a space in it, a value that is a byte too large, or a serialization format that changes between deploys. This lesson sets out the rules and good habits.

Keys

The server's rules for a key:

  • At most 250 bytes.
  • No whitespace and no control characters (the protocol is separated by spaces and newlines).
  • Case-sensitive: User:1 and user:1 are different keys.

Client libraries often add their own limits or helpers, and many hash long keys for you. A key containing user input (a search term, an email address) is dangerous if you pass it through unchanged: spaces or newlines could break the command, and a malicious user could craft keys that collide with others. Hash or encode untrusted parts.

Python Making any text safe to use in a key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Encoding keeps keys readable for debugging, while hashing is the escape hatch for very long ones. A SHA-256 hex digest is 64 characters, well under the limit.

A key-naming convention

A good key tells you what it holds and which version of the format it uses:

TEXT
<app>:<version>:<entity>:<id>[:<variant>]
shop:v3:product:1042
shop:v3:product:1042:fr
shop:v3:user:77:cart
  • The app prefix prevents collisions when several applications share one pool.
  • The version lets a new deploy that changes the value format use fresh keys instead of reading old, incompatible data. Old entries simply expire.
  • The entity and id make keys predictable so you can delete exactly the right one.
  • Variants (language, currency, device) must be in the key whenever they change the value, otherwise users see each other's variant.

Values

A value is a blob of bytes, up to 1 MB by default (-I raises it, but big values are usually a design smell). A larger value is rejected with SERVER_ERROR object too large for cache. Many clients compress values over a threshold and record that in the flags.

Why avoid huge values?

  • Reading 1 MB on every request wastes network bandwidth and CPU.
  • Large items live in big slab classes and make memory use less efficient.
  • A single update rewrites the whole thing, even if only one field changed.

Instead, split big structures: cache each product under its own key rather than the whole catalogue under one.

Flags

The flags field is a 32-bit number stored with the item and returned untouched. The server never interprets it. Clients use it to remember how the value was encoded: raw bytes, UTF-8 text, JSON, pickled object, compressed or not. You have already seen this in your first client.

Serialization formats

Format Good for Watch out for
Raw bytes / UTF-8 text Strings, HTML fragments Nothing to decode, but only strings
JSON Cross-language data (PHP, Python, Node share a cache) Loses types (dates become strings, tuples become lists)
MessagePack, protobuf Compact, fast, cross-language Needs a schema or library on each side
pickle, PHP serialize, Java serialization Language-native objects Unsafe if untrusted writers exist; breaks when classes change; not shared across languages

Prefer JSON or another neutral format when there is any chance that two services or two versions of the same code will read the same keys.

Python JSON round trip, and what it changes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The tuple turned into a list and the date into a string. A cache layer should convert such values back explicitly, or store only JSON-friendly types.

Versioning the value format

When the shape of a cached value changes (a new field, a renamed field), old entries are still in the cache. Reading them with new code can crash. Two defences: put the format version in the key (v3), or store a version inside the value and treat a mismatch as a miss.

Python Treat an old-format value as a miss

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Compression

Compressing large text (HTML, JSON) with zlib or LZ4 can save memory and bandwidth. The trade-off is CPU time on every read and write. Compress only above a size threshold (say 1 KB), and mark the value as compressed with a flag so readers know to decompress it.

Python Compression above a threshold

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these is NOT allowed in a Memcached key?

    Keys cannot contain whitespace or control characters because the protocol uses them as separators.
  2. 2. What is the default maximum item size?

    Items are limited to 1 MB by default (-I changes it). The 250-byte limit applies to keys.
  3. 3. Why put a format version in the key (shop:v3:...)?

    Old entries are never read by new code and simply expire.
  4. 4. Which serialization is safest when several languages share a cache?

    Language-native formats are tied to one runtime and can be unsafe; JSON is readable by all.

Summary

  • Keys: at most 250 bytes, no whitespace or control characters; encode or hash untrusted parts.
  • Name keys as app, version, entity, id (plus variants that change the value).
  • Values: up to 1 MB by default; split large data into smaller items.
  • Flags hold a client-defined type tag; the server never reads them.
  • Prefer JSON over native formats, version your value format, and compress only large values.

Next: Stats and Multi-Get