column OP expr// // where OP is =, <, <=, >, or >=.)^ ^(The particular operator is // stored in aConstraint[].op using one of the // [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ // ^(The index of the column is stored in // aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the // expr on the right-hand side can be evaluated (and thus the constraint // is usable) and false if it cannot.)^ // // ^The optimizer automatically inverts terms of the form "expr OP column" // and makes other simplifications to the WHERE clause in an attempt to // get as many WHERE clause terms into the form shown above as possible. // ^The aConstraint[] array only reports WHERE clause terms that are // relevant to the particular virtual table being queried. // // ^Information about the ORDER BY clause is stored in aOrderBy[]. // ^Each term of aOrderBy records a column of the ORDER BY clause. // // The colUsed field indicates which columns of the virtual table may be // required by the current scan. Virtual table columns are numbered from // zero in the order in which they appear within the CREATE TABLE statement // passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), // the corresponding bit is set within the colUsed mask if the column may be // required by SQLite. If the table has at least 64 columns and any column // to the right of the first 63 is required, then bit 63 of colUsed is also // set. In other words, column iCol may be required if the expression // (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to // non-zero. // // The [xBestIndex] method must fill aConstraintUsage[] with information // about what parameters to pass to xFilter. ^If argvIndex>0 then // the right-hand side of the corresponding aConstraint[] is evaluated // and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit // is true, then the constraint is assumed to be fully handled by the // virtual table and might not be checked again by the byte code.)^ ^(The // aConstraintUsage[].omit flag is an optimization hint. When the omit flag // is left in its default setting of false, the constraint will always be // checked separately in byte code. If the omit flag is change to true, then // the constraint may or may not be checked in byte code. In other words, // when the omit flag is true there is no guarantee that the constraint will // not be checked again using byte code.)^ // // ^The idxNum and idxPtr values are recorded and passed into the // [xFilter] method. // ^[sqlite3_free()] is used to free idxPtr if and only if // needToFreeIdxPtr is true. // // ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in // the correct order to satisfy the ORDER BY clause so that no separate // sorting step is required. // // ^The estimatedCost value is an estimate of the cost of a particular // strategy. A cost of N indicates that the cost of the strategy is similar // to a linear scan of an SQLite table with N rows. A cost of log(N) // indicates that the expense of the operation is similar to that of a // binary search on a unique indexed field of an SQLite table with N rows. // // ^The estimatedRows value is an estimate of the number of rows that // will be returned by the strategy. // // The xBestIndex method may optionally populate the idxFlags field with a // mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag - // SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite // assumes that the strategy may visit at most one row. // // Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then // SQLite also assumes that if a call to the xUpdate() method is made as // part of the same statement to delete or update a virtual table row and the // implementation returns SQLITE_CONSTRAINT, then there is no need to rollback // any database changes. In other words, if the xUpdate() returns // SQLITE_CONSTRAINT, the database contents must be exactly as they were // before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not // set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by // the xUpdate method are automatically rolled back by SQLite. // // IMPORTANT: The estimatedRows field was added to the sqlite3_index_info // structure for SQLite [version 3.8.2] ([dateof:3.8.2]). // If a virtual table extension is // used with an SQLite version earlier than 3.8.2, the results of attempting // to read or write the estimatedRows field are undefined (but are likely // to include crashing the application). The estimatedRows field should // therefore only be used if [sqlite3_libversion_number()] returns a // value greater than or equal to 3008002. Similarly, the idxFlags field // was added for [version 3.9.0] ([dateof:3.9.0]). // It may therefore only be used if // sqlite3_libversion_number() returns a value greater than or equal to // 3009000. type sqlite3_index_constraint = struct { FiColumn int32 Fop uint8 Fusable uint8 _ [2]byte FiTermOffset int32 } /* sqlite3.c:7818:9 */ // CAPI3REF: Virtual Table Indexing Information // KEYWORDS: sqlite3_index_info // // The sqlite3_index_info structure and its substructures is used as part // of the [virtual table] interface to // pass information into and receive the reply from the [xBestIndex] // method of a [virtual table module]. The fields under **Inputs** are the // inputs to xBestIndex and are read-only. xBestIndex inserts its // results into the **Outputs** fields. // // ^(The aConstraint[] array records WHERE clause constraints of the form: // //
column OP expr// // where OP is =, <, <=, >, or >=.)^ ^(The particular operator is // stored in aConstraint[].op using one of the // [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ // ^(The index of the column is stored in // aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the // expr on the right-hand side can be evaluated (and thus the constraint // is usable) and false if it cannot.)^ // // ^The optimizer automatically inverts terms of the form "expr OP column" // and makes other simplifications to the WHERE clause in an attempt to // get as many WHERE clause terms into the form shown above as possible. // ^The aConstraint[] array only reports WHERE clause terms that are // relevant to the particular virtual table being queried. // // ^Information about the ORDER BY clause is stored in aOrderBy[]. // ^Each term of aOrderBy records a column of the ORDER BY clause. // // The colUsed field indicates which columns of the virtual table may be // required by the current scan. Virtual table columns are numbered from // zero in the order in which they appear within the CREATE TABLE statement // passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), // the corresponding bit is set within the colUsed mask if the column may be // required by SQLite. If the table has at least 64 columns and any column // to the right of the first 63 is required, then bit 63 of colUsed is also // set. In other words, column iCol may be required if the expression // (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to // non-zero. // // The [xBestIndex] method must fill aConstraintUsage[] with information // about what parameters to pass to xFilter. ^If argvIndex>0 then // the right-hand side of the corresponding aConstraint[] is evaluated // and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit // is true, then the constraint is assumed to be fully handled by the // virtual table and might not be checked again by the byte code.)^ ^(The // aConstraintUsage[].omit flag is an optimization hint. When the omit flag // is left in its default setting of false, the constraint will always be // checked separately in byte code. If the omit flag is change to true, then // the constraint may or may not be checked in byte code. In other words, // when the omit flag is true there is no guarantee that the constraint will // not be checked again using byte code.)^ // // ^The idxNum and idxPtr values are recorded and passed into the // [xFilter] method. // ^[sqlite3_free()] is used to free idxPtr if and only if // needToFreeIdxPtr is true. // // ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in // the correct order to satisfy the ORDER BY clause so that no separate // sorting step is required. // // ^The estimatedCost value is an estimate of the cost of a particular // strategy. A cost of N indicates that the cost of the strategy is similar // to a linear scan of an SQLite table with N rows. A cost of log(N) // indicates that the expense of the operation is similar to that of a // binary search on a unique indexed field of an SQLite table with N rows. // // ^The estimatedRows value is an estimate of the number of rows that // will be returned by the strategy. // // The xBestIndex method may optionally populate the idxFlags field with a // mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag - // SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite // assumes that the strategy may visit at most one row. // // Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then // SQLite also assumes that if a call to the xUpdate() method is made as // part of the same statement to delete or update a virtual table row and the // implementation returns SQLITE_CONSTRAINT, then there is no need to rollback // any database changes. In other words, if the xUpdate() returns // SQLITE_CONSTRAINT, the database contents must be exactly as they were // before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not // set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by // the xUpdate method are automatically rolled back by SQLite. // // IMPORTANT: The estimatedRows field was added to the sqlite3_index_info // structure for SQLite [version 3.8.2] ([dateof:3.8.2]). // If a virtual table extension is // used with an SQLite version earlier than 3.8.2, the results of attempting // to read or write the estimatedRows field are undefined (but are likely // to include crashing the application). The estimatedRows field should // therefore only be used if [sqlite3_libversion_number()] returns a // value greater than or equal to 3008002. Similarly, the idxFlags field // was added for [version 3.9.0] ([dateof:3.9.0]). // It may therefore only be used if // sqlite3_libversion_number() returns a value greater than or equal to // 3009000. type sqlite3_index_orderby = struct { FiColumn int32 Fdesc uint8 _ [3]byte } /* sqlite3.c:7818:9 */ // CAPI3REF: Virtual Table Indexing Information // KEYWORDS: sqlite3_index_info // // The sqlite3_index_info structure and its substructures is used as part // of the [virtual table] interface to // pass information into and receive the reply from the [xBestIndex] // method of a [virtual table module]. The fields under **Inputs** are the // inputs to xBestIndex and are read-only. xBestIndex inserts its // results into the **Outputs** fields. // // ^(The aConstraint[] array records WHERE clause constraints of the form: // //
column OP expr// // where OP is =, <, <=, >, or >=.)^ ^(The particular operator is // stored in aConstraint[].op using one of the // [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ // ^(The index of the column is stored in // aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the // expr on the right-hand side can be evaluated (and thus the constraint // is usable) and false if it cannot.)^ // // ^The optimizer automatically inverts terms of the form "expr OP column" // and makes other simplifications to the WHERE clause in an attempt to // get as many WHERE clause terms into the form shown above as possible. // ^The aConstraint[] array only reports WHERE clause terms that are // relevant to the particular virtual table being queried. // // ^Information about the ORDER BY clause is stored in aOrderBy[]. // ^Each term of aOrderBy records a column of the ORDER BY clause. // // The colUsed field indicates which columns of the virtual table may be // required by the current scan. Virtual table columns are numbered from // zero in the order in which they appear within the CREATE TABLE statement // passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), // the corresponding bit is set within the colUsed mask if the column may be // required by SQLite. If the table has at least 64 columns and any column // to the right of the first 63 is required, then bit 63 of colUsed is also // set. In other words, column iCol may be required if the expression // (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to // non-zero. // // The [xBestIndex] method must fill aConstraintUsage[] with information // about what parameters to pass to xFilter. ^If argvIndex>0 then // the right-hand side of the corresponding aConstraint[] is evaluated // and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit // is true, then the constraint is assumed to be fully handled by the // virtual table and might not be checked again by the byte code.)^ ^(The // aConstraintUsage[].omit flag is an optimization hint. When the omit flag // is left in its default setting of false, the constraint will always be // checked separately in byte code. If the omit flag is change to true, then // the constraint may or may not be checked in byte code. In other words, // when the omit flag is true there is no guarantee that the constraint will // not be checked again using byte code.)^ // // ^The idxNum and idxPtr values are recorded and passed into the // [xFilter] method. // ^[sqlite3_free()] is used to free idxPtr if and only if // needToFreeIdxPtr is true. // // ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in // the correct order to satisfy the ORDER BY clause so that no separate // sorting step is required. // // ^The estimatedCost value is an estimate of the cost of a particular // strategy. A cost of N indicates that the cost of the strategy is similar // to a linear scan of an SQLite table with N rows. A cost of log(N) // indicates that the expense of the operation is similar to that of a // binary search on a unique indexed field of an SQLite table with N rows. // // ^The estimatedRows value is an estimate of the number of rows that // will be returned by the strategy. // // The xBestIndex method may optionally populate the idxFlags field with a // mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag - // SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite // assumes that the strategy may visit at most one row. // // Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then // SQLite also assumes that if a call to the xUpdate() method is made as // part of the same statement to delete or update a virtual table row and the // implementation returns SQLITE_CONSTRAINT, then there is no need to rollback // any database changes. In other words, if the xUpdate() returns // SQLITE_CONSTRAINT, the database contents must be exactly as they were // before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not // set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by // the xUpdate method are automatically rolled back by SQLite. // // IMPORTANT: The estimatedRows field was added to the sqlite3_index_info // structure for SQLite [version 3.8.2] ([dateof:3.8.2]). // If a virtual table extension is // used with an SQLite version earlier than 3.8.2, the results of attempting // to read or write the estimatedRows field are undefined (but are likely // to include crashing the application). The estimatedRows field should // therefore only be used if [sqlite3_libversion_number()] returns a // value greater than or equal to 3008002. Similarly, the idxFlags field // was added for [version 3.9.0] ([dateof:3.9.0]). // It may therefore only be used if // sqlite3_libversion_number() returns a value greater than or equal to // 3009000. type sqlite3_index_constraint_usage = struct { FargvIndex int32 Fomit uint8 _ [3]byte } /* sqlite3.c:7818:9 */ // CAPI3REF: Mutex Methods Object // // An instance of this structure defines the low-level routines // used to allocate and use mutexes. // // Usually, the default mutex implementations provided by SQLite are // sufficient, however the application has the option of substituting a custom // implementation for specialized deployments or systems for which SQLite // does not provide a suitable implementation. In this case, the application // creates and populates an instance of this structure to pass // to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. // Additionally, an instance of this structure can be used as an // output variable when querying the system for the current mutex // implementation, using the [SQLITE_CONFIG_GETMUTEX] option. // // ^The xMutexInit method defined by this structure is invoked as // part of system initialization by the sqlite3_initialize() function. // ^The xMutexInit routine is called by SQLite exactly once for each // effective call to [sqlite3_initialize()]. // // ^The xMutexEnd method defined by this structure is invoked as // part of system shutdown by the sqlite3_shutdown() function. The // implementation of this method is expected to release all outstanding // resources obtained by the mutex methods implementation, especially // those obtained by the xMutexInit method. ^The xMutexEnd() // interface is invoked exactly once for each call to [sqlite3_shutdown()]. // // ^(The remaining seven methods defined by this structure (xMutexAlloc, // xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and // xMutexNotheld) implement the following interfaces (respectively): // //
| createFlag | Behavior when page is not already in cache // |
|---|---|
| 0 | Do not allocate a new page. Return NULL. // |
| 1 | Allocate a new page if it easy and convenient to do so. // Otherwise return NULL. // |
| 2 | Make every effort to allocate a new page. Only return // NULL if allocating a new page is effectively impossible. // |
| createFlag | Behavior when page is not already in cache // |
|---|---|
| 0 | Do not allocate a new page. Return NULL. // |
| 1 | Allocate a new page if it easy and convenient to do so. // Otherwise return NULL. // |
| 2 | Make every effort to allocate a new page. Only return // NULL if allocating a new page is effectively impossible. // |