.Dd January 24, 2024
.Dt SQLITE3_STMT_SCANSTATUS 3
.Os
.Sh NAME
.Nm sqlite3_stmt_scanstatus ,
.Nm sqlite3_stmt_scanstatus_v2
.Nd prepared statement scan status
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_stmt_scanstatus
.Fa "sqlite3_stmt *pStmt"
.Fa "int idx"
.Fa "int iScanStatusOp"
.Fa "void *pOut"
.Fc
.Ft int
.Fo sqlite3_stmt_scanstatus_v2
.Fa "sqlite3_stmt *pStmt"
.Fa "int idx"
.Fa "int iScanStatusOp"
.Fa "int flags"
.Fa "void *pOut"
.Fc
.Sh 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.
.Pp
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.
.Pp
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.
.Pp
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.
.Pp
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.
.Pp
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 10215.
.Bd -literal
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 */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3_stmt_scanstatus_reset 3 ,
.Xr SQLITE_SCANSTAT_NLOOP 3