aerospike-data-modeling

Aerospike: data model design

Role

Act as a data architect. Your job is to turn requirements into a durable schema contract, not to write client code. The output is documents that a team reviews and implements against.

When to use this skill

Use it when the starting point is requirements without a schema:

• A new application or service with no Aerospike model yet.
• A redesign, where an existing model no longer serves its access patterns.
• A review of a proposed schema for structural defects before implementation.

Not this skill: writing or reviewing client code against an existing model, tuning policies, choosing CDT operations, debugging a slow batch read. That is aerospike-development. If a schema already exists and the question is "how do I use it well," hand off.

What you produce

Two documents. Write them to files — they are review artifacts with a life beyond the session, not chat output.

Deliverable	Contents
Schema guide	The full design: entity and relationship map, access pattern matrix, key schema, bin schema, one JSON example record per set, relationship and consolidation decisions, sizing worksheets, index rationale, growth and hot-key plan, validation plan. Plus the reasoning — an assumptions log, the alternatives rejected, and what evidence would reopen each decision.
Schema summary	The condensed contract derived from the guide: one table per set with key format, bins, types, and a one-line purpose; the index list; growth and overflow triggers. No rationale.

The schema summary is generated from the schema guide, never authored independently. If they disagree, the schema guide wins and the summary is regenerated.

See references/model-deliverables-schema-guide-summary.md.

Mental model for data architects

Aerospike is neither a relational database nor a document database.

• Records are semi-structured. A record is a collection of strongly typed bins, and the typing is per bin per record — there is no set-level schema. Two records in the same set can have entirely different bins, and the server enforces nothing. Absent bins cost nothing, so sparse and heterogeneous shapes are cheap rather than wasteful. The consequence for design: the data model is an application-level contract — namespace, set, key format, bin names, and bin types that every client agrees on — and nothing in the database will stop a client that writes a different shape. Write the contract down; that is what the schema guide is for.
• Records are the unit of I/O. Record data is stored contiguously, so every read fetches the entire record from storage, and every write rewrites the entire record — Aerospike does not do in-place updates. Requesting a subset of bins trims what crosses the network, not what is read from device. A record in the tens of KiB therefore spends tens of KiB of I/O on every access, no matter how small the change. Record size is an I/O budget, not just a storage number.
• There are no server-side joins. The multi-record tool is the batch read, which scatters and gathers across nodes in parallel.
• Every record costs 64 bytes of primary index metadata, per replica, usually in RAM. Many tiny records spend more memory on index than on data.
• Access patterns drive the model — not entity normalization, and not document embedding.
• Consolidate, but bound it. Enough to avoid tiny records; not so much that one record becomes a monolith or a hot key.