Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

SQLITE3_STMT_SCANSTATUS(3)                            Library Functions Manual

NAME
     sqlite3_stmt_scanstatus, sqlite3_stmt_scanstatus_v2 - prepared statement
     scan status

SYNOPSIS
     #include <sqlite3.h>

     int
     sqlite3_stmt_scanstatus(sqlite3_stmt *pStmt, int idx, int iScanStatusOp,
         void *pOut);

     int
     sqlite3_stmt_scanstatus_v2(sqlite3_stmt *pStmt, int idx,
         int iScanStatusOp, int flags, void *pOut);

DESCRIPTION
     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.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 10215.

     SQLITE_API 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 */
     );
     SQLITE_API 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 */
     );

SEE ALSO
     sqlite3_stmt_scanstatus_reset(3), SQLITE_SCANSTAT_NLOOP(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99