Module 06 · Lesson 2 of 11Free

Document and key-value databases compared

Level

Intermediate

Topic

NoSQL databases and when to use them

Reading time

19 min

JSON doesn’t choose the database

A seller on Kartly asks for all blue shirts costing less than ₹1,000. The catalog has 20 million products, but its prototype only supports fetching one product by ID. Reading every product would turn a filter into a catalog-wide scan.

The cart service stores JSON too. Yet it usually knows exactly whose cart to fetch.

How do you choose between document and key-value storage when the records look alike?

Kartly is now at the many-services stage. We’ll focus on its catalog and cart services. Additional sizes and request rates below are illustrative assumptions for this lesson.

A key-value interface starts with a unique key. You ask it to retrieve, replace or remove the associated value. In the simplest version, field meanings belong to your application.

A document database exposes fields inside structured records. Its query interface can select records using those fields. Efficient selection still depends on indexes.

These are useful models, not strict product categories. DynamoDB supports nested attributes alongside primary-key access and secondary indexes. A product can support both styles.^{3Core components of Amazon DynamoDBAmazon Web Services, Amazon DynamoDB Developer Guide}

Build on SQL vs NoSQL: choosing a data store: choose required operations and guarantees before choosing a database name. The next step is to write those operations down.

Start with the questions you ask

Kartly’s team lists its access patterns: the precise ways each service reads or changes data.

The first and third reads look identical at the storage boundary. Both provide an identifier and expect one record.

The filtered catalog read is different. It asks storage to discover identifiers.

A key-value database is not automatically a cache. Whether lost data is recoverable depends on its role and configured durability, not its access interface.

Likewise, a document database is not automatically a good search engine. This lesson’s catalog filters are exact fields and ranges. Full-text ranking is a separate requirement.

Now we need to see what each operation actually makes storage do.

Follow the key or the index

Consider this cart service layout:

A cart value might be:

{
  "version": 7,
  "items": {
    "p42": 2,
    "p91": 1
  }
}

The item map holds quantities, not authoritative prices. Checkout must obtain current prices and stock from their owners.

A key lookup follows this path:

1. The cart service constructs cart:u17 from the authenticated customer.
2. The storage client routes the request to the responsible partition.
3. That partition locates the key using its local storage structure.
4. Storage returns the value, or reports that the key is absent.

The routing algorithm is product-specific. For example, DynamoDB hashes its partition-key value to determine placement.^{3Core components of Amazon DynamoDBAmazon Web Services, Amazon DynamoDB Developer Guide} A distributed key-value database is therefore not necessarily one large in-memory hash map.

Now consider a catalog document:

{
  "_id": "p42",
  "seller_id": "s8",
  "category": "shirt",
  "price_minor": 89900,
  "currency": "INR",
  "attributes": {
    "colour": "blue",
    "size": "M"
  }
}

For our filter, propose an index ordered by category, attributes.colour, then price_minor. The equality fields narrow the region before the price range. The database can walk matching index entries instead of inspecting every product.

This follows the access-path reasoning from Indexes. MongoDB’s guidance recommends indexing commonly queried fields and notes that indexes add write work and consume storage.^{1Best Practices for Data Modeling in MongoDBMongoDB, MongoDB Docs}

A possible read path is:

1. The catalog service submits the category, colour and price conditions.
2. The query engine selects a suitable index.
3. Storage reads matching entries and fetches the required documents.
4. The service returns a bounded page of products.

The index is a maintained mapping from field values to record identifiers. Its cost exists even when nobody is running that query.

Could the cart-style store maintain its own blue-shirts lookup? Yes. But inserting a product now means updating both the product and that lookup. A crash between them can hide a product or leave an outdated entry.

Building that mapping yourself means accepting responsibility for index maintenance. Before doing so, compare its cost with a database that already owns the operation.

One cart needs one boundary

Suppose Kartly stores every cart item under its own key. Fetching the cart now needs a way to discover its item keys. Editing several items also crosses multiple records.

The simplest alternative is one bounded cart value. This makes one customer’s current selection a useful aggregate: a group of data treated as one read or update boundary.

That boundary should follow behavior, not merely ownership. A product belongs to a seller, but embedding every seller product inside one seller document creates a growing record.

Here is the service boundary, independent of the chosen vendor:

A catalog write validates the seller’s edit, updates the document and lets storage maintain the relevant indexes. A cart write reads the record, calculates a replacement, then submits that replacement conditionally.

That final word matters. Keeping data together does not prevent two writers from overwriting each other.

A replacement can erase an edit

Asha opens her cart on her phone and laptop. Both read version 7.

The phone adds a shirt. The laptop adds a mug. Each sends a complete replacement based on the old snapshot.

The shirt disappears. Each individual replacement can be atomic, yet the combined read-modify-write sequence still loses an update.

Kartly needs compare-and-set: replace the record only if its current version equals the version you read. The check and replacement must happen in one atomic storage operation.

A cart write now proceeds as follows:

1. Read version 7 and its quantities.
2. Apply the requested edit locally.
3. Request replacement only if the stored version is still 7.
4. On success, save version 8.
5. On conflict, reload and decide whether the edit can be applied again.

This is the conditional-update reasoning from Isolation levels and locking, applied to a whole value.

Redis offers one implementation using WATCH: if a watched key changes before EXEC, the transaction aborts instead of applying its queued writes.^{2TransactionsRedis, Redis Docs}

The following examples implement the required semantics locally. They belong inside the cart storage component in the diagram. They are teaching models, not persistent databases.

from threading import Lock

class CartStore:
    def __init__(self) -> None:
        self._rows: dict[str, tuple[int, dict[str, int]]] = {}
        self._lock = Lock()

    def read(self, key: str) -> tuple[int, dict[str, int]]:
        with self._lock:
            version, items = self._rows.get(key, (0, {}))
            return version, items.copy()

    def replace(
        self,
        key: str,
        expected: int,
        items: dict[str, int],
    ) -> int | None:
        with self._lock:
            version, _ = self._rows.get(key, (0, {}))
            if version != expected:
                return None
            next_version = version + 1
            self._rows[key] = (next_version, items.copy())
            return next_version

type Items = Record<string, number>;
type Cart = { version: number; items: Items };

class CartStore {
  private readonly rows = new Map<string, Cart>();

  read(key: string): Cart {
    const row = this.rows.get(key) ?? { version: 0, items: {} };
    return { version: row.version, items: { ...row.items } };
  }

  replace(
    key: string,
    expected: number,
    items: Items,
  ): number | null {
    const current = this.rows.get(key);
    const version = current?.version ?? 0;
    if (version !== expected) return null;
    const nextVersion = version + 1;
    this.rows.set(key, {
      version: nextVersion,
      items: { ...items },
    });
    return nextVersion;
  }
}

Python’s lock protects the check and replacement together. The TypeScript method performs both synchronously in one JavaScript execution context, without an asynchronous gap.

Copies prevent callers from changing stored quantities outside replace. Neither example coordinates separate processes or survives a restart.

In production, require equivalent behavior from storage. A service-side lock on one server cannot protect writes arriving through another server.

Conditional writes also do not solve every retry. If the write succeeds but its reply disappears, a timeout leaves the outcome unknown. Reload before deciding what to do. Repeating “set quantity to 3” differs from repeating “add 1”.

The record model tells you where an atomic change could fit. You must still choose the operation and its retry behavior.

Size the value before scaling

For this lesson’s capacity example, assume a typical serialized cart occupies 4 KB. Assume 10,000 cart replacements arrive each second.

These are decimal units and scenario estimates, not database benchmarks. A field-update API can reduce request payload. Its physical storage work depends on the engine; do not assume it rewrites only those bytes.

Bound record size before adding infrastructure. Then measure whether bytes, conflicts or storage latency dominate.

During a festival sale, a popular product can receive concentrated catalog reads. Choosing document storage does not distribute one product’s popularity. Changing the cart’s key format does not fix that catalog bottleneck.

Monitor the behavior users experience:

Never translate a storage timeout into “cart not found”. That would show an empty basket even though the customer’s choices may still be saved.

Common mistakes

Choosing by JSON alone. JSON describes a representation. It does not promise indexed filtering, conditional writes or durability.

Calling flexible records schema-free. Kartly still needs rules for quantities, currency and attribute types. Validate writes and plan how readers handle older records.

Adding every possible index. Start with actual queries. Otherwise, seller updates pay to maintain access paths nobody uses.

Keeping authoritative stock inside the cart. A cart expresses customer intent. It does not reserve inventory or prove availability.

Assuming “transaction” means identical behavior everywhere. Redis transactions do not roll back successful commands when another queued command fails during execution.^{2TransactionsRedis, Redis Docs} Read the exact guarantees rather than borrowing expectations from another database.

Going deeper

Where this shows up

• Design: a fast product catalog page: product lookup and filtered lists need distinct access paths.
• Design: an e-commerce checkout: saved cart contents must be checked against current price and inventory.

The next lesson, Columnar and wide-column databases compared, asks what changes when reads group data by columns or partitioned rows.

Check your understanding

Summary