kevy上のRDSワークロード

MySQLやPostgreSQLの上で運用系のワークロードを回していて、それを——全部または一部——kevyへ移すことを検討している。このページはそのためのリファレンスマトリクスです。SQL面の構成要素ひとつひとつについて、kevyでは何がそれを担うのか、正確なverbは何か、そしてセマンティクスの差分は何かを示します。kevyがある構成要素を断る場合、その拒否は、手当ての代替とともに、はっきりと述べられます。対になるクックブックは、これらの行を実行可能なレシピに変えます。designing-on-kevyは、エンジンそのものの1ページの地図です。

分業

RDSでは、まずデータを書いておいて、アクセスパスはあとで決められます。クエリプランナが、どんなWHERE句からでも、クエリ時に*なんらかの*プランを作るからです。kevyはそれを反転させます。アクセスパスは書き込み時に宣言し（インデックス、集約、ビュー）、エンジンがそれをすべての書き込みと同期して維持し（構成上の派生物、ドリフトゼロ）、サービングはマイクロ秒スケールのルックアップになります。プラン探索は決して起きません。取引は明示的です。

• 手放すもの：宣言されていないパス上のアドホッククエリ。マッチするインデックスのないWHEREは、kevyでは遅いのではありません——*設計上、存在しない*のです（アクセスパスをモデル化するか、そのクエリを出さないか）。
• 得るもの：予測可能なサービング遅延（hydratedページのp99 < 1ms、index+viewフック経由の書き込みファンアウトのp99 < 200µs——フルスタックを載せた1台のサーバー上で。ゲートされたラインはdesigning-on-kevyにあります）、そして同じ耐久性設定ではRDSが追いつけない書き込み吸収力（サイジングを参照）。

PostgreSQL 18との実測比較

主張ではなく、実行したものです。200万行／854 MBのCSV、同一のharnessで両方を駆動、PGは素の設定、kevy 5.4 の 3 パス交互の中央値：

この数値は、同じものを比べていなかった一組を置き換えるものです。 5.4 までは kevy 側の読み取り形状が列をひとつも要求しておらず、対する SQL は 2〜3 列を選んでいました。さらに kevy のテーブルは、行が実際に持つ 7 列のうち 6 列しか宣言していませんでした。どちらも修正され、どちらも答えを動かしました：セカンダリインデックス参照は 212 µs 対 PostgreSQL の 126 µs として公開されていましたが、いまは 4% 以内の互角です。

向きの違う結論として読んでください。1秒の損失を許容するなら、kevyは書き込みを41倍速く吸収します——RDSの前段にキャッシュを置かせるのは、まさにこの圧力です。書き込みごとにfsyncする同条件では、PostgreSQLが2.0倍速い：PGはWALをグループコミットし、kevyはコマンド単位でfsyncします。索引参照は互角、一覧ページはPostgreSQLが1.2倍速い——B木の上のプランナは本業で強いのです。そして同じデータを保持するのに kevy は6.6倍のメモリを使います：行をプロセス内に置けばRAMを食います。データが収まらなくなったとき——11.5 GBのCSV、PostgreSQLはメモリ2 GBに制限、kevyは1 GBのティアリング予算——持ち主が変わるのはランダムアクセスの形だけです。ランダムな主キーでの参照はPG 184 µsに対しティアリングkevy 78 µs。kevyの行はディスク上にありながら、PGのバッファプールミスより速く答えます。上の索引形状は依然PGが勝ちます。しかも表全体に散る高カーディナリティ述語で測り直すと、差は縮まるどころか広がりました——索引参照で176 µs対385 µsです。I/Oの効果ではありません：kevyは全データをRAMに置いていても負けるので、コストは取得ではなくクエリ経路にあります。ティアリングは同じ12 GBを17.95 GBではなく2.95 GBのRSSで保持し、しかもその索引参照は、ディスク上にある98%の行に触れずに答えます。

この境界はバックログではなく、憲章です。クエリ言語なし、プランナなし、JOINなし、サーバーサイドのバリデーションDSLなし、トリガーなし（「法3」、designing-on-kevy）。以下はすべて、SQLの構成要素をこの固定された面の上へ写像したものです。

テーブル、行、カラム

HSET user:42 name ada email ada@example.com age 36
HGETALL user:42                # SELECT * WHERE id = 42
HGET user:42 email             # SELECT email WHERE id = 42
HMGET user:42 name age         # SELECT name, age WHERE id = 42

存在しないフィールドへのHGETはnilを返します——それがNULLのセマンティクスそのものです。そしてインデックスの仕様は、フィールドの欠落を「行を除外」として扱います（数えられ、IDX.VERIFYで可視になります）。

型システム

kevyはバイト列を格納します。型はそれが意味を持つ場所——インデックス作成時——に宣言します（TYPE i64|f64|str|vector）。宣言された型強制に失敗したフィールドを持つ行は、そのインデックスから除外され、数えられます（IDX.VERIFY / IDX.LISTのcoerce_failures）——宣言的なフェンスであって、書き込みエラーでは決してありません。

PRIMARY KEY、UNIQUE、AUTO_INCREMENT

主キー —— キーそのものです。ポイントルックアップ（WHERE pk = ?）はGET/HGETALL/HMGETです。1シャード、ハッシュプローブ1回、インデックス不要です。

AUTO_INCREMENT / シーケンス —— INCR seq:orderがidを1つ発行します。INCRBY seq:order 100はブロックを確保し、アプリのメモリから配っていけます（高スループット版）。クラッシュ時に穴が空くのは、PostgreSQLのシーケンスが与えるのと同じ契約です（クックブックのレシピ3）。

UNIQUE —— KIND uniqueはフェンスであって、ロックではありません。書き込みをブロックしません（ブロックすれば、シャードをまたぐ書き込みを直列化することになります）。重複は数えられ（IDX.VERIFYのduplicates）、EQ読み出しが複数ヒットする形で可視になります。硬い一意性のゲートが必要なら、次のいずれかを使ってください。

SET uniq:email:ada@example.com 42 NX          # atomic claim, NX = the gate
WATCH + MULTI/EXEC check-then-write           # CAS loop (cookbook recipe 4)
{hashtag} prefix + single-shard domain        # cluster mode

SELECT

セマンティクスと限界を、正直に。

• インデックス1つにつきフィールド1つ。 インデックスは、1つのプレフィックスの、宣言された1つのフィールドを覆います。複数カラムの述語は、ちょうど2つのインデックスのCOMPOSE AND|OR（キー順です——2つの値ドメインが異なるので、キー順だけが共有できる順序です）か、最大4葉までの名前付き・再利用可能な合成であるビューになります。それより広いアドホックな連言は、クエリプランナへの坂道です——断ります。残余の述語は、hydrationのあとアプリ側でフィルタしてください。
• RANGE/EQ/COMPOSE：デフォルトLIMIT 100、最大10000、カーソルページング（[next-cursor, rows]、"0"は開始または枯渇）。カーソルの契約はSCANクラスです。走査を通じて安定していた行はちょうど1回見えます。並行する書き込みは現れるかもしれないし、現れないかもしれません。グローバルスナップショットはありません——SCAN/DBSIZEと同じ包絡線です。
• 前方一致のLIKE：TYPE str KIND rangeのインデックスは辞書式のバイト順序で並ぶため、LIKE 'abc%'はRANGE 'abc' 'abc<0xff>'になります——キー空間の走査ではなく、インデックススキャンです。（SCAN 0 MATCH 'user:*'によるキー名の前方一致も存在しますが、これはキー空間全体を漸進的に歩きます——運用の雑務に使うものであり、サービングパスとして使ってはいけません。）
• MATCHはクエリトークン上のORセマンティクスで、BM25でランクづけされ、CJKのbigramが組み込まれています。LIMITは1000で頭打ち、カーソルなし、フレーズクエリなし、ブール構文なし、ハイライトなしです（text-search）。
• FIELDSは、各行を所有するシャード上で、指定されたハッシュフィールドを同じ呼び出しの中でhydrateします——「インデックススキャン + 主キー参照」という二重ホップの、ワンホップの置き換えです。これはJOINの形をしたhydrationのプリミティブでもあります（後述）。
• IDX.EXPLAINは診断専用です。 kind、state、est_rows、そしてあなたがすでに書いたクエリのプラン行を報告します——複数のプランから選ぶオプティマイザは存在しません。

Scalar functions

移行してきたクエリの SQL 式はスカラー関数の語彙に依存します。kevy はそれをエンジンではなく SQL 面でカバーします：kevy-cli sql eval（および sql ツールボックスの定数畳み込み）が PostgreSQL 準拠のセマンティクスでクライアント側で式を評価し、サービングエンジンは式に一切触れません——このページの他の場所と同じ分業です。

現在のカバレッジ（関数名は大文字小文字を区別せず、PG と同じ折りたたみ規則）：

この表を支える主張の規律：

• セマンティクスは PostgreSQL 自身の回帰コーパスから逐一転写され、CI ゲート（funcgate）で守られています：カバー済み関数が PG と異なる答えを返せばハード失敗——ゲートの誤答数はゼロでなければなりません。コーパスのカバレッジ比率は上がる一方のラチェットです（現在、サブセット畳み込み可能なプローブの ≥ 82%）。
• 表の外の関数は名前を挙げて拒否され、推測は決してしません。カバー済み関数の内部でも、基数を変えてしまう形は同様です——regexp_matches が零行または複数行を返すケースは、誤ったスカラーに潰されるのではなく拒否されます。

ORDER BY / LIMIT / OFFSET

• rangeインデックスが順序そのものです。IDX.QUERY … RANGEは、インデックス値の昇順で行を返します。ORDER BY col ASC LIMIT nは、colにrangeインデックスを宣言してLIMIT nでクエリすることに等しくなります。
• 素のインデックス面での降順は、IDX.QUERYのオプションにはありません。ビューを宣言する（VIEW.CREATE … ORDER BY idx DESC）か、書き込み時に符号を反転した（あるいは補数を取った）ソート用フィールドを保存してください。
• ORDER BY a, b（複合）：複合キーを、書き込み時に1つのインデックス対象フィールドへ符号化してください——有界な整数ならa * 1_000_000 + b、辞書式の複合ならゼロ埋めした文字列です（クックブックのレシピ8）。
• OFFSETは存在しません。 「N行読み飛ばす」は意図的に存在しません——どのエンジンにおいてもO(N)の浪費であり、深いところではアンチパターンだからです。返されたカーソルでページングしてください（ページあたり定数コスト、SCANクラスの契約のもとで位置が安定します）。プロダクトが「47ページ目へ飛ぶ」を必要とするなら、ページのアンカーを事前計算するか、UXを考え直してください。kevyはそのコストを隠しません。

GROUP BYと集約

KIND aggは、集約を書き込みパスの中で維持します——GROUP BYの反転です。RDSはクエリ時に行をスキャンしますが、kevyは各書き込みを、それが着地するそばから自分のグループへ畳み込みます。だからグループの読み出しはO(1)です。

IDX.CREATE ord_amt ON PREFIX ord: FIELD amount TYPE i64 KIND agg GROUPBY status
IDX.QUERY ord_amt GROUP paid                  → [count, sum, min, max, avg]
IDX.QUERY ord_amt GROUPS BY sum LIMIT 100     → ranked [group, count, sum, min, max]

• GROUP gはSELECT COUNT(*), SUM(v), MIN(v), MAX(v), AVG(v) WHERE group = gです。GROUPS BY count|sum|min|maxは、ランクづけされたGROUP BY … ORDER BY agg LIMIT nです（LIMITは1000以下）。
• min/maxは削除のもとでも正確なままです（グループごとの値の多重集合）。sumはf64で累積されます——金額を扱うなら精度の限界に注意してください（総額が2^53を十分下回るように補助単位のサイズを取ること）。
• HAVINGなし、集約式なし、任意の述語に対するGROUP BYなし —— （有界な）GROUPSの結果をアプリでフィルタしてください。インデックス1つにつきgroup-byフィールドは1つです。複数のグループ分けが要るなら、aggインデックスを複数宣言してください。

JOIN

kevyはJOINしません。 2つのプレフィックスをサーバーサイドで結合するverbは存在せず、これからも存在しません（法3）。置き換えは3つあり、望ましい順に挙げます。

1. 書き込み時に非正規化する。 サービングモデルの答えです。ページがorder.totalの隣にuser.nameを出すなら、注文の行を作るときにuser_nameをそこへ書き込んでください。ストレージは安いですし、書き込みフックがそのコピー上のインデックスも最新に保ちます。親側の更新のファンアウト（表示用フィールドではまれです）は、CDCコンシューマの仕事です。
2. アプリ側のhydration（2ホップ）。 外部キーは行の中に住み、インデックスが逆方向をワンホップにします。IDX.QUERY order_user EQ 42 FIELDS total statusはSELECT total, status FROM orders WHERE user_id = 42です——インデックスがキーを見つけ、同じ呼び出しの中でフィールドをhydrateします（クックブックのレシピ2）。順方向は親ごとのHMGETです——idをまとめてパイプラインしてください。
3. VIA hydrationを持つビュー。 VIEW.QUERY v FIELDS name VIA user:{key.1}は、各メンバーキーをテンプレート経由で*ターゲット*キーへ参照解決し、そこでフィールドを読みます——宣言された、再利用可能な「メンバー→親」の参照解決です（内部ファンアウト1回、クライアントの往復はゼロ）。クエリではなく参照解決なので、ターゲットに述語は付けられません。

SQLに対して失うもの：任意のN方向JOIN、遠い側のテーブルに対するJOIN時のフィルタリング、プランナが選ぶJOIN順序。得るもの：JOINがレイテンシのヒストグラムに現れることは二度とありません。

VIEW

VIEW.*は、宣言済みインデックス上の名前付きAND/OR/DIFF合成に、順序づけ用インデックスを添えたものです——SQLのビューというより、インデックス付きの*materialized*ビューに近いものです。

VIEW.CREATE live_adults QUERY '( AND user_live EQ 0 user_age RANGE 18 200 )'
    ORDER BY user_age MODE materialized TOPK 100
VIEW.QUERY live_adults LIMIT 10 [FIELDS name] [VIA …]

キラーアプリはホットリストです。「優先度順の準備完了ジョブ上位100件」をTOPK materializedビューにすれば、書き込み税はおよそ2%で、マイクロ秒で答え、恒久的に最新です——RDSが、カバリングインデックスと規律あるクエリと運とを揃えて、ようやく近似できるものです（views）。

トランザクション

kevyのトランザクションの物語はRedisのそれです（法1）。SQLへの写像はこうなります。

分離性について、正直に。kevyにMVCCはなく、分離レベルのノブもありません。1つのシャードの内側では、すべてのコマンド（そしてすべてのEVAL、MULTIバッチ、組み込みのアトミックブロック）が直列化されます——1シャード / 1スクリプトに収まるものについては、*直列化可能*な振る舞いが得られます。シャードをまたぐとグローバルスナップショットはありません。マルチキーの読み出し（MGET、IDX.QUERYのマージ）はシャード単位でアトミックであり、全体としてはSCANクラスです。ちぎれた単一コマンドを観測する読み出しはありませんし、コミットされていないMULTIバッチのdirty readもありません。ただし、別々の2つのコマンドをまたぐrepeatable readは存在しません —— それが重要な場面ではWATCH（CAS）かLua（1単位）を使ってください。

「コミット」の耐久性についてはpersistenceを参照してください。appendfsync alwaysなら、ackされた書き込みは応答の前にディスク上にあります。デフォルトのeverysecは最大1秒の窓を開けます（Redisと同じ取引です）。Store::fsync_aof()（組み込み）が、トランザクション単位のsynchronous_commitにあたる脱出口です。

制約とトリガー

サーバーサイドの制約DSLもトリガーDSLも、意図的に存在しません。サーバーサイドのロジックはLuaスクリプトだけであり、それは書き込みに*付随して*走るのではなく、書き込み*として*走ります。

セカンダリインデックスのDDL

• オンラインビルド：IDX.CREATEは即座に返り、バックグラウンドでバックフィルします（小さい行なら100万件あたりおよそ7秒。数KBのテキスト本体ならおよそ85秒/100万件）。準備できるまでクエリは-INDEXBUILDINGを返します——IDX.LISTをポーリングしてstate=readyを待ってください（migration）。データの可用性がインデックスのビルドを待つことは決してありません。
• インデックスの内容は派生状態です。スナップショットにもAOFにも決して記録されず、再起動後にバックグラウンドで再構築されます。カタログ（宣言のほう）は、データディレクトリのサイドカーに永続化されます。
• インデックスは最大64個です。MAXMEMはビルドを宣言的に上限づけます（-INDEXOVERBUDGET）。際限なく成長することはありません。
• バルクロードの鉄則：先にインポートし、あとからインデックスを宣言してください——バルク速度でバックフィルするほうが、インポートする行ごとに書き込みフックの代金を払うより速く済みます（クックブックのレシピ15）。

ページングと楽観ロックのパターン

• キーセット / カーソルページング（良いほうのOFFSET）：ページングするすべての面（IDX.QUERY RANGE/EQ/COMPOSE、VIEW.QUERY、SCAN）が[next-cursor, rows]を返します。カーソルを"0"になるまで戻し続けてください。カーソルは不透明で、1回の走査限りのものとして扱ってください。
• バージョンカラムによる楽観ロック：versionフィールドを持ち、行をWATCHし、読み、MULTI + HSET … version n+1 + EXEC。nilが返ればレースに負けたので、再試行してください（クックブックのレシピ4）。

バックアップとPITR

PITRについてのスコープ上の注意：フィードの窓はインメモリのバックログです（feed_buffer_size、シャードあたり最大1 GiB）。正確な時点への復旧に頼るなら、少なくともその窓が一巡するのと同じ頻度でスナップショットを取ってください。検証は一級市民です。PREFIX.DIGEST / kevy-cli diffが、順序にもトポロジにも依存せずに、2つのキー空間が等しいことを証明します。

レプリケーションと読み出しのスケーリング

プライマリ + N台のレプリカ、デフォルトで非同期——リードレプリカの形です。RDSとの違いはすべて整合性ラダー（availability）にあります。ラダーは、各保証にインスタンス単位ではなく呼び出し単位で値段を付けます。

フェイルオーバー：計画的な引き継ぎはFAILOVER verbです（quiesce → drain → 昇格——ゼロロス）。クラッシュフェイルオーバーは3ノードのelectクォーラムです（MTTRはおよそ5〜8秒。オフセット最良の候補が勝つので、WAITでackされた書き込みは生き残ります）。再合流してくる元プライマリの、レプリケートされなかった末尾は破棄されます（分岐した末尾は、定義上ackされていません）——MySQLの準同期で、まだ送られていないbinlogを失うのと同じ形のデータロスを、明示したものです。劣化した状態はすべて名前を持つエラー（-READONLY、-STALE、-NOREPLICAS、-QUIESCED、-MISDIRECTED）であり、ルーティングクライアントはそこから自己修復します（error-replies）。

CDC

フィードはkevyの「APIとしてのbinlog」です——DebeziumがRDSから抽出しているものを、ネイティブに提供します（cdc）。

意図的に提供しないもの：シャードをまたぐグローバル順序（キー単位の順序は、シャードのストリーム内で保証されます）、サーバーサイドのコンシューマ位置、コンシューマグループ。保持期間はインメモリのバックログです。遅れすぎると、再構築の出発点となるカーソルとともに-FEEDRESYNCが返ります。

kevyが決してやらないこと

拒否を1か所にまとめます。どれも憲章上の決定であって（designing-on-kevy、プロジェクトのスコープログ）、ロードマップの穴ではありません。

その2行目がどこで止まるか。 「決めない」は*クエリ時*の話です：あなたのクエリが自分で経路を名指すので、プランはあなたのために選ばれません。将来ひとつも足さない、という拒否ではありません。TABLE.DECLARE … AUTODECLARE nは、拒否され続けている形をエンジンが宣言済みの経路に変えることを許します——頼まない限りオフ、あなたが書いたnで上限が付き、宣言したカラムの上だけ、追加のみ、そしてIDX.LISTでautoと印が付きます（tables.md）。予測できないオプティマイザと、あなたが頼んだスキーマ変更は別のものであり、ここで拒否されるのは前者だけです。

かつてこの表にあり、そこに属さない項目がひとつ：OFFSET。 拒否として載っていましたが、エンジンはクローズつきの面（tables.md）で常に提供してきました。つまりこの表は、振る舞いではなく意図を書いていたのです。本当のところは、範囲内 30 000 行に対してLIMIT 20を返す実測（30 回のp50）です：

オフセットに対して線形で、シャードを増やすほど悪化します——どのシャードも自分のヒットのどれが全体マージを生き残るか知り得ないため、各シャードがlimit + offsetを取得しなければならず、原点はlimit件を返すために(limit + offset) × シャード数件を実体化します。このエンジンの他の軸はコアを増やすほど速くなりますが、この軸だけは速くなりません。

カーソルを使ってください。 OFFSETは存在し、拒否されておらず、そして深いOFFSETは、この表の残りが、あなたのレイテンシから締め出すために存在している当のO(N)スキップです。

サイジングと運用上の差分

すべてがRAM常駐です。 RDSがディスクからページインしてくるワーキングセットは、ここではメモリに住みます。ディスクは耐久性のログとスナップショットであって、サービングの階層ではありません。キャパシティプランニングを1行で書くと、こうです。

RAM ≈ 行数 × （平均キー長 + 平均行バイト数 + キーあたりのオーバーヘッド） + Σ インデックスごとの式 + ビューのメンバー数 × エントリサイズ ——そのうえで、 ロード済みのサンプル上でMEMORY USAGE / IDX.LISTのバイト数と突き合わせて検証すること。

サブシステムごとの式（それぞれCIで実測RSSに対してゲートされています）：rangeインデックスは概算でrows × (value_width + avg_key_len + 48)。textとANNの式はtext-search / vector-searchにあります（1M × 1024次元のベクトルでおよそ4.1 GiB）。aggはグループ数が支配的です（indexes）。ビューのメンバーは概算でorder_value_width + key_len + 48です（views）。maxmemoryとエビクションポリシーを設定するか、-OOMによる拒否を受け入れてください（書き込みは受付の時点で拒否されます。既存のデータが壊れることはありません）。

サービングの余力。 v3.18.0のリリースアリーナ（kevy対valkey 9.1、fair-fightプロトコル、5回の中央値——bench/PERF-LEDGER.md）：GET 3.00倍、SET 3.99倍、INCR 3.00倍、SADD 2.50倍、HSET 2.25倍、ZADD 1.73倍、LPUSH 1.64倍——レプリケーション/ハートビートのパイプラインを載せきったうえで、7戦7勝です。ディスクファーストのRDSに対するポイント読み出しでは、差はさらに大きくなります。ただしそこでの正直な比較は、クエリ単位のベンチマークではなく、「kevyはキャッシュ層*と*運用系クエリの両方を置き換える」というものです。

RDSに対する運用上の差分を、手短に。キー空間は1つ（スキーマもデータベースもありません——プレフィックスが名前空間です）。TTLは一級市民です（EXPIRE、フィールド単位のHEXPIRE——cronの削除ジョブが消えます）。FLUSHALLはコマンド1つで届きます（外周で守ってください）。派生状態（インデックス、ビュー、フィード）は再起動後にロードされるのではなく再構築されます（100万行あたり数秒——再起動時間に織り込んでください）。そしてエラーの面は契約の一部です——クライアントはメッセージをパースするのではなく、エラーのプレフィックスにマッチさせるべきです（error-replies）。

このページとクックブック

このページはリファレンスマトリクスです——SQLの構成要素を入れると、kevyの形が出てきて、差分が述べられます。クックブックはレシピ集です——20の実行可能なパターン（コマンドブロックはすべてCIでsmokeされています）。それぞれが、置き換えるSQLの構成要素でタグづけされ、上のマトリクスの行へ相互リンクされています。本当に移行するのですか。段階を追ったプレイブックはmigrationにあります。