From 03e56f798e365763486b03a2630fbc3190ccd29a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 10 Mar 2012 18:36:49 -0500 Subject: Restructure SPGiST opclass interface API to support whole-index scans. The original API definition was incapable of supporting whole-index scans because there was no way to invoke leaf-value reconstruction without checking any qual conditions. Also, it was inefficient for multiple-qual-condition scans because value reconstruction got done over again for each qual condition, and because other internal work in the consistent functions likewise had to be done for each qual. To fix these issues, pass the whole scankey array to the opclass consistent functions, instead of only letting them see one item at a time. (Essentially, the loop over scankey entries is now inside the consistent functions not outside them. This makes the consistent functions a bit more complicated, but not unreasonably so.) In itself this commit does nothing except save a few cycles in multiple-qual-condition index scans, since we can't support whole-index scans on SPGiST indexes until nulls are included in the index. However, I consider this a must-fix for 9.2 because once we release it will get very much harder to change the opclass API definition. --- doc/src/sgml/spgist.sgml | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index dcc3cc2d733..0202dbcdd5a 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -439,8 +439,8 @@ CREATE FUNCTION my_inner_consistent(internal, internal) RETURNS void ... typedef struct spgInnerConsistentIn { - StrategyNumber strategy; /* operator strategy number */ - Datum query; /* operator's RHS value */ + ScanKey scankeys; /* array of operators and comparison values */ + int nkeys; /* length of array */ Datum reconstructedValue; /* value reconstructed at parent */ int level; /* current level (counting from zero) */ @@ -463,8 +463,17 @@ typedef struct spgInnerConsistentOut } spgInnerConsistentOut; - strategy and - query describe the index search condition. + The array scankeys, of length nkeys, + describes the index search condition(s). These conditions are + combined with AND — only index entries that satisfy all of + them are interesting. (Note that nkeys = 0 implies + that all index entries satisfy the query.) Usually the consistent + function only cares about the sk_strategy and + sk_argument fields of each array entry, which + respectively give the indexable operator and comparison value. + In particular it is not necessary to check sk_flags to + see if the comparison value is NULL, because the SP-GiST core code + will filter out such conditions. reconstructedValue is the value reconstructed for the parent tuple; it is (Datum) 0 at the root level or if the inner_consistent function did not provide a value at the @@ -527,8 +536,8 @@ CREATE FUNCTION my_leaf_consistent(internal, internal) RETURNS bool ... typedef struct spgLeafConsistentIn { - StrategyNumber strategy; /* operator strategy number */ - Datum query; /* operator's RHS value */ + ScanKey scankeys; /* array of operators and comparison values */ + int nkeys; /* length of array */ Datum reconstructedValue; /* value reconstructed at parent */ int level; /* current level (counting from zero) */ @@ -544,8 +553,17 @@ typedef struct spgLeafConsistentOut } spgLeafConsistentOut; - strategy and - query define the index search condition. + The array scankeys, of length nkeys, + describes the index search condition(s). These conditions are + combined with AND — only index entries that satisfy all of + them satisfy the query. (Note that nkeys = 0 implies + that all index entries satisfy the query.) Usually the consistent + function only cares about the sk_strategy and + sk_argument fields of each array entry, which + respectively give the indexable operator and comparison value. + In particular it is not necessary to check sk_flags to + see if the comparison value is NULL, because the SP-GiST core code + will filter out such conditions. reconstructedValue is the value reconstructed for the parent tuple; it is (Datum) 0 at the root level or if the inner_consistent function did not provide a value at the @@ -566,8 +584,8 @@ typedef struct spgLeafConsistentOut leafValue must be set to the value originally supplied to be indexed for this leaf tuple. Also, recheck may be set to true if the match - is uncertain and so the operator must be re-applied to the actual heap - tuple to verify the match. + is uncertain and so the operator(s) must be re-applied to the actual + heap tuple to verify the match. -- cgit v1.2.3