Workers KV — グローバル key-value ストア

KV の特性 — 中央ストアとエッジキャッシュ

Workers KV は、グローバルに分散した低レイテンシの key-value ストアです。データは少数の中央データストアに保存され、アクセスされた地域の Cloudflare データセンターにキャッシュされます。この「中央保存 + エッジキャッシュ」の構造が KV のすべての性質を決めています。読み取りリクエストは次の順序で処理されます。

1. アクセス元ロケーションのローカルキャッシュを確認（ヒットすれば最速。ホットキーは典型的に 500µs〜10ms 程度で応答）
2. ミスした場合はリージョナル層のキャッシュへ
3. それでもミスなら中央層を経て中央ストアから取得（コールドリードは遅い）

一度読まれたキーはその地域にキャッシュされるため、同じ地域からの 2 回目以降の読み取りは高速です。つまり KV は読み取りが多く書き込みが少ないワークロードに最適化されています。

一方、書き込み（put / delete）は中央ストアに対して行われ、各地のキャッシュへ自動でプッシュされるわけではありません。ここから重要な性質が生まれます。

• 結果整合性（eventually consistent）: 書き込みは同じロケーションでは通常すぐ見えますが（保証はされない）、他のロケーションではキャッシュが失効するまで、最大 60 秒程度（または読み取り時の cacheTtl の長さ）古い値が見えることがあります。
• 負のキャッシュ: 「キーが存在しない」という結果もキャッシュされます。キーを新規作成した直後でも、直前にそのキーを読んで null を得ていたロケーションでは、しばらく null が返り続けます。
• 同一キーへの書き込みは 1 秒に 1 回まで: 超えると 429 Too Many Requests エラーになります。また同一キーへの同時書き込みは後勝ち（last write wins）です。

アトミック操作やトランザクション、強整合な読み書きが必要な場合、KV は適していません。その用途には Durable Objects（第 8 章）を使います。

namespace の作成と wrangler kv コマンド

KV のデータは namespace（キーと値の集合。1 つの key-value データベース）に格納されます。namespace は npx wrangler kv namespace create <BINDING_NAME> で作成します（実行例はハンズオン 5-1）。

Worker から namespace にアクセスするには、wrangler.jsonc の kv_namespaces にバインディングを宣言します。binding は Worker コード内で env.<名前> として参照する変数名（有効な JavaScript 識別子であること）、id は作成時に発行される namespace の ID です。

{
	"kv_namespaces": [
		{
			"binding": "MY_KV",
			"id": "<YOUR_NAMESPACE_ID>"
		}
	]
}

<YOUR_NAMESPACE_ID> は npx wrangler kv namespace create の出力に表示される ID に置き換えます。バインディング名と namespace 名は一致している必要はありません。TOML 派は wrangler.toml で [[kv_namespaces]] テーブルに同じ 2 キーを書きます。

wrangler の KV コマンドは 3 系統あります。主なサブコマンドを挙げます。

kv key put には --ttl（有効期間・秒）、--expiration（UNIX エポック秒）、--metadata（任意の JSON）といったオプションがあり、後述の Worker API と同じ機能を CLI から使えます。なお Wrangler 3.60.0 より前の kv:namespace のようなコロン区切り構文は非推奨です。古い記事を参考にする際は読み替えてください。

Worker からの get / put / list / delete

バインディングを宣言すると、Worker コードから 4 つのメソッドで KV を操作できます。すべて Promise を返すため await します。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// 書き込み（作成・上書き）
		await env.MY_KV.put("user:1", "enabled");

		// 読み取り（存在しないキーは null）
		const value = await env.MY_KV.get("user:1");

		// キーの列挙
		const listed = await env.MY_KV.list({ prefix: "user:" });

		// 削除（存在しないキーの削除も成功扱い）
		await env.MY_KV.delete("user:1");

		return Response.json({ value, keys: listed.keys });
	},
} satisfies ExportedHandler<{ MY_KV: KVNamespace }>;

get() は第 2 引数で値の型を指定できます。"text"（既定）、"json"（パース済みオブジェクト）、"arrayBuffer"、"stream" の 4 種で、大きな値ほど stream / arrayBuffer が高速です。またキーの配列を渡すと一括読み取りになり（最大 100 キー、戻り値は Map）、Worker 1 呼び出しあたり 1,000 回までの外部サービス操作制限に対して 1 操作としてカウントされる利点があります（一括読み取りは text / json 型のみ）。

expiration（TTL）と metadata

put() の第 3 引数で、キーの自動失効と付随データを設定できます。

// 相対指定: 今から 1 時間後に自動削除（最小 60 秒）
await env.MY_KV.put("session:abc", token, { expirationTtl: 3600 });

// 絶対指定: エポック秒で失効時刻を指定（例: 2027-01-01 00:00 UTC）
await env.MY_KV.put("campaign", data, { expiration: 1798761600 });

// metadata: JSON 直列化で 1024 バイトまでの付随データ
await env.MY_KV.put("docs", "https://example.com", {
	metadata: { createdAt: "2026-08-11" },
});

// 値と metadata を同時に読む
const { value, metadata } = await env.MY_KV.getWithMetadata("docs");

失効したキーは自動削除され、以後の読み取りは存在しないキーと同じ挙動になります。失効時刻は現在から 60 秒以上先である必要があります。metadata は list() の結果にも含まれるため、「一覧表示に必要な小さいデータは metadata に持たせ、list() 後の個別 get() をなくす」という定石があります。

list() のページネーション

list() は 1 回につき最大 1,000 キー（既定値かつ上限）を、キーの UTF-8 バイト順で返します。結果オブジェクトの形は次のとおりです。

{
	"keys": [
		{ "name": "user:1", "expiration": 1798761600, "metadata": { "plan": "free" } }
	],
	"list_complete": false,
	"cursor": "6Ck1la0VxJ0djhidm1MdX2FyD"
}

続きの有無は keys が空かどうかではなく list_complete で判定します。削除・失効直後のキー（tombstone）を走査する回では、keys が空でも続きが存在することがあるためです。list_complete が false の間、cursor を次の list({ cursor }) に渡して繰り返します。prefix で絞り込んでいる場合は 2 ページ目以降も同じ prefix を渡し続けます。

ユースケースと制限・無料枠

「読み取り超高速・書き込みは伝播に時間がかかる」という特性から、向き不向きは明確です。

主要な制限値と無料枠は次のとおりです（2026-08 時点）。KV は Free プランでも使えます。

Free プランの日次上限は毎日 00:00 UTC（日本時間 9:00）にリセットされ、超過するとその種類の操作はエラーになります。ダッシュボードや wrangler からの操作も課金対象の操作数にカウントされる点、存在しないキーの読み取り（null が返るもの）も読み取り 1 回と数えられる点に注意してください。失効で削除されたキーは、以後ストレージ使用量の課金対象に含まれません。

つまずきポイント

理解度チェック

まとめと次章へ

• KV は中央ストア + エッジキャッシュ構成の結果整合な key-value ストアで、読み取り多・書き込み少のワークロードに最適化されている
• 書き込みの他ロケーションへの伝播は最大 60 秒程度。負のキャッシュ・同一キー 1 write/秒・後勝ちの性質を設計に織り込む
• wrangler kv namespace create で namespace を作り、wrangler.jsonc の kv_namespaces でバインディングして env.名前 から操作する
• Worker からは get（型指定・一括読み取り・cacheTtl）/ put（expirationTtl・metadata）/ list（prefix・cursor）/ delete の 4 メソッド
• 設定配布・セッション・キャッシュに向き、高頻度カウンタ・トランザクション・リレーショナルデータには向かない。後者は Durable Objects / D1 の領分

次章は、25 MiB の値上限を超える世界 — 画像・動画・任意のファイルを格納する、エグレス無料のオブジェクトストレージ R2 を扱います。

• How KV works — 中央ストアとキャッシュ階層、整合性の公式解説
• Read key-value pairs / Write key-value pairs — get / put の全パラメータ
• Wrangler KV commands — CLI リファレンス
• Limits / Pricing — 制限値と料金の最新情報
• Choose a data or storage product — KV と R2 / D1 / Durable Objects の使い分け