Prepared Statement Scan Status

*** DRAFT ***

SQLite C Interface

Prepared Statement Scan Status

int sqlite3_stmt_scanstatus(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  void *pOut                /* Result written here */
);
int sqlite3_stmt_scanstatus_v2(
  sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  int idx,                  /* Index of loop to report on */
  int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  int flags,                /* Mask of flags defined below */
  void *pOut                /* Result written here */
);

These interfaces return information about the predicted and measured performance for pStmt. Advanced applications can use this interface to compare the predicted and the measured performance and issue warnings and/or rerun ANALYZE if discrepancies are found.

Since this interface is expected to be rarely used, it is only available if SQLite is compiled using the SQLITE_ENABLE_STMT_SCANSTATUS compile-time option.

The "iScanStatusOp" parameter determines which status information to return. The "iScanStatusOp" must be one of the scanstatus options or the behavior of this interface is undefined. The requested measurement is written into a variable pointed to by the "pOut" parameter.

The "flags" parameter must be passed a mask of flags. At present only one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX is specified, then status information is available for all elements of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements that correspond to query loops (the "SCAN..." and "SEARCH..." elements of the EXPLAIN QUERY PLAN output) are available. Invoking API sqlite3_stmt_scanstatus() is equivalent to calling sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter.

Parameter "idx" identifies the specific query element to retrieve statistics for. Query elements are numbered starting from zero. A value of -1 may be to query for statistics regarding the entire query. If idx is out of range - less than -1 or greater than or equal to the total number of query elements used to implement the statement - a non-zero value is returned and the variable that pOut points to is unchanged.

See also lists of Objects, Constants, and Functions.

*** DRAFT ***