/ Check-in [d97c324e]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the sqlite3_stmt_scanstatus() documentation. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: d97c324eb1d870c994911c53fbf84205f4e3e7a1
User & Date: drh 2014-11-03 18:03:00
Context
2014-11-04
12:11
Add the SQLITE_CONFIG_PCACHE_HDRSZ option for sqlite3_config(). check-in: 6eb03e62 user: drh tags: trunk
2014-11-03
18:03
Updates to the sqlite3_stmt_scanstatus() documentation. No changes to code. check-in: d97c324e user: drh tags: trunk
16:56
Add the experimental sqlite3_stmt_scanstatus() API. For comparing the number of rows actually visited by a loop with the estimate used by the query planner. check-in: ab3b0fc5 user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  7407   7407   */
  7408   7408   #define SQLITE_ROLLBACK 1
  7409   7409   /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
  7410   7410   #define SQLITE_FAIL     3
  7411   7411   /* #define SQLITE_ABORT 4  // Also an error code */
  7412   7412   #define SQLITE_REPLACE  5
  7413   7413   
  7414         -/* CAPI3REF: Prepared Statement Scan Status Opcodes
  7415         -** KEYWORDS: {scanstatus option}
         7414  +/*
         7415  +** CAPI3REF: Prepared Statement Scan Status Opcodes
         7416  +** KEYWORDS: {scanstatus options}
  7416   7417   **
  7417   7418   ** The following constants can be used for the T parameter to the
  7418   7419   ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface.  Each constant designates a
  7419   7420   ** different metric for sqlite3_stmt_scanstatus() to return.
  7420   7421   **
  7421   7422   ** <dl>
  7422         -** [[SQLITE_SCANSTAT_NLOOP]] <td>SQLITE_SCANSTAT_NLOOP</dt>
  7423         -** <dd>The [sqlite3_int64] variable pointed to by the T parameter will be set to the
         7423  +** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
         7424  +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the
  7424   7425   ** total number of times that the X-th loop has run.</dd>
  7425   7426   **
  7426         -** [[SQLITE_SCANSTAT_NVISIT]] <td>SQLITE_SCANSTAT_NVISIT</dt>
  7427         -** <dd>The [sqlite3_int64] variable pointed to by the T parameter will be set to the
         7427  +** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
         7428  +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the
  7428   7429   ** total number of rows visited by the X-th loop.</dd>
  7429   7430   **
  7430         -** [[SQLITE_SCANSTAT_EST]] <td>SQLITE_SCANSTAT_EST</dt>
  7431         -** <dd>The [sqlite3_int64] variable pointed to by the T parameter will be set to the
         7431  +** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
         7432  +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the
  7432   7433   ** query planner's estimate for the number of rows visited for each
  7433   7434   ** iteration of the X-th loop.  If the query planner's estimate was accurate,
  7434   7435   ** then this value should be approximately NVISIT/NLOOP.
  7435   7436   **
  7436         -** [[SQLITE_SCANSTAT_NAME]] <td>SQLITE_SCANSTAT_NAME</dt>
  7437         -** <dd>The "const char *" variable pointed to by the T parameter will be set to 
         7437  +** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
         7438  +** <dd>^The "const char *" variable pointed to by the T parameter will be set to 
  7438   7439   ** a zero-terminated UTF-8 string containing the name of the index or table used
  7439   7440   ** for the X-th loop.
  7440   7441   **
  7441         -** [[SQLITE_SCANSTAT_EXPLAIN]] <td>SQLITE_SCANSTAT_EXPLAIN</dt>
  7442         -** <dd>The "const char *" variable pointed to by the T parameter will be set to 
         7442  +** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
         7443  +** <dd>^The "const char *" variable pointed to by the T parameter will be set to 
  7443   7444   ** a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] description
  7444   7445   ** for the X-th loop.
  7445   7446   ** </dl>
  7446   7447   */
  7447   7448   #define SQLITE_SCANSTAT_NLOOP    0
  7448   7449   #define SQLITE_SCANSTAT_NVISIT   1
  7449   7450   #define SQLITE_SCANSTAT_EST      2
................................................................................
  7454   7455   ** CAPI3REF: Prepared Statement Scan Status
  7455   7456   **
  7456   7457   ** Return status data for a single loop within query pStmt.
  7457   7458   **
  7458   7459   ** The "iScanStatusOp" parameter determines which status information to return.
  7459   7460   ** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior of
  7460   7461   ** this interface is undefined.
  7461         -** The requested measurement is written into a variable pointed to by
         7462  +** ^The requested measurement is written into a variable pointed to by
  7462   7463   ** the "pOut" parameter.
  7463   7464   ** Parameter "idx" identifies the specific loop to retrieve statistics for.
  7464         -** Loops are numbered starting from zero. If idx is out of range - less than
         7465  +** Loops are numbered starting from zero. ^If idx is out of range - less than
  7465   7466   ** zero or greater than or equal to the total number of loops used to implement
  7466   7467   ** the statement - a non-zero value is returned and the variable that pOut
  7467   7468   ** points to is unchanged.
  7468   7469   **
  7469         -** Statistics might not be available for all loops in all statements. In cases
         7470  +** ^Statistics might not be available for all loops in all statements. ^In cases
  7470   7471   ** where there exist loops with no available statistics, this function behaves
  7471   7472   ** as if the loop did not exist - it returns non-zero and leave the variable
  7472   7473   ** that pOut points to unchanged.
  7473   7474   **
  7474   7475   ** This API is only available if the library is built with pre-processor
  7475   7476   ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
         7477  +**
         7478  +** See also: [sqlite3_stmt_scanstatus_reset()]
  7476   7479   */
  7477   7480   SQLITE_EXPERIMENTAL int sqlite3_stmt_scanstatus(
  7478   7481     sqlite3_stmt *pStmt,      /* Prepared statement for which info desired */
  7479   7482     int idx,                  /* Index of loop to report on */
  7480   7483     int iScanStatusOp,        /* Information desired.  SQLITE_SCANSTAT_* */
  7481   7484     void *pOut                /* Result written here */
  7482   7485   );     
  7483   7486   
  7484   7487   /*
  7485   7488   ** CAPI3REF: Zero Scan-Status Counters
  7486   7489   **
  7487         -** Zero all sqlite3_stmt_scanstatus() related event counters.
         7490  +** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
  7488   7491   **
  7489   7492   ** This API is only available if the library is built with pre-processor
  7490   7493   ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
  7491   7494   */
  7492   7495   SQLITE_EXPERIMENTAL void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
  7493   7496   
  7494   7497