Cloudflare 20：KV ― 世界中から速く読める、キーと値の置き場

一言でいうと：世界中から速く読める、キーと値の置き場

KV は、キー（名前）と値の組を保存する、とても単純な置き場です。KV は Key-Value の頭文字です。

できることは、ほぼ次の4つだけです。

表の列も、SQL も、検索もありません。「この名前の値をください」「この名前でこの値を覚えておいて」だけです。その代わり、読み込みが世界中どこからでも速いという、1つの長所に特化しています。

KV は、読み込みがとても多く、書き込みが少ない用途のために作られています。どのくらい極端かは、後で見る無料枠の数字（読み込みは書き込みの100倍）にも表れています。次のページから、なぜ読み込みが速く、なぜ書き込みに弱いのかを、仕組みから見ていきます。

読むとき：近くの拠点が覚えていれば、その場で返る

KV の値は、大もとの中央の保管庫にしまわれています。図の上の紫の箱です（実際には何段かの層になっていますが、ここでは単純にしています）。

東京の Worker が theme を読もうとしたとします。

これは、02号で見た CDN のキャッシュとまったく同じ考え方です。よく読まれるキーほど、拠点が覚えている時間のほとんどを「その場で返す」ことに使えるので、効果が大きくなります。

世界中の拠点が、それぞれ自分の近くの利用者のために値を覚えます。東京の拠点は東京の Worker のために、サンパウロの拠点はサンパウロの Worker のために。結果として、人気のあるキーは、世界中どこからでも近くで読めるようになります。

逆に、めったに読まれないキーは、読むたびに中央まで行くことになり、それほど速くありません。KV は「同じキーが何度も読まれる」ときに真価を発揮する置き場です。

書くとき：まず中央へ。他の拠点はしばらく古い値のまま

では、値を書き換えるとどうなるでしょうか。東京の Worker が、theme を「青」から「赤」に書き換えたとします。

書き込みは、中央の保管庫に送られます。中央の値は「赤」になります。書き込んだ東京の拠点も、すぐに「赤」が見えるようになります。

問題は、他の拠点です。ロンドン・NY・サンパウロの拠点は、前に読んだ「青」を覚えたままです。拠点は「覚えている間は中央に確かめに行かない」ことで速さを出しているので、中央の値が変わったことに、すぐには気づきません。

その結果、書き換えた直後には、こういうことが起きます。

同じキーを同じ瞬間に読んでも、どの拠点で読んだかによって、違う値が返るのです。

普通のデータベースに慣れていると、これは奇妙に感じます。「書いたのに、読んだら古い値が返る」のですから。でも、これが KV の速さの代償です。拠点が毎回「中央の値は変わっていないか」を確かめていたら、結局遠くまで往復することになり、速さが失われてしまいます。

行き渡るまで、最大でおよそ60秒

では、古い値はいつまで返るのでしょうか。

各拠点が値を覚えておく時間には、限りがあります。その時間が切れると、拠点は次に読まれたときに中央へ取りに行き、新しい「赤」を覚え直します。こうして、書き込みは、最大でおよそ60秒で世界中に行き渡ります（後で見る cacheTtl を長くした場合は、その分だけ遅くなります）。

このように、「書いた直後は場所によって違う値が見えるが、いつかは必ず揃う」という性質を、結果整合性（eventual consistency）と呼びます。反対に、「書いた瞬間から、どこで読んでも新しい値が見える」性質を強い整合性と呼びます。

どちらが優れているということはありません。何を優先するかの違いです。KV は、「すぐ揃う」ことをあきらめる代わりに、「世界中で速く読める」ことを手に入れています。

設定値やフラグなら、変更が世界中に届くのに数十秒かかっても、ほとんどの場合は困りません。KV を使うかどうかは、「この値は、少しの間古くても困らないか」で判断します。

向いている用途・向いていない用途

ここまでの仕組みから、KV に向く用途と、向かない用途がはっきりします。

セッションは、「ログアウトした直後に、別の拠点ではまだログインしている扱いになる」ことがありえます。多くのサイトでは問題になりませんが、厳密さが要るなら別の置き場を検討しましょう。

向いていない側の用途には、別の答えがあります。数える・取り合うものは Durable Objects（21号）、検索・集計が要るものは D1（23号）です。

導入：名前空間を作り、Worker につなぐ

KV の入れ物は名前空間（namespace）と呼ばれます。1つの名前空間の中に、キーと値の組がたくさん入ります。用途ごとに名前空間を分けておくと、整理しやすくなります。

名前空間は、wrangler のコマンドで作れます。

$ npx wrangler kv namespace create CONFIG

実行すると、作られた名前空間の ID が表示されます。これを Worker の設定ファイルに、バインディング（18号）として書きます。

{
  "kv_namespaces": [
    { "binding": "CONFIG", "id": "<名前空間の ID>" }
  ]
}

binding に書いた名前が、コードの env に入る名前になります。この例なら env.CONFIG です。

手元で wrangler dev を使うと、KV は手元の模擬版につながります。本番の値を汚さずに試せます。本番の名前空間につないで試したいときは、そのための設定もあります。

TypeScript を使うなら、npx wrangler types を実行すると、env.CONFIG の型（KVNamespace）が自動で作られます。

使い方：get・put・delete・list

Worker のコードからは、env.CONFIG に対して、get・put・delete・list を呼びます。どれも非同期なので await を付けます。

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 読む。無ければ null
    const theme = (await env.CONFIG.get("theme")) ?? "青";

    // JSON として読む
    const flags = await env.CONFIG.get<{ newEditor: boolean }>("flags", "json");

    // 書く。expirationTtl は「この秒数が過ぎたら自動で消す」
    const id = crypto.randomUUID();
    await env.CONFIG.put(`session:${id}`, JSON.stringify({ user: "u_12" }), {
      expirationTtl: 60 * 60,
    });

    // 先頭の文字でキーの一覧を取る
    const { keys } = await env.CONFIG.list({ prefix: "session:" });

    return Response.json({ theme, flags, sessions: keys.length });
  },
};

いくつか押さえておきたい点があります。

キーの付け方には、「種類:ID」のように区切りを入れておくのがおすすめです。KV には表が無いので、キーの名前が整理の道具になります。

cacheTtl：拠点に覚えさせる時間を延ばす

KV の読み込みには、cacheTtl という指定ができます。「この値を、拠点に何秒覚えさせるか」です。

const theme = await env.CONFIG.get("theme", { cacheTtl: 3600 }); // 1時間

これまでの図で見たとおり、拠点が値を覚えている間は、中央まで行かずに速く返せます。めったに変わらない値なら、覚える時間を長くするほど、中央へ行く回数が減り、読み込みはさらに速くなります。

ただし、これは両刃の剣です。覚える時間を1時間にすると、値を書き換えたときに、他の拠点へ行き渡るのにも最大で1時間かかるようになります。「最大60秒ほどで行き渡る」という話は、既定の設定のときのものです。

cacheTtl には最小値があり、それより短くはできません。「書いたらすぐ全部の拠点に届いてほしい」という要求は、そもそも KV の設計と合わないので、その場合は Durable Objects（21号）を検討します。

使い分けの目安は、「その値が変わったとき、どのくらい古い値が見えていても許されるか」です。サイトのロゴの場所のように、1時間古くても誰も困らない値なら長く、機能フラグのように早く切り替えたい値なら既定のまま、と決めます。

料金と制限：読み込みは多く、書き込みは少なく

KV の料金は、操作の回数と保存している量で決まります。2026年9月時点の主な数字は次のとおりです。料金・上限は変わるので、必ず公式の Pricing と Limits のページで確かめてください。

Free の数字を見ると、読み込みは書き込みの100倍です。これは、KV が「たまに書き、たくさん読む」ために作られていることをそのまま表しています。Free では、上限を超えるとその種類の操作がエラーになり、次の日（UTC の0時）に回数が戻ります。

料金とは別に、仕組みから来る制限もあります。

特に「同じキーへの書き込みは1秒に1回まで」は、カウンターのような使い方ができない、もう1つの理由です。

よくある落とし穴

KV でよくつまずく点をまとめます。

1つ目の「読んで +1 して書く」は、KV に限らず、取り合い（競合） の典型的な失敗です。手元で1人で試しているときは正しく動くので、本番でアクセスが増えてから初めて気づくことが多いのが厄介なところです。

KV を選ぶときは、いつも2つを自問しましょう。「この値は、少し古くても困らないか」「同じキーを、何人もが同時に書き換えることはないか」。両方が「はい、困らない」「いいえ、ない」なら、KV は最良の選択です。

他の置き場との使い分け

Cloudflare には、データの置き場がいくつもあります。KV を他と比べると、選び方が見えてきます。

迷ったときは、次の順に考えます。

組み合わせて使うことも普通です。たとえば、画像そのものは R2 に置き、「どの画像を表示するか」という設定だけを KV に置く。記事は D1 に置き、よく読まれる記事の組み立て済みの HTML を KV にキャッシュする、といった具合です。

どれも Worker からはバインディングでつなぎ、env.名前 で呼び出します（18号）。