redis-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Redis Core

Redis 核心指南

Foundational guidance for modeling data in Redis. Covers data-type selection and key-name conventions — the two decisions that most directly drive memory, performance, and maintainability.

Redis数据建模的基础指南，涵盖数据类型选择和键名约定这两个对内存、性能和可维护性影响最直接的决策。

When to apply

适用场景

Caching objects, sessions, or per-user state.
Counters, leaderboards, recent-items lists, unique-membership sets.
Reviewing or refactoring Redis key names.
Deciding between a Redis Hash and a JSON document for an entity.

缓存对象、会话或每个用户的状态
计数器、排行榜、最近项列表、唯一成员集合
审查或重构Redis键名
为实体选择Redis Hash还是JSON文档

1. Choose the right data structure

1. 选择合适的数据结构

Pick the type that matches the access pattern, not just the shape of the data.

Use case	Recommended type	Why
Simple values, counters	String	Atomic `INCR` / `DECR` , `SET` / `GET`
Object with independently updated fields	Hash	Per-field reads/writes, no whole-object rewrite
Queue, recent-N items	List	O(1) push/pop at ends
Unique items, membership checks	Set	O(1) `SADD` / `SISMEMBER` / `SCARD`
Rankings, score-based ranges	Sorted Set	Score-ordered; `ZADD` / `ZRANGE` / `ZRANK`
Nested / hierarchical data	JSON	Path-level updates, nested arrays, RQE indexing
Event log, fan-out messaging	Stream	Persistent, consumer groups
Vector similarity	Vector Set	Native vector storage with HNSW

Common anti-pattern: stuffing a flat object into a serialized string. Updating one field means fetch + parse + mutate + rewrite. Use a Hash instead.

See references/choose-data-structure.md for full rationale and Python/Java examples.

选择与访问模式匹配的类型，而不只是匹配数据的形态。

适用场景	推荐类型	原因
简单值、计数器	String	原子性 `INCR` / `DECR` 、 `SET` / `GET` 操作
包含可独立更新字段的对象	Hash	支持按字段读写，无需重写整个对象
队列、最近N项列表	List	首尾处O(1)复杂度的push/pop操作
唯一项、成员资格检查	Set	O(1)复杂度的 `SADD` / `SISMEMBER` / `SCARD` 操作
排名、基于分数的范围查询	Sorted Set	按分数排序；支持 `ZADD` / `ZRANGE` / `ZRANK` 操作
嵌套/层级数据	JSON	支持路径级更新、嵌套数组、RQE索引
事件日志、扇出消息	Stream	持久化存储、支持消费者组
向量相似度计算	Vector Set	基于HNSW的原生向量存储

常见反模式： 将扁平对象塞进序列化字符串中。更新单个字段需要执行获取+解析+修改+重写的流程，建议改用Hash。

详见references/choose-data-structure.md获取完整原理及Python/Java示例。

2. Use consistent key names

2. 使用统一的键名

Use

colon-separated

segments with a stable hierarchy:

{entity}:{id}:{attribute}
user:1001:profile
user:1001:settings
order:2024:items
session:abc123
article:987:likes
game:space-invaders:leaderboard

Rules of thumb:

Lowercase, colon-separated. No spaces, no mixed casing (
```
User_1001_Profile
```
is bad).
Keep keys short but readable — keys live in memory and appear in every command.
Don't use full URLs or long strings as keys. Extract a short identifier, or use a hash digest of the URL.
Prefix for multi-tenancy (
```
tenant:42:user:7:cart
```
) so scans and ACLs can target a tenant cleanly.
Be consistent. Pick one convention per service and apply it across all keys.

See references/key-naming.md for cleanup examples and edge cases.

使用冒号分隔的分段结构，保持层级稳定：

{entity}:{id}:{attribute}
user:1001:profile
user:1001:settings
order:2024:items
session:abc123
article:987:likes
game:space-invaders:leaderboard

经验法则：

小写、冒号分隔：不使用空格，不混用大小写（
```
User_1001_Profile
```
这类写法不可取）
保持键名简短但可读：键名存储在内存中，且会出现在每一条命令里
不要用完整URL或长字符串作为键名：提取简短标识符，或使用URL的哈希摘要
多租户场景添加前缀（如
```
tenant:42:user:7:cart
```
），以便扫描和ACL能精准定位单个租户
保持一致性：每个服务选择一种命名规范，并应用于所有键名

详见references/key-naming.md获取清理示例及边缘场景说明。