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. R-07848-59274:[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. R-13703-05723:[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 ***