SQLiteC/C++接口详细介绍sqlite3_stmt类（十三）

  返回：SQLite—系列文章目录   

上一篇：SQLiteC/C++接口详细介绍sqlite3_stmt类（十二）

下一篇： SQLite数据库文件损坏的可能几种情况

51、sqlite3_stmt_scanstatus_reset

sqlite3_stmt_scanstatus_reset 函数用于重置指定语句对象最近一次执行的 WHERE 子句中搜索的行数及扫描的页数的数据，以便进行下一次查询。

函数原型如下：

void sqlite3_stmt_scanstatus_reset(sqlite3_stmt *pStmt);

参数说明：

- pStmt：已经编译的 SQLite 语句对象。

该函数没有返回值。

举例用法：

int nLoop = 0;
int nVisit = 0;
sqlite3_stmt *stmt;
sqlite3_prepare_v2(db, "SELECT * FROM user WHERE age > ?", -1, &stmt, NULL);
sqlite3_bind_int(stmt, 1, 18);
while (sqlite3_step(stmt) == SQLITE_ROW) {
    nLoop++;
}
sqlite3_stmt_scanstatus_reset(stmt); // 重置搜索的行数和扫描的页数
while (sqlite3_step(stmt) == SQLITE_ROW) {
    nLoop++;
}
sqlite3_stmt_scanstatus(stmt, SQLITE_SCANSTAT_NLOOP, 0, &nLoop);
sqlite3_stmt_scanstatus(stmt, SQLITE_SCANSTAT_NVISIT, 0, &nVisit);
printf("搜索了 %d 行，扫描了 %d 个页\n", nLoop, nVisit);
sqlite3_finalize(stmt);

在上面的示例中，我们使用 `sqlite3_prepare_v2` 函数编译了一条 SQL 语句，并绑定了一个参数。然后使用 `sqlite3_step` 函数逐行获取查询结果，并累计 WHERE 子句搜索的行数和扫描的页数。在第一个 `while` 循环后使用 `sqlite3_stmt_scanstatus_reset` 函数，以清空搜索的行数和扫描的页数的数据。然后在第二个 `while` 循环中执行查询，再使用 `sqlite3_stmt_scanstatus` 函数获取搜索的行数和扫描的页数，并将结果打印出来。

使用这个函数可以用于评估不同查询条件下的查询效率和性能，对 SQL 语句进行调优和优化。

52、sqlite3_stmt_scanstatus_v2  

sqlite3_stmt_scanstatus_v2 函数用于返回指定的语句对象最近一次执行的 WHERE 子句中搜索的行数及扫描的页数。相对于 sqlite3_stmt_scanstatus 函数，它能额外生成一些查询性能的统计信息。

函数原型如下：

int sqlite3_stmt_scanstatus_v2(
  sqlite3_stmt* pStmt,                    /* Prepared statement to be measured */
  int idx,                                /* Index of binding to report on */
  int iScanStatusOp,                      /* Operation to measure */
  void* pOut,                             /* OUT: Write statistic here */
  int resetFlg                           /* Reset value for pOut */
);

参数说明：

- pStmt：已经编译的 SQLite 语句对象。
- idx：指定绑定参数的索引（从 1 开始），如果不需要指定则使用 0。
- iScanStatusOp：操作类型，可以是下列值中的一种：
  - `SQLITE_SCANSTAT_NLOOP`：返回 WHERE 子句搜索的行数。
  - `SQLITE_SCANSTAT_NVISIT`：返回 WHERE 子句扫描的页数。
  - `SQLITE_SCANSTAT_EST`：返回 WHERE 子句搜索的平均行数。
  - `SQLITE_SCANSTAT_SELECTID`：返回 SELECT 查询的 ID。
  - `SQLITE_SCANSTAT_EXPLAIN`：返回执行计划的文本形式。
  - `SQLITE_SCANSTAT_ALL`：同时返回上述所有统计信息。
- pOut：返回查询结果的指针。
- resetFlg：是否重置累计统计数据，1 表示重置，0 表示不重置。

返回值：

- 返回 `SQLITE_OK` 表示执行成功，否则返回其他错误码。

各种操作的返回结果的数据类型与 sqlite3_stmt_scanstatus 函数一致，其中 `SQLITE_SCANSTAT_EXPLAIN` 的返回类型为 `const char *`。

举例用法：

int nLoop = 0;
int nVisit = 0;
const char *explain = NULL;
sqlite3_stmt *stmt;
sqlite3_prepare_v2(db, "SELECT * FROM user WHERE age > ?", -1, &stmt, 0);
sqlite3_bind_int(stmt, 1, 18);
while (sqlite3_step(stmt) == SQLITE_ROW) {
    nLoop++;
}
sqlite3_stmt_scanstatus_v2(stmt, 0, SQLITE_SCANSTAT_NLOOP, &nLoop, 1);
sqlite3_stmt_scanstatus_v2(stmt, 0, SQLITE_SCANSTAT_NVISIT, &nVisit, 1);
sqlite3_stmt_scanstatus_v2(stmt, 0, SQLITE_SCANSTAT_EXPLAIN, &explain, 0);
printf("搜索了 %d 行，扫描了 %d 个页\n", nLoop, nVisit);
printf("执行计划：\n%s\n", explain);
sqlite3_finalize(stmt);

在上面的示例中，我们使用 `sqlite3_prepare_v2` 函数编译了一条 SQL 语句，并绑定了一个参数。然后使用 `sqlite3_step` 函数逐行获取查询结果，并累加 WHERE 子句搜索的行数。最后使用 `sqlite3_stmt_scanstatus_v2` 函数获取搜索的行数、扫描的页数和执行计划，并将结果打印出来。

需要注意的是，在获取 SQL 语句执行计划信息时，需要使用 `SQLITE_SCANSTAT_EXPLAIN` 操作，并将 resetFlg 参数设为 0，以保留已有的执行计划信息，否则需要先调用 sqlite3_clear_bindings 函数来释放绑定参数。

53、sqlite3_stmt_status

sqlite3_stmt_status 函数用于返回指定语句对象的执行状态信息，如 SQL 语句执行的次数、查询返回的行数、最后使用的表和索引、插入、修改和删除的行数等。

函数原型如下：

int sqlite3_stmt_status(
  sqlite3_stmt *pStmt,  /* Prepared statement to be queried */
  int op,               /* Information desired */
  int resetFlg,         /* Reset the value after returning it if true */
  int *pOut             /* Integer value to return */
);

参数说明：

- pStmt：已经编译的 SQLite 语句对象。
- op：所需字段的操作代码，可以是下列值中的一种：
  - `SQLITE_STMTSTATUS_FULLSCAN_STEP`：执行全表扫描的步骤数。
  - `SQLITE_STMTSTATUS_SORT`：排序操作的总数。
  - `SQLITE_STMTSTATUS_AUTOINDEX`：Autoindex 步骤数。
  - `SQLITE_STMTSTATUS_VM_STEP`：后续操作已执行完成的虚拟机步骤数。
  - `SQLITE_STMTSTATUS_REPREPARE`：SQL 语句重新编译的次数。
  - `SQLITE_STMTSTATUS_RUN`：语句已执行的次数。
  - `SQLITE_STMTSTATUS_MEMUSED`：语句消耗的内存总量（单位字节）。
  - `SQLITE_STMTSTATUS_ROW`：已返回的行数。
  - `SQLITE_STMTSTATUS_STMT_USED`：语句对象使用的内存总量（单位字节）。
  - `SQLITE_STMTSTATUS_STMTEXPIRED`：处于过期状态的预处理语句的数量。
- resetFlg：是否重置所需字段的值，1 表示重置，0 表示不重置。
- pOut：返回查询结果的指针。

返回值：

- 返回 `SQLITE_OK` 表示执行成功，否则返回其他错误码。

举例用法：

int nRow = 0;
int memUsed = 0;
sqlite3_stmt *stmt;
sqlite3_prepare_v2(db, "SELECT * FROM user WHERE age > ?", -1, &stmt, NULL);
sqlite3_bind_int(stmt, 1, 18);
while (sqlite3_step(stmt) == SQLITE_ROW) {
    nRow++;
}
sqlite3_stmt_status(stmt, SQLITE_STMTSTATUS_MEMUSED, 1, &memUsed);
printf("执行了 %d 次查询，返回了 %d 行，消耗了 %d 字节的内存\n", 
        sqlite3_stmt_status(stmt, SQLITE_STMTSTATUS_RUN, 0, NULL), nRow, memUsed);
sqlite3_finalize(stmt);

在上面的示例中，我们使用 `sqlite3_prepare_v2` 函数编译了一条 SQL 语句，并绑定了一个参数。然后使用 `sqlite3_step` 函数逐行获取查询结果，并累加已返回的行数。使用 `sqlite3_stmt_status` 函数获取语句对象的执行次数和消耗的内存量，并将结果打印出来。

使用这个函数可以用于监控 SQL 查询的性能表现，以实现 SQL 语句调优。

后记：

本次Stmt类的所有内容已经完成后续内容等待更新要三互的请发消息。