SQLite unlikely() 函数使用指南

SQLite unlikely() 函数是 SQLite 提供的内置优化器统计辅助函数。在运行时，它直接返回参数的值而不做任何转换；但在 SQL 准备阶段（Prepare Phase），它会向查询规划器发出明确信号：该条件表达式成立的概率极低。

在 SQLite 查询规划器的成本计算模型中，被 unlikely(X) 包裹的表达式被赋予仅约 6.25%（即 1/16）的为真预估概率。这使得规划器能够更好地识别高选择性过滤条件，避免优先扫描全表，或者在嵌套循环关联（Nested Loop Join）中合理安排内外表驱动顺序。

SQLite unlikely() 语法

这里是 SQLite unlikely() 函数的标准语法：

unlikely(expression)

参数

expression

必需的。一个待评估的测试表达式、比较条件或字段值。

返回值

SQLite unlikely() 函数原样返回参数 expression 的评估结果。

• 如果参数为布尔真（非 0 数字），返回该值。
• 如果参数为布尔假（0），返回 0。
• 如果参数为 NULL，则返回 NULL。

SQLite unlikely() 示例

以下示例演示 unlikely() 函数的用法与行为。

标量与条件计算

SELECT 
    unlikely(1 = 1) AS res_one,
    unlikely(1 = 2) AS res_zero,
    unlikely('active' = 'active') AS res_str;

输出：

res_one  res_zero  res_str
-------  --------  -------
1        0         1      

在稀疏错误状态过滤中的实战应用

在生产系统的审计日志表或任务流表中，绝大部分记录均为正常状态，仅有极少数记录为错误或异常中止状态：

CREATE TABLE audit_logs (
    log_id INTEGER PRIMARY KEY,
    module TEXT,
    is_error INTEGER,
    message TEXT
);

-- 告知优化器：is_error = 1 是极罕见的极端小概率事件
SELECT log_id, module, message
FROM audit_logs
WHERE unlikely(is_error = 1) AND module = 'PAYMENT';

输出：

log_id  module   message                 
------  -------  ------------------------
883     PAYMENT  Gateway timeout occurred

由于显式声明了 unlikely(is_error = 1)，规划器在评估查询树时代价模型会判定此分支仅会过滤出极少量数据行，从而倾向于利用此谓词作为强过滤锚点，显著减少中间临时结果集的大小。

结论

• unlikely(X) 在底层等同于调用 likelihood(X, 0.0625)。
• 它不会以任何方式篡改业务逻辑或返回的数据集内容，仅改变执行计划预估成本。
• 适合应用于排查低频状态标记（如 is_deleted = 1、has_warning = true、status = 'CRASHED'）等典型长尾稀疏数据的查询优化。