Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Explain the use of SQLITE_CONSTRAINT as a return value from xBestIndex. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA3-256: |
52c277f049823cb02f18e595043e035c |
User & Date: | drh 2018-11-16 14:30:33.667 |
Context
2018-11-16
| ||
14:33 | More fixes to the virtual table documentation. (check-in: 70c4eaad4d user: drh tags: trunk) | |
14:30 | Explain the use of SQLITE_CONSTRAINT as a return value from xBestIndex. (check-in: 52c277f049 user: drh tags: trunk) | |
01:45 | Fix a typo in csv.html. (check-in: ccee8fa12e user: drh tags: trunk) | |
Changes
Changes to pages/rescode.in.
︙ | ︙ | |||
276 277 278 279 280 281 282 283 284 285 286 287 288 289 | } RESCODE SQLITE_CONSTRAINT 19 { The SQLITE_CONSTRAINT error code means that an SQL constraint violation occurred while trying to process an SQL statement. Additional information about the failed constraint can be found by consulting the accompanying error message (returned via [sqlite3_errmsg()] or [sqlite3_errmsg16()]) or by looking at the [extended error code]. } RESCODE SQLITE_MISMATCH 20 { The SQLITE_MISMATCH error code indicates a datatype mismatch. <p> SQLite is normally very forgiving about mismatches between the type of a value and the declared type of the container in which that value is to be stored. For example, SQLite allows the application to store | > > > > > > | 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 | } RESCODE SQLITE_CONSTRAINT 19 { The SQLITE_CONSTRAINT error code means that an SQL constraint violation occurred while trying to process an SQL statement. Additional information about the failed constraint can be found by consulting the accompanying error message (returned via [sqlite3_errmsg()] or [sqlite3_errmsg16()]) or by looking at the [extended error code]. <p> The SQLITE_CONSTRAINT code can also be used as the return value from the [xBestIndex()] method of a [virtual table] implementation. When xBestIndex() returns SQLITE_CONSTRAINT, that indicates that the particular combination of inputs submitted to xBestIndex() cannot result in a usable query plan and should not be given further consideration. } RESCODE SQLITE_MISMATCH 20 { The SQLITE_MISMATCH error code indicates a datatype mismatch. <p> SQLite is normally very forgiving about mismatches between the type of a value and the declared type of the container in which that value is to be stored. For example, SQLite allows the application to store |
︙ | ︙ |
Changes to pages/vtab.in.
︙ | ︙ | |||
719 720 721 722 723 724 725 | [sqlite3_index_info] structure, it should make a copy. Care must be take to store the copy in a place where it will be deallocated, such as in the idxStr field with needToFreeIdxStr set to 1. <p>Note that xBestIndex will always be called before [xFilter], since the idxNum and idxStr outputs from xBestIndex are required inputs to xFilter. However, there is no guarantee that xFilter will be called | | | 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 | [sqlite3_index_info] structure, it should make a copy. Care must be take to store the copy in a place where it will be deallocated, such as in the idxStr field with needToFreeIdxStr set to 1. <p>Note that xBestIndex will always be called before [xFilter], since the idxNum and idxStr outputs from xBestIndex are required inputs to xFilter. However, there is no guarantee that xFilter will be called following a successful xBestIndex. <p>The xBestIndex method is required for every virtual table implementation. <h3>Inputs</h3> <p>The main thing that the SQLite core is trying to communicate to the virtual table is the constraints that are available to limit |
︙ | ︙ | |||
766 767 768 769 770 771 772 | <codeblock> x >= 10 x <= 100 y < 999 </codeblock> | | | 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 | <codeblock> x >= 10 x <= 100 y < 999 </codeblock> <p>For each such constraint, the aConstraint[].iColumn field indicates which column appears on the left-hand side of the constraint. The first column of the virtual table is column 0. The rowid of the virtual table is column -1. The aConstraint[].op field indicates which operator is used. The SQLITE_INDEX_CONSTRAINT_* constants map integer constants into operator values. Columns occur in the order they were defined by the call to |
︙ | ︙ | |||
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 | agree on what that meaning is. <p>The idxStr value may be a string obtained from an SQLite memory allocation function such as [sqlite3_mprintf()]. If this is the case, then the needToFreeIdxStr flag must be set to true so that the SQLite core will know to call [sqlite3_free()] on that string when it has finished with it, and thus avoid a memory leak. <p>If the virtual table will output rows in the order specified by the ORDER BY clause, then the orderByConsumed flag may be set to true. If the output is not automatically in the correct order then orderByConsumed must be left in its default false setting. This will indicate to the SQLite core that it will need to do a separate sorting pass over the data after it comes out of the virtual table. <p>The estimatedCost field should be set to the estimated number of disk access operations required to execute this query against the virtual table. The SQLite core will often call xBestIndex multiple times with different constraints, obtain multiple cost estimates, then choose the query plan that gives the lowest estimate. <p>If the current version of SQLite is 3.8.2 or greater, the estimatedRows field may be set to an estimate of the number of rows returned by the proposed query plan. If this value is not explicitly set, the default estimate of 25 rows is used. <p>If the current version of SQLite is 3.9.0 or greater, the idxFlags field | > > > > > > | 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 | agree on what that meaning is. <p>The idxStr value may be a string obtained from an SQLite memory allocation function such as [sqlite3_mprintf()]. If this is the case, then the needToFreeIdxStr flag must be set to true so that the SQLite core will know to call [sqlite3_free()] on that string when it has finished with it, and thus avoid a memory leak. The idxStr value may also be a static constant string, in which case the needToFreeIdxStr boolean should remain false. <p>If the virtual table will output rows in the order specified by the ORDER BY clause, then the orderByConsumed flag may be set to true. If the output is not automatically in the correct order then orderByConsumed must be left in its default false setting. This will indicate to the SQLite core that it will need to do a separate sorting pass over the data after it comes out of the virtual table. <p>The estimatedCost field should be set to the estimated number of disk access operations required to execute this query against the virtual table. The SQLite core will often call xBestIndex multiple times with different constraints, obtain multiple cost estimates, then choose the query plan that gives the lowest estimate. The SQLite core initializes estimatedCost to a very large value prior to invoking xBestIndex, so if xBestIndex determines that the current combination of parameters is undesirable, it can leave the estimatedCost field unchanged to discourage its use. <p>If the current version of SQLite is 3.8.2 or greater, the estimatedRows field may be set to an estimate of the number of rows returned by the proposed query plan. If this value is not explicitly set, the default estimate of 25 rows is used. <p>If the current version of SQLite is 3.9.0 or greater, the idxFlags field |
︙ | ︙ | |||
880 881 882 883 884 885 886 887 888 889 890 891 892 893 | the EXPR value of the aConstraint[3] constraint. <p>By default, the SQLite core double checks all constraints on each row of the virtual table that it receives. If such a check is redundant, the xBestFilter method can suppress that double-check by setting aConstraintUsage[].omit. <tcl>hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl> <h2>The xDisconnect Method</h2> <codeblock> int (*xDisconnect)(sqlite3_vtab *pVTab); </codeblock> | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 | the EXPR value of the aConstraint[3] constraint. <p>By default, the SQLite core double checks all constraints on each row of the virtual table that it receives. If such a check is redundant, the xBestFilter method can suppress that double-check by setting aConstraintUsage[].omit. <h3>Return Value</h3> <p>The xBestIndex method should return SQLITE_OK on success. If any kind of fatal error occurs, an appropriate error code (ex: [SQLITE_NOMEM]) should be returned instead. <p>If xBestIndex returns [SQLITE_CONSTRAINT], that does not indicate an error. Rather, SQLITE_CONSTRAINT indicates that the particular combination of input parameters specified should not be used in the query plan. The SQLITE_CONSTRAINT return is useful for [table-valued functions] that have required parameters. If the aConstraint[].usable field is false for one of the required parameter, then the xBestIndex method should return SQLITE_CONSTRAINT. <p>The following example will better illustrate the use of SQLITE_CONSTRAINT as a return value from xBestIndex: <codeblock> SELECT * FROM realtab, tablevaluedfunc(realtab.x); </codeblock> <p>Assuming that the first hidden column of "tablevaluedfunc" is "param1", the query above is semantically equivalent to this: <codeblock> SELECT * FROM realtab, tablevaluedfunc WHERE tablevaluedfunc.param1 = realtab.x; </codeblock> <p>The query planner must decide between many possible implementations of this query, but two plans in particular are of note: <ol> <li><p>Scan all rows of realtab and for each row, find rows in tablevaluedfunc where param1 is equal to realtab.x <li><p>Scan all rows of tablevalued func and for each row find rows in realtab where x is equal to tablevaluedfunc.param1. </ol> <p>The xBestIndex method will be invoked once for each of the potential plans above. For plan 1, the aConstraint[].usable flag for for the SQLITE_CONSTRAINT_EQ constraint on the param1 column will be true because the right-hand side value for the "param1 = ?" constraint will be known. But for plan 2, the aConstraint[].usable flag for "param1 = ?" will be false because the right-hand side value is determined by an inner loop. Hence, the xBestIndex method should return SQLITE_CONSTRAINT when presented with plan 2, forcing SQLite to choose plan 1. <tcl>hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl> <h2>The xDisconnect Method</h2> <codeblock> int (*xDisconnect)(sqlite3_vtab *pVTab); </codeblock> |
︙ | ︙ |