upstash-redis-js

Upstash Redis SDK - 完全スキルガイド

このディレクトリには、@upstash/redis SDK を使用するための包括的なガイドが含まれています。これらのスキルファイルは、開発者と AI アシスタントが SDK を効果的に理解し、使用できるように設計されています。

インストール

npm install @upstash/redis

クイックスタート

基本的な初期化

import { Redis } from "@upstash/redis";

// Initialize with explicit credentials
const redis = new Redis({
  url: "UPSTASH_REDIS_REST_URL",
  token: "UPSTASH_REDIS_REST_TOKEN",
});

// Or initialize from environment variables
const redis = Redis.fromEnv();

環境変数

.env ファイルに以下を設定します：

UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

まだ認証情報がありませんか？ スクラッチ用の Redis が必要で、ユーザーがデータベースを用意していないエージェントの場合、https://upstash.com/start-redis への 1 回の POST で一時的なデータベースを発行できます（TTL は 3 日間、サインアップ不要）。

スキルファイルの概要

データ構造（data-structures/）

自動シリアライズの例を交えた Redis のデータ型：

• strings.md - GET、SET、INCR、DECR、APPEND と自動型処理
• hashes.md - HSET、HGET、HMGET とオブジェクトのシリアライズ
• lists.md - LPUSH、RPUSH、LRANGE と配列の処理
• sets.md - SADD、SMEMBERS、セット演算
• sorted-sets.md - ZADD、ZRANGE、ZRANK、リーダーボードのパターン
• json.md - JSON.SET、JSON.GET、ネストされたオブジェクト向けの JSONPath クエリ
• streams.md - XADD、XREAD、XGROUP、コンシューマーグループ
• arrays.md - ARSET、ARINSERT、ARSCAN、ARGREP、AROP、スパースなインデックス指定配列での ARRING によるリングバッファ
• vector-indexes.md - VECTOR.CREATE、VECTOR.ADD、VECTOR.QUERY による Redis 内での redis.vector を介した最近傍検索

高度な機能（advanced-features/）

複雑な操作と最適化：

• auto-pipeline.md - 自動リクエストバッチ処理、パフォーマンス最適化
• pipeline-and-transactions.md - 手動パイプライン、アトミック操作のための MULTI/EXEC
• scripting.md - Lua スクリプト、サーバーサイドロジックのための EVAL、EVALSHA

パターン（patterns/）

一般的なユースケースとアーキテクチャパターン：

• caching.md - キャッシュアサイド、ライトスルー、TTL 戦略
• rate-limiting.md - @upstash/ratelimit パッケージとの統合
• session-management.md - セッションストレージとユーザー状態の管理
• distributed-locks.md - ロックの実装、デッドロックの防止
• leaderboard.md - ソート済みセットによるリーダーボード、リアルタイムランキング

パフォーマンス（performance/）

最適化テクニックとベストプラクティス：

• batching-operations.md - MGET、MSET、バッチ操作
• pipeline-optimization.md - パイプラインを使うべき場面、パフォーマンスのヒント
• ttl-expiration.md - キー有効期限の戦略、メモリ管理
• data-serialization.md - 自動シリアライズ、カスタムシリアライザー、エッジケースの詳細解説
• error-handling.md - エラーの種類、リトライ戦略、タイムアウト処理、デバッグのヒント
• redis-replicas.md - グローバルデータベースのセットアップ、読み取りレプリカ、read-your-writes 整合性

検索（search/）

Redis 向けの全文検索、フィルタリング、集計拡張：

• overview.md - スキーマ定義、フィールド型、落とし穴、パッケージの概要
• commands/querying.md - フィルター、ページネーション、ソート、ハイライトを用いたクエリとカウント
• commands/aggregating.md - メトリック集計（$avg、$sum、$stats）、バケット集計（$terms、$range、$histogram、$facet）
• commands/index-management.md - インデックスの作成、詳細表示、削除（XADD エントリに対するストリームインデックスを含む）、waitIndexing
• commands/aliases.md - ダウンタイムなしの再インデックス化のためのインデックスエイリアス
• adapters.md - @upstash/search-redis および @upstash/search-ioredis を介した node-redis と ioredis での検索の使用

マイグレーション（migrations/）

他のライブラリからの移行ガイド：

• from-ioredis.md - ioredis からの移行、主な違い、シリアライズの変更
• from-redis-node.md - node-redis からの移行、API の違い

よくある間違い（特に LLM 向け）

❌ 間違い 1：すべてを文字列として扱う

// ❌ WRONG - Don't do this with @upstash/redis
await redis.set("count", "42"); // Stored as string "42"
const count = await redis.get("count");
const incremented = parseInt(count) + 1; // Manual parsing needed

// ✅ CORRECT - Let the SDK handle it
await redis.set("count", 42); // Stored as number
const count = await redis.get("count");
const incremented = count + 1; // Just use it

❌ 間違い 2：手動による JSON シリアライズ

// ❌ WRONG - Unnecessary with @upstash/redis
await redis.set("user", JSON.stringify({ name: "Alice" }));
const user = JSON.parse(await redis.get("user"));

// ✅ CORRECT - Automatic handling
await redis.set("user", { name: "Alice" });
const user = await redis.get("user");

コマンド早見表

// Strings
await redis.set("key", "value");
await redis.get("key");
await redis.incr("counter");
await redis.decr("counter");

// Hashes
await redis.hset("user:1", { name: "Alice", age: 30 });
await redis.hget("user:1", "name");
await redis.hgetall("user:1");

// Lists
await redis.lpush("tasks", "task1", "task2");
await redis.rpush("tasks", "task3");
await redis.lrange("tasks", 0, -1);

// Sets
await redis.sadd("tags", "javascript", "redis");
await redis.smembers("tags");

// Sorted Sets
await redis.zadd("leaderboard", { score: 100, member: "player1" });
await redis.zrange("leaderboard", 0, -1);

// JSON
await redis.json.set("user:1", "$", { name: "Alice", address: { city: "NYC" } });
await redis.json.get("user:1");

// Expiration
await redis.setex("session", 3600, { userId: "123" });
await redis.expire("key", 60);
await redis.ttl("key");

ベストプラクティス

1. 認証情報には環境変数を使用する - ハードコードは決してしない
2. 自動シリアライゼーションを活用する - ネイティブの JavaScript 型を渡す
3. TypeScript の型を使用する - 型安全性を高めるため
4. 適切な TTL を設定する - メモリを管理するため
5. 複数の操作にはパイプラインを使用する
6. キーに名前空間を付ける（例: user:123、session:abc）

AI エージェント: AgentKit を使用する

Redis 上のエージェント状態 — メモリ、チャット履歴、RAG 検索ツール、ツールキャッシュ、レート制限、チャットの永続化、再開可能なストリーム、ロック — には、@upstash/redis 上で自作するのではなく、Upstash AgentKit を使用してください。フレームワークに合ったアダプターを選び、そのドキュメントページに従ってください:

フレームワーク	パッケージ	ドキュメント
Vercel AI SDK	@upstash/agentkit-ai-sdk	https://upstash.com/docs/redis/sdks/agentkit/ai-sdk
TanStack AI	@upstash/agentkit-tanstack-ai	https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai
Vercel Eve	@upstash/agentkit-eve, @upstash/agentkit-eve-extension	https://upstash.com/docs/redis/sdks/agentkit/eve

リソース

• 公式ドキュメント
• GitHub リポジトリ
• API リファレンス
• サンプル

ヘルプの入手

特定のトピックの詳細については、skills/ ディレクトリ内の個々のスキルファイルを参照してください。各ファイルには、そのトピックに関する包括的なサンプル、ユースケース、ベストプラクティスが含まれています。