diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md index 97eac5c5a13..e50a66e9262 100644 --- a/doc/api/sqlite.md +++ b/doc/api/sqlite.md @@ -1196,6 +1196,18 @@ returns an empty iterator. The prepared statement [parameters are bound][] using the values in `namedParameters` and `anonymousParameters`. See [Binding parameters][]. +### `statement.resetStats()` + + + +Resets every counter reported by [`statement.stat()`][] back to zero, except +`memused`, which reports current memory usage and cannot be reset. This +method is a wrapper around [`sqlite3_stmt_status()`][] and is useful for +measuring a specific workload without the counts accumulated by earlier +executions of the same prepared statement. + ### `statement.run([namedParameters][, ...anonymousParameters])` + +* `counter` {string} The name of the counter to read. One of: + + * `'fullscanStep'` The number of times SQLite has stepped forward in a table + as part of a full table scan. + * `'sort'` The number of sort operations that have occurred. + * `'autoindex'` The number of rows inserted into transient indices that were + created automatically to help joins run faster. + * `'vmStep'` The number of virtual machine operations executed by the + prepared statement. + * `'reprepare'` The number of times the statement has been automatically + reprepared due to schema changes or changes to bound parameters. + * `'run'` The number of execution cycles started by the prepared statement. + * `'filterMiss'` The number of times the Bloom filter returned a result that + required the join step to be processed as normal. + * `'filterHit'` The number of times a join step was bypassed because a Bloom + filter returned not-found. + * `'memused'` The approximate number of bytes of heap memory used to store + the prepared statement. + +* Returns: {number} The current value of the requested counter. + +Returns one of the runtime counters that SQLite tracks for this prepared +statement. This method is a wrapper around [`sqlite3_stmt_status()`][] and does +not reset the counter. Asserting that a statement does not perform a full table +scan (`statement.stat('fullscanStep') === 0`) is a useful check to guard +against degenerate performance. + +The `'filterMiss'` and `'filterHit'` counters require SQLite 3.38.0 or later. +Builds linked against an older SQLite with `--shared-sqlite` do not expose them, +and passing either name throws `ERR_INVALID_ARG_VALUE`. + ## Class: `SQLTagStore`