キーと値のペアを読む

特定のキーの値を取得するには、Worker コードにバインドした任意の KV 名前空間に対して、KV バインディングの get() メソッドを呼び出します。

// Read individual key
env.NAMESPACE.get(key);

// Read multiple keys
env.NAMESPACE.get(keys);

# Read individual key
self.env.NAMESPACE.get(key)

# Read multiple keys
self.env.NAMESPACE.get(keys)

get() メソッドは Promise を返します。値を取得するには await してください。

キーを文字列で 1 つ指定すると、Promise は単一の応答を返します。キーが見つからない場合、Promise はリテラル値 null で解決します。

キーの配列を指定することもできます。戻り値は、見つかったキーと値のペアの Map です。見つからなかったキーの値は null です。

export default {
	async fetch(request, env, ctx) {
		try {
			// Read single key, returns value or null
			const value = await env.NAMESPACE.get("first-key");

			// Read multiple keys, returns Map of values
			const values = await env.NAMESPACE.get(["first-key", "second-key"]);

			// Read single key with metadata, returns value or null
			const valueWithMetadata = await env.NAMESPACE.getWithMetadata("first-key");

			// Read multiple keys with metadata, returns Map of values
			const valuesWithMetadata = await env.NAMESPACE.getWithMetadata(["first-key", "second-key"]);

			return new Response({
				value: value,
				values: Object.fromEntries(values),
				valueWithMetadata: valueWithMetadata,
				valuesWithMetadata: Object.fromEntries(valuesWithMetadata)
			});
		} catch (e) {
			return new Response(e.message, { status: 500 });
		}
	},
};

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        try:
            # Read single key, returns value or None
            value = await self.env.NAMESPACE.get("first-key")

            # Read multiple keys, returns dict of values
            values = await self.env.NAMESPACE.get(["first-key", "second-key"])

            # Read single key with metadata
            value_with_metadata = await self.env.NAMESPACE.getWithMetadata("first-key")

            # Read multiple keys with metadata
            values_with_metadata = await self.env.NAMESPACE.getWithMetadata(["first-key", "second-key"])

            return Response.json({
                "value": value,
                "values": values,
                "valueWithMetadata": value_with_metadata,
                "valuesWithMetadata": values_with_metadata,
            })
        except Exception as e:
            return Response(str(e), status=500)

リファレンス

KV からの読み取りには、次のメソッドを使います。

get()
getWithMetadata()

`get()` メソッド

get() メソッドで、単一の値を取得します。複数キーを渡した場合は複数の値を取得します。

単一キーは get(key: string) で読みます
複数キーは get(keys: string[]) で読みます

単一キーを `get(key: string)` で取得する

単一キーの値を取得するには、Worker コードにバインドした任意の KV 名前空間で get() メソッドを呼び出します。

env.NAMESPACE.get(key, type?);
// OR
env.NAMESPACE.get(key, options?);

self.env.NAMESPACE.get(key, type)
# OR
self.env.NAMESPACE.get(key, options)

パラメーター

key: string
- KV ペアのキーです。
type: "text" | "json" | "arrayBuffer" | "stream"
- 省略可能です。返す値の型です。デフォルトは text です。
options: { cacheTtl?: number, type?: "text" | "json" | "arrayBuffer" | "stream" }
- 省略可能です。省略可能な cacheTtl と type プロパティを含むオブジェクトです。cacheTtl は、アクセスしたグローバルネットワーク拠点で KV 結果をキャッシュする秒数です（最小: 30）。type は返す値の型です。

レスポンス

response: Promise<string | Object | ArrayBuffer | ReadableStream | null>
- リクエストした KV ペアの値です。レスポンスの型は、get() に渡した type パラメーターによって次のように変わります。
- text: string（デフォルト）。
- json: JSON 文字列からデコードしたオブジェクト。
- arrayBuffer: ArrayBuffer ↗ のインスタンス。
- stream: ReadableStream ↗。

複数キーを `get(keys: string[])` で取得する

複数キーの値を取得するには、Worker コードにバインドした任意の KV 名前空間で get() メソッドを呼び出します。

env.NAMESPACE.get(keys, type?);
// OR
env.NAMESPACE.get(keys, options?);

self.env.NAMESPACE.get(keys, type)
# OR
self.env.NAMESPACE.get(keys, options)

パラメーター

keys: string[]
- KV ペアのキーです。最大: 100 キー
type: "text" | "json"
- 省略可能です。返す値の型です。デフォルトは text です。
options: { cacheTtl?: number, type?: "text" | "json" }
- 省略可能です。省略可能な cacheTtl と type プロパティを含むオブジェクトです。cacheTtl は、アクセスしたグローバルネットワーク拠点で KV 結果をキャッシュする秒数です（最小: 30）。type は返す値の型です。

レスポンス

response: Promise<Map<string, string | Object | null>>
- リクエストした KV ペアの値です。キーが見つからない場合、そのキーには null が返ります。レスポンスの型は、get() に渡した type パラメーターによって次のように変わります。
  - text: string（デフォルト）。
  - json: JSON 文字列からデコードしたオブジェクト。

レスポンスサイズの上限は 25 MB です。これを超えると 413 Error のエラーメッセージで失敗します。

`getWithMetadata()` メソッド

getWithMetadata() メソッドで、単一の値とそのメタデータを取得します。複数キーを渡した場合は、各値とメタデータを取得します。

単一キーは getWithMetadata(key: string) で読みます
複数キーは getWithMetadata(keys: string[]) で読みます

単一キーを `getWithMetadata(key: string)` で取得する

特定のキーの値とメタデータを取得するには、Worker コードにバインドした任意の KV 名前空間で getWithMetadata() メソッドを呼び出します。

env.NAMESPACE.getWithMetadata(key, type?);
// OR
env.NAMESPACE.getWithMetadata(key, options?);

self.env.NAMESPACE.getWithMetadata(key, type)
# OR
self.env.NAMESPACE.getWithMetadata(key, options)

メタデータは、各 KV エントリに付けるシリアライズ可能な値です。

パラメーター

key: string
- KV ペアのキーです。
type: "text" | "json" | "arrayBuffer" | "stream"
- 省略可能です。返す値の型です。デフォルトは text です。
options: { cacheTtl?: number, type?: "text" | "json" | "arrayBuffer" | "stream" }
- 省略可能です。省略可能な cacheTtl と type プロパティを含むオブジェクトです。cacheTtl は、アクセスしたグローバルネットワーク拠点で KV 結果をキャッシュする秒数です（最小: 30）。type は返す値の型です。

レスポンス

response: Promise<{ value: string | Object | ArrayBuffer | ReadableStream | null, metadata: string | null }>
- リクエストした KV ペアの値とメタデータを含むオブジェクトです。value 属性の型は、getWithMetadata() に渡した type パラメーターによって次のように変わります。
  - text: string（デフォルト）。
  - json: JSON 文字列からデコードしたオブジェクト。
  - arrayBuffer: ArrayBuffer ↗ のインスタンス。
  - stream: ReadableStream ↗。

リクエストしたキーと値のペアにメタデータがない場合、metadata には null が返ります。

複数キーを `getWithMetadata(keys: string[])` で取得する

複数キーの値とメタデータを取得するには、Worker コードにバインドした任意の KV 名前空間で getWithMetadata() メソッドを呼び出します。

env.NAMESPACE.getWithMetadata(keys, type?);
// OR
env.NAMESPACE.getWithMetadata(keys, options?);

self.env.NAMESPACE.getWithMetadata(keys, type)
# OR
self.env.NAMESPACE.getWithMetadata(keys, options)

パラメーター

keys: string[]
- KV ペアのキーです。最大: 100 キー
type: "text" | "json"
- 省略可能です。返す値の型です。デフォルトは text です。
options: { cacheTtl?: number, type?: "text" | "json" }
- 省略可能です。省略可能な cacheTtl と type プロパティを含むオブジェクトです。cacheTtl は、アクセスしたグローバルネットワーク拠点で KV 結果をキャッシュする秒数です（最小: 30）。type は返す値の型です。

レスポンス

response: Promise<Map<string, { value: string | Object | null, metadata: string | Object | null }>
- リクエストした KV ペアの値とメタデータを含むオブジェクトです。value 属性の型は、getWithMetadata() に渡した type パラメーターによって次のように変わります。
  - text: string（デフォルト）。
  - json: JSON 文字列からデコードしたオブジェクト。
- metadata の型は保存内容に依存し、文字列またはオブジェクトです。

リクエストしたキーと値のペアにメタデータがない場合、metadata には null が返ります。

レスポンスサイズの上限は 25 MB です。これを超えると 413 Error のエラーメッセージで失敗します。

ガイダンス

type パラメーター

単純な値では、デフォルトの text 型を使い、値を string として受け取ります。便利な json 型もあり、JSON 値をオブジェクトに変換してから返します。大きな値では stream を指定して ReadableStream をリクエストします。バイナリ値では arrayBuffer を指定して ArrayBuffer をリクエストします。

大きな値では、type の選択がレイテンシと CPU 使用量に目に見えて影響します。参考として、速い順は stream、arrayBuffer、text、json です。

cacheTtl パラメーター

cacheTtl は、アクセスしたグローバルネットワーク拠点で KV 結果をキャッシュする秒数を決めるパラメーターです。

秒数を指定すると、比較的まれに読むキーのコールドリードレイテンシを下げられます。データが書き込み 1 回、または書き込みがまれな場合に cacheTtl は有効です。

データ更新が多く、書き込み直後に更新を見たい場合は、cacheTtl は推奨しません。ほかのグローバルネットワーク拠点からの書き込みは、キャッシュ値が期限切れになるまで見えません。

cacheTtl パラメーターは 30 以上の整数である必要があります。デフォルトは 60 です。cacheTtl の最大値は Number.MAX_SAFE_INTEGER ↗ です。

あるリージョンで特定の cacheTtl を使ってキーを読むと、その cacheTtl が終わるか、キャッシュから削除されるまで、そのリージョンにキャッシュされ続けます。これは、KV 組み込みキャッシュ層のリージョン層と中央層に影響します。Workers KV へ書き込むと、KV 内部のリージョン層と中央層のキャッシュは、新しく書き込まれた結果で再検証されます。

一括リクエストで Worker 呼び出しあたりのキー数を増やす

Workers は、1 回の呼び出しあたり外部サービスへの操作が 1,000 回までに制限されています。Workers KV にも適用され、Workers KV の制限に記載されています。

1 回の操作で 1,000 を超えるキーを読む場合は、一括読み取りで複数キーを 1 回の操作として読めます。これらは 1,000 回制限に対して 1 回の操作として数えます。

キーをまとめてカーディナリティを下げる

関連するキーと値のペアに、ホットキーとコールドキーが混在している場合は、まとめることを検討してください。コールドキーをホットキーとまとめると、コールドキーもホットキーと一緒にキャッシュされ、個別キーとしてキャッシュされない場合より速く読めます。

「スーパー」KV エントリにまとめる

まとめる手法のひとつは、すべてのキーと値を 1 つのスーパーキーと値のオブジェクトに含めることです。次の例を参照してください。

key1: value1
key2: value2
key3: value3

これは次のようになります。

coalesced: {
  key1: value1,
  key2: value2,
  key3: value3,
}

値をまとめると、アクセスの多いキーのパターンにより、アクセスの少ないキーもキャッシュ上で温かく保たれます。

値を独立して更新する必要がない場合に向いています。独立して更新すると、競合状態が起きることがあります。

メリット: アクセス頻度の低いキーがキャッシュに残ります。
デメリット: 結果の値のサイズが大きくなり、Worker のメモリ上限を超えることがあります。値を安全に更新するには、何らかのロック機構が必要です。

KV へのその他のアクセス方法

Wrangler のコマンドラインからキーと値のペアを読むことも、REST API から読むこともできます。

キーと値のペアを読む

リファレンス

get() メソッド

単一キーを get(key: string) で取得する

パラメーター

レスポンス

複数キーを get(keys: string[]) で取得する

パラメーター

レスポンス

getWithMetadata() メソッド

単一キーを getWithMetadata(key: string) で取得する

パラメーター

レスポンス

複数キーを getWithMetadata(keys: string[]) で取得する

パラメーター

レスポンス

ガイダンス

type パラメーター

cacheTtl パラメーター

一括リクエストで Worker 呼び出しあたりのキー数を増やす

キーをまとめてカーディナリティを下げる

「スーパー」KV エントリにまとめる

KV へのその他のアクセス方法

`get()` メソッド

単一キーを `get(key: string)` で取得する

複数キーを `get(keys: string[])` で取得する

`getWithMetadata()` メソッド

単一キーを `getWithMetadata(key: string)` で取得する

複数キーを `getWithMetadata(keys: string[])` で取得する