第2章 EXPLAIN QUERY PLAN 分析查询计划

2.1 查询计划核心原理

SQLite 查询优化器在执行 SQL 语句前会生成一份查询计划，描述数据访问的具体路径。通过 EXPLAIN QUERY PLAN 可以查看该计划，从而判断查询是否有效利用了索引。

SQLite 的扫描方式分为以下三种：

2.2 在 Room 中获取执行计划

Room 并未提供专用的 EXPLAIN QUERY PLAN API，但可以通过 RoomDatabase.openHelper 获取 SupportSQLiteDatabase 直接执行原生 SQL。

标准执行方式如下：

val db = roomDatabase.openHelper.writableDatabase
val cursor = db.rawQuery(
    "EXPLAIN QUERY PLAN SELECT * FROM users WHERE age > ?",
    arrayOf("30")
)
cursor.use { c ->
    while (c.moveToNext()) {
        val id = c.getInt(0)        // 操作编号
        val parent = c.getInt(1)    // 父操作编号
        val detail = c.getString(3) // 详细信息（SCAN / SEARCH）
        println("id=$id parent=$parent detail=$detail")
    }
}

2.3 识别全表扫描与索引扫描

EXPLAIN QUERY PLAN 输出的 detail 列中，扫描方式的关键词决定了查询性能：

• 全表扫描：SCAN TABLE 表名 —— 表示逐行扫描整张表，无索引可用。
• 索引扫描：SEARCH TABLE 表名 USING INDEX 索引名 —— 通过索引定位行，通常伴随 WHERE 条件。
• 覆盖索引扫描：SEARCH TABLE 表名 USING INDEX 索引名 (条件) 且查询列均在索引中，无需回表。

典型输出对比：

-- 无索引时（全表扫描）
0|0|0|SCAN TABLE users

-- 有 age 索引时（索引扫描）
0|0|0|SEARCH TABLE users USING INDEX idx_users_age (age>?)

-- 覆盖索引时（无需回表）
0|0|0|SEARCH TABLE users USING COVERING INDEX idx_users_age_name (age>?)

2.4 实战步骤与代码示例

步骤 1：定义实体与索引

@Entity(
    tableName = "users",
    indices = [
        Index(value = ["age"], name = "idx_users_age"),
        Index(value = ["age", "name"], name = "idx_users_age_name")
    ]
)
data class User(
    @PrimaryKey val id: Long,
    val name: String,
    val age: Int,
    val email: String
)

步骤 2：编写 DAO

@Dao
interface UserDao {
    @Query("SELECT * FROM users WHERE age > :minAge")
    suspend fun getUsersByAge(minAge: Int): List<User>

    @Query("SELECT id, name, age FROM users WHERE age > :minAge")
    suspend fun getUsersPartial(minAge: Int): List<UserPartial>
}

步骤 3：执行查询计划分析

class QueryPlanAnalyzer(private val database: RoomDatabase) {

    fun analyze(sql: String, args: Array<String>) {
        val db = database.openHelper.writableDatabase
        val cursor = db.rawQuery("EXPLAIN QUERY PLAN $sql", args)
        println("═══════════════════════════════════════")
        println("SQL: $sql")
        println("────────── 查询计划 ──────────────────")
        cursor.use { c ->
            while (c.moveToNext()) {
                val detail = c.getString(3)
                val scanType = when {
                    detail.startsWith("SCAN TABLE") -> "⚠️ 全表扫描"
                    detail.contains("USING INDEX") -> "✅ 索引扫描"
                    detail.contains("COVERING") -> "✅ 覆盖索引扫描"
                    else -> "ℹ️ 其他"
                }
                println("  [$scanType] $detail")
            }
        }
        println("═══════════════════════════════════════")
    }
}

步骤 4：调用分析并解读结果

// 在 ViewModel 或 Repository 中调用
val analyzer = QueryPlanAnalyzer(roomDatabase)

// 分析按年龄查询
analyzer.analyze("SELECT * FROM users WHERE age > ?", arrayOf("30"))

// 输出示例：
// ═══════════════════════════════════════
// SQL: SELECT * FROM users WHERE age > ?
// ────────── 查询计划 ──────────────────
//   [✅ 索引扫描] SEARCH TABLE users USING INDEX idx_users_age (age>?)
// ═══════════════════════════════════════

2.5 性能对比数据

以下测试基于 50 万条用户数据，分别执行全表扫描与索引扫描，对比关键指标：

2.6 常见错误与解决方案

2.7 通过 SQLite 命令行验证

除 Room 外，也可以直接使用 SQLite 命令行工具快速验证查询计划，适合在数据库文件上做离线分析：

-- 打开数据库文件
sqlite3 app_database.db

-- 查看当前索引
.tables
.indices users

-- 执行分析
EXPLAIN QUERY PLAN SELECT * FROM users WHERE age > 30;

-- 输出示例：
-- QUERY PLAN
-- |--SEARCH TABLE users USING INDEX idx_users_age (age>?)

-- 对比无索引时的计划（先删除索引测试）
DROP INDEX IF EXISTS idx_users_age;
EXPLAIN QUERY PLAN SELECT * FROM users WHERE age > 30;
-- QUERY PLAN
-- |--SCAN TABLE users