Skip to content

[KV] Clarify cacheTtl default and that KV reads are always cached - #35513

Open
chris-martinelli wants to merge 1 commit into
productionfrom
kv-cachettl-default-clarification
Open

chris-martinelli wants to merge 1 commit into
productionfrom
kv-cachettl-default-clarification

Conversation

@chris-martinelli

Copy link
Copy Markdown
Contributor

Summary

The Read key-value pairs page reads as contradictory about cacheTtl:

  • The parameter reference lists cacheTtl as optional with a minimum of 30 but no default.
  • The guidance says "cacheTtl is not recommended if your data is updated often", which suggests leaving it out avoids caching.
  • A later sentence says "60 is the default".

In fact every KV read is cached, and leaving out cacheTtl means a 60-second cache (confirmed in the Jan 30, 2026 changelog: "The default cache TTL remains unchanged at 60 seconds"). This PR makes that explicit.

Changes (src/content/docs/kv/api/read-key-value-pairs.mdx)

  • Parameter reference (all four get / getWithMetadata signatures): (minimum: 30) → (default: 60, minimum: 30).
  • Stale-reads note at the top: "up to 60 seconds (or the duration of the cacheTtl)" → "up to 60 seconds by default (or the cacheTtl you set)".
  • CacheTtl parameter section:
    • The opening now says that all read results, including negative lookups, are cached, that omitting cacheTtl means 60 seconds, and that caching cannot be turned off.
    • Adds short guidance on when to raise it (write-rarely data) and when to lower it to 30 (faster visibility, more cold reads).
    • "cacheTtl is not recommended…" → "A long cacheTtl is not recommended…", plus a pointer to Durable Objects for read-after-write needs.

No behaviour claims beyond what the existing docs and changelog already state.

State the 60-second default in the get()/getWithMetadata() parameter
reference, explain that omitting cacheTtl still caches reads, and reword
the guidance so it is clear a *long* cacheTtl is what is discouraged for
frequently updated data.
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed cc5db1b · 1 finding · incremental

👉 Fix in your agent 👈
Fix the following review findings in PR #35513 (https://github.com/cloudflare/cloudflare-docs/pull/35513).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification.
- If you disagree, explain why.
- If you need clarification before deciding, ask those questions.
- Then share your plan for which issues to tackle and in what order.

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit because the next review reads PR comments.

## Style Guide
- S-185d7c06 | src/content/docs/kv/api/read-key-value-pairs.mdx:320 | Two-item bullet list in `CacheTtl parameter` section
  The new guidance is a bulleted list with only two items (`Increase cacheTtl` / `Decrease cacheTtl`), which the style guide says to consider writing as prose.

Style Guide

  • src/content/docs/kv/api/read-key-value-pairs.mdx:320 · Two-item bullet list in CacheTtl parameter section

    The new guidance is a bulleted list with only two items (Increase cacheTtl / Decrease cacheTtl), which the style guide says to consider writing as prose.

Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@cloudflare-docs-bot

Copy link
Copy Markdown
Contributor

Review coverage

🟡 1 ownership area needs approval.

Suggested reviewers: @irvinebroque @rts-rob @vy-ton

Needs approval Eligible approvers Suggested
kv @irvinebroque, @rts-rob, @thomasgauvin, @vy-ton, @cloudflare/product-owners irvinebroque, rts-rob, vy-ton
CODEOWNERS mappings for displayed areas (1)
Pattern Owners
/src/content/docs/kv/ @irvinebroque, @rts-rob, @thomasgauvin, @vy-ton, @cloudflare/product-owners

@github-actions

Copy link
Copy Markdown
Contributor

@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://kv-cachettl-default-clarification.previews.developers.cloudflare.com (commit cc5db1b)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://75eb23c4.previews.developers.cloudflare.com cc5db1b 2026-11-20T22:26:34.615Z Visit the dashboard ↗

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant