1.Dd January 24, 2024 2.Dt SQLITE3_STMT_SCANSTATUS 3 3.Os 4.Sh NAME 5.Nm sqlite3_stmt_scanstatus , 6.Nm sqlite3_stmt_scanstatus_v2 7.Nd prepared statement scan status 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft int 11.Fo sqlite3_stmt_scanstatus 12.Fa "sqlite3_stmt *pStmt" 13.Fa "int idx" 14.Fa "int iScanStatusOp" 15.Fa "void *pOut" 16.Fc 17.Ft int 18.Fo sqlite3_stmt_scanstatus_v2 19.Fa "sqlite3_stmt *pStmt" 20.Fa "int idx" 21.Fa "int iScanStatusOp" 22.Fa "int flags" 23.Fa "void *pOut" 24.Fc 25.Sh DESCRIPTION 26These interfaces return information about the predicted and measured 27performance for pStmt. 28Advanced applications can use this interface to compare the predicted 29and the measured performance and issue warnings and/or rerun ANALYZE 30if discrepancies are found. 31.Pp 32Since this interface is expected to be rarely used, it is only available 33if SQLite is compiled using the SQLITE_ENABLE_STMT_SCANSTATUS 34compile-time option. 35.Pp 36The "iScanStatusOp" parameter determines which status information to 37return. 38The "iScanStatusOp" must be one of the scanstatus options 39or the behavior of this interface is undefined. 40The requested measurement is written into a variable pointed to by 41the "pOut" parameter. 42.Pp 43The "flags" parameter must be passed a mask of flags. 44At present only one flag is defined - SQLITE_SCANSTAT_COMPLEX. 45If SQLITE_SCANSTAT_COMPLEX is specified, then status information is 46available for all elements of a query plan that are reported by "EXPLAIN 47QUERY PLAN" output. 48If SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements 49that correspond to query loops (the "SCAN..." and "SEARCH..." elements 50of the EXPLAIN QUERY PLAN output) are available. 51Invoking API sqlite3_stmt_scanstatus() is equivalent to calling sqlite3_stmt_scanstatus_v2() 52with a zeroed flags parameter. 53.Pp 54Parameter "idx" identifies the specific query element to retrieve statistics 55for. 56Query elements are numbered starting from zero. 57A value of -1 may be to query for statistics regarding the entire query. 58If idx is out of range - less than -1 or greater than or equal to the 59total number of query elements used to implement the statement - a 60non-zero value is returned and the variable that pOut points to is 61unchanged. 62.Pp 63.Sh IMPLEMENTATION NOTES 64These declarations were extracted from the 65interface documentation at line 10215. 66.Bd -literal 67SQLITE_API int sqlite3_stmt_scanstatus( 68 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ 69 int idx, /* Index of loop to report on */ 70 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ 71 void *pOut /* Result written here */ 72); 73SQLITE_API int sqlite3_stmt_scanstatus_v2( 74 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ 75 int idx, /* Index of loop to report on */ 76 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ 77 int flags, /* Mask of flags defined below */ 78 void *pOut /* Result written here */ 79); 80.Ed 81.Sh SEE ALSO 82.Xr sqlite3_stmt_scanstatus_reset 3 , 83.Xr SQLITE_SCANSTAT_NLOOP 3 84