Key-Value Store の制約と注意点

このページではCraft Key-Value Store（Craft KVS）の制約と、利用時の注意点について説明します。

制約

1 valueあたりの最大サイズ

1 valueあたりの最大サイズは、1,048,572バイト（約1MB）です。

※ 2025年10月以前からKARTE Craftをご利用いただいているプロジェクトでは、1 valueあたりの最大サイズが1KBに制限されている場合があります。

処理力の目安

Key-Value Storeには、安定して実行できる処理力の目安があります。これを超える負荷がかかると、処理の遅延だけでなく、タイムアウトやエラーの増加も起こりえます。

目安は次の通りです。

秒間処理数: 〜 3000（読み込み・書き込みなどすべての操作の合計）
- ※ 有効期限の到来によるレコードの自動削除は、この目安には含まれません

同じキーへのアクセスが集中する場合は、一時的にパフォーマンス低下することがあります。ホットスポットの発生によるパフォーマンス低下もあわせてご確認ください。

次の点にご注意ください。

これは目安であり、保証値ではありません。
急激に負荷が増えた場合は、目安内であっても一時的にエラーが増えやすくなります（徐々に負荷を増やすことを推奨します）。
KVSの目安の範囲内であっても、呼び出し元のファンクションの処理力の目安を超える場合は、ファンクション側で先に上限となります。

目安を超える規模での利用が見込まれる場合は、事前にご相談ください。利用状況に応じて、安定して処理できるよう環境を調整できる場合があります。

注意点

ホットスポットの発生によるパフォーマンス低下

keyの辞書順が近いレコード群に対して頻繁に読み取りや書き込みを行うと、ホットスポットの発生により一時的にパフォーマンス低下することがあります。

この問題は、keyに対して辞書順をばらけさせるためのprefixを付与することで軽減できる可能性があります。

// keyにホットスポット回避用のprefixを付与する実装の例

import crypto from 'crypto';

function generateHashPrefix(id) {
  const hashBase64Url = crypto.createHash('sha256').update(id).digest('base64url');
  // 辞書順を分散させるためハッシュ値の5〜12文字目を使用
  const prefix = hashBase64Url.substring(4, 12);
  return prefix;
}

function kvsKey(id) {
  const hash = generateHashPrefix(id);
  return `${hash}-${id}`;
}