PostgreSQL GIN 索引原理、应用场景与最佳实践

值 1 → 行1, 行5, 行10
值 3 → 行1, 行2, 行7
值 5 → 行1, 行3, 行8

GIN Index Structure:
┌─────────────┬──────────────────────┐
│    Key      │    Posting List      │
├─────────────┼──────────────────────┤
│   "apple"   │  (1,2), (5,3), ...   │
│   "banana"  │  (2,1), (7,4), ...   │
│     42      │  (3,2), (9,1), ...   │
└─────────────┴──────────────────────┘

-- 数组操作
SELECT * FROM products WHERE tags @> ARRAY['electronics'];  -- 包含
SELECT * FROM products WHERE tags && ARRAY['sale', 'discount']; -- 任一匹配
-- JSONB 操作
SELECT * FROM users WHERE profile @> '{"age": 25}';  -- 包含键值对
SELECT * FROM users WHERE profile ? 'email';         -- 包含键
SELECT * FROM users WHERE profile ?| ARRAY['phone', 'email']; -- 任一键存在
-- 全文检索
SELECT * FROM articles WHERE content_tsvector @@ to_tsquery('english', 'database & performance');

-- 数组操作
SELECT * FROM products WHERE tags @> ARRAY['electronics'];  -- 包含
SELECT * FROM products WHERE tags && ARRAY['sale', 'discount']; -- 任一匹配
-- JSONB 操作
SELECT * FROM users WHERE profile @> '{"age": 25}';  -- 包含键值对
SELECT * FROM users WHERE profile ? 'email';         -- 包含键
SELECT * FROM users WHERE profile ?| ARRAY['phone', 'email']; -- 任一键存在
-- 全文检索
SELECT * FROM articles WHERE content_tsvector @@ to_tsquery('english', 'database & performance');

Insert Process with fastupdate=on:
┌─────────────┐    ┌──────────────────┐    ┌─────────────┐
│   New Data  │───▶│  Pending List    │───▶│  Main Index │
└─────────────┘    └──────────────────┘    └─────────────┘
                          ▲
                          │
                   gin_clean_pending_list()

-- 查询: SELECT * FROM table WHERE col @> ARRAY[1,2];
-- GIN 查询步骤：
-- 1. 查找值 1 的 posting list: [row1, row3, row5]
-- 2. 查找值 2 的 posting list: [row1, row2, row5]
-- 3. 取交集: [row1, row5]
-- 4. 返回结果

-- 表结构
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name TEXT,
    tags TEXT[],  -- 标签数组
    price NUMERIC
);
-- 插入测试数据
INSERT INTO products (name, tags, price) VALUES
('iPhone 15', ARRAY['electronics', 'phone', 'apple'], 999),
('MacBook Pro', ARRAY['electronics', 'laptop', 'apple'], 2499),
('Nike Air Max', ARRAY['clothing', 'shoes', 'sport'], 120);
-- 创建 GIN 索引
CREATE INDEX idx_products_tags ON products USING GIN (tags);
-- 查询包含特定标签的商品
EXPLAIN ANALYZE 
SELECT * FROM products WHERE tags @> ARRAY['electronics'];
-- Index Scan using idx_products_tags on products
-- 查询包含任一标签的商品
EXPLAIN ANALYZE 
SELECT * FROM products WHERE tags && ARRAY['phone', 'laptop'];
-- Bitmap Heap Scan with Bitmap Index Scan

-- 表结构
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT,
    profile JSONB  -- 用户配置
);
-- 插入数据
INSERT INTO users (name, profile) VALUES
('Alice', '{"age": 25, "city": "Beijing", "skills": ["Java", "Python"]}'),
('Bob', '{"age": 30, "city": "Shanghai", "skills": ["JavaScript", "React"]}');
-- 创建 GIN 索引
CREATE INDEX idx_users_profile ON users USING GIN (profile);
-- 查询年龄为25的用户
EXPLAIN ANALYZE 
SELECT * FROM users WHERE profile @> '{"age": 25}';
-- 查询具有特定技能的用户
EXPLAIN ANALYZE 
SELECT * FROM users WHERE profile->'skills' ? 'Java';
-- 创建特定路径的 GIN 索引（更高效）
CREATE INDEX idx_users_skills ON users USING GIN ((profile->'skills'));

-- 1. 针对特定 JSON 路径创建索引（比全 JSONB 索引更高效）
CREATE INDEX idx_users_email ON users USING GIN ((profile->>'email'));  -- 错误！
CREATE INDEX idx_users_email ON users USING GIN ((profile->'email'));   -- 正确
-- 2. 使用表达式索引
CREATE INDEX idx_users_age ON users USING GIN ((profile->'age'));
-- 3. 复合条件考虑部分索引
CREATE INDEX idx_active_users ON users USING GIN (profile) 
WHERE status = 'active';

-- 查看当前 GIN 参数
SHOW gin_fuzzy_search_limit;
SHOW gin_pending_list_limit;
-- 会话级调整（临时）
SET gin_pending_list_limit = '16MB';
SET gin_fuzzy_search_limit = 10000;
-- 系统级调整（postgresql.conf）
# gin_pending_list_limit = 16MB
# gin_fuzzy_search_limit = 10000

-- 手动清理待处理列表（当 fastupdate=on 时）
SELECT gin_clean_pending_list('idx_products_tags');
-- 监控 GIN 索引状态
SELECT * FROM pg_stat_user_indexes 
WHERE indexname = 'idx_products_tags';
-- 定期 REINDEX（特别是在大量更新后）
REINDEX INDEX idx_products_tags;

-- 对于写入密集型应用，考虑关闭 fastupdate
CREATE INDEX idx_write_heavy ON table USING GIN (col) WITH (fastupdate = off);
-- 对于读取密集型应用，保持 fastupdate=on（默认）
-- 但监控 pending list 大小，避免查询性能下降

-- 确保使用正确的操作符
-- ✅ 正确：profile ? 'email'
-- ❌ 错误：profile->>'email' IS NOT NULL
-- 检查索引是否创建正确
\d+ users  -- 查看索引信息
-- 强制使用索引（调试用）
SET enable_seqscan = off;

-- 方案1：批量操作后手动清理
BEGIN;
INSERT INTO table ...;  -- 批量插入
SELECT gin_clean_pending_list('index_name');
COMMIT;
-- 方案2：临时关闭 fastupdate
DROP INDEX idx_name;
CREATE INDEX idx_name ON table USING GIN (col) WITH (fastupdate = off);

-- 方案1：只索引必要字段
-- 而不是 CREATE INDEX ON table USING GIN (jsonb_col);
-- 使用 CREATE INDEX ON table USING GIN ((jsonb_col->'needed_field'));
-- 方案2：定期 REINDEX
REINDEX INDEX CONCURRENTLY idx_name;
-- 方案3：考虑分区表