PostgreSQL

+
The first argument is a pointer to a `+spgConfigIn+` C struct, containing input data for the function. The second argument is a pointer to a `+spgConfigOut+` C struct, which the function must fill with result data.
+

  +
  `+attType+` is passed in order to support polymorphic index operator classes; for ordinary fixed-data-type operator classes, it will always have the same value and so can be ignored.
  +
  For operator classes that do not use prefixes, `+prefixType+` can be set to `+VOIDOID+`. Likewise, for operator classes that do not use node labels, `+labelType+` can be set to `+VOIDOID+`. `+canReturnData+` should be set true if the operator class is capable of reconstructing the originally-supplied index value. `+longValuesOK+` should be set true only when the `+attType+` is of variable length and the operator class is capable of segmenting long values by repeated suffixing (see link:spgist-implementation.html#SPGIST-LIMITS[Section 69.4.1]).
  +
  `+leafType+` should match the index storage type defined by the operator class's `+opckeytype+` catalog entry. (Note that `+opckeytype+` can be zero, implying the storage type is the same as the operator class's input type, which is the most common situation.) For reasons of backward compatibility, the `+config+` method can set `+leafType+` to some other value, and that value will be used; but this is deprecated since the index contents are then incorrectly identified in the catalogs. Also, it's permissible to leave `+leafType+` uninitialized (zero); that is interpreted as meaning the index storage type derived from `+opckeytype+`.
  +
  When `+attType+` and `+leafType+` are different, the optional method `+compress+` must be provided. Method `+compress+` is responsible for transformation of datums to be indexed from `+attType+` to `+leafType+`.
[.term]#`+choose+`#::
  Chooses a method for inserting a new value into an inner tuple.
  +
  The SQL declaration of the function must look like this:
  +

+
The first argument is a pointer to a `+spgChooseIn+` C struct, containing input data for the function. The second argument is a pointer to a `+spgChooseOut+` C struct, which the function must fill with result data.
+

  +
  `+datum+` is the original datum of `+spgConfigIn+`.`+attType+` type that was to be inserted into the index. `+leafDatum+` is a value of `+spgConfigOut+`.`+leafType+` type, which is initially a result of method `+compress+` applied to `+datum+` when method `+compress+` is provided, or the same value as `+datum+` otherwise. `+leafDatum+` can change at lower levels of the tree if the `+choose+` or `+picksplit+` methods change it. When the insertion search reaches a leaf page, the current value of `+leafDatum+` is what will be stored in the newly created leaf tuple. `+level+` is the current inner tuple's level, starting at zero for the root level. `+allTheSame+` is true if the current inner tuple is marked as containing multiple equivalent nodes (see link:spgist-implementation.html#SPGIST-ALL-THE-SAME[Section 69.4.3]). `+hasPrefix+` is true if the current inner tuple contains a prefix; if so, `+prefixDatum+` is its value. `+nNodes+` is the number of child nodes contained in the inner tuple, and `+nodeLabels+` is an array of their label values, or NULL if there are no labels.
  +
  The `+choose+` function can determine either that the new value matches one of the existing child nodes, or that a new child node must be added, or that the new value is inconsistent with the tuple prefix and so the inner tuple must be split to create a less restrictive prefix.
  +
  If the new value matches one of the existing child nodes, set `+resultType+` to `+spgMatchNode+`. Set `+nodeN+` to the index (from zero) of that node in the node array. Set `+levelAdd+` to the increment in `+level+` caused by descending through that node, or leave it as zero if the operator class does not use levels. Set `+restDatum+` to equal `+leafDatum+` if the operator class does not modify datums from one level to the next, or otherwise set it to the modified value to be used as `+leafDatum+` at the next level.
  +
  If a new child node must be added, set `+resultType+` to `+spgAddNode+`. Set `+nodeLabel+` to the label to be used for the new node, and set `+nodeN+` to the index (from zero) at which to insert the node in the node array. After the node has been added, the `+choose+` function will be called again with the modified inner tuple; that call should result in an `+spgMatchNode+` result.
  +
  If the new value is inconsistent with the tuple prefix, set `+resultType+` to `+spgSplitTuple+`. This action moves all the existing nodes into a new lower-level inner tuple, and replaces the existing inner tuple with a tuple having a single downlink pointing to the new lower-level inner tuple. Set `+prefixHasPrefix+` to indicate whether the new upper tuple should have a prefix, and if so set `+prefixPrefixDatum+` to the prefix value. This new prefix value must be sufficiently less restrictive than the original to accept the new value to be indexed. Set `+prefixNNodes+` to the number of nodes needed in the new tuple, and set `+prefixNodeLabels+` to a palloc'd array holding their labels, or to NULL if node labels are not required. Note that the total size of the new upper tuple must be no more than the total size of the tuple it is replacing; this constrains the lengths of the new prefix and new labels. Set `+childNodeN+` to the index (from zero) of the node that will downlink to the new lower-level inner tuple. Set `+postfixHasPrefix+` to indicate whether the new lower-level inner tuple should have a prefix, and if so set `+postfixPrefixDatum+` to the prefix value. The combination of these two prefixes and the downlink node's label (if any) must have the same meaning as the original prefix, because there is no opportunity to alter the node labels that are moved to the new lower-level tuple, nor to change any child index entries. After the node has been split, the `+choose+` function will be called again with the replacement inner tuple. That call may return an `+spgAddNode+` result, if no suitable node was created by the `+spgSplitTuple+` action. Eventually `+choose+` must return `+spgMatchNode+` to allow the insertion to descend to the next level.
[.term]#`+picksplit+`#::
  Decides how to create a new inner tuple over a set of leaf tuples.
  +
  The SQL declaration of the function must look like this:
  +

+
The first argument is a pointer to a `+spgPickSplitIn+` C struct, containing input data for the function. The second argument is a pointer to a `+spgPickSplitOut+` C struct, which the function must fill with result data.
+

  +
  `+nTuples+` is the number of leaf tuples provided. `+datums+` is an array of their datum values of `+spgConfigOut+`.`+leafType+` type. `+level+` is the current level that all the leaf tuples share, which will become the level of the new inner tuple.
  +
  Set `+hasPrefix+` to indicate whether the new inner tuple should have a prefix, and if so set `+prefixDatum+` to the prefix value. Set `+nNodes+` to indicate the number of nodes that the new inner tuple will contain, and set `+nodeLabels+` to an array of their label values, or to NULL if node labels are not required. Set `+mapTuplesToNodes+` to an array that gives the index (from zero) of the node that each leaf tuple should be assigned to. Set `+leafTupleDatums+` to an array of the values to be stored in the new leaf tuples (these will be the same as the input `+datums+` if the operator class does not modify datums from one level to the next). Note that the `+picksplit+` function is responsible for palloc'ing the `+nodeLabels+`, `+mapTuplesToNodes+` and `+leafTupleDatums+` arrays.
  +
  If more than one leaf tuple is supplied, it is expected that the `+picksplit+` function will classify them into more than one node; otherwise it is not possible to split the leaf tuples across multiple pages, which is the ultimate purpose of this operation. Therefore, if the `+picksplit+` function ends up placing all the leaf tuples in the same node, the core SP-GiST code will override that decision and generate an inner tuple in which the leaf tuples are assigned at random to several identically-labeled nodes. Such a tuple is marked `+allTheSame+` to signify that this has happened. The `+choose+` and `+inner_consistent+` functions must take suitable care with such inner tuples. See link:spgist-implementation.html#SPGIST-ALL-THE-SAME[Section 69.4.3] for more information.
  +
  `+picksplit+` can be applied to a single leaf tuple only in the case that the `+config+` function set `+longValuesOK+` to true and a larger-than-a-page input value has been supplied. In this case the point of the operation is to strip off a prefix and produce a new, shorter leaf datum value. The call will be repeated until a leaf datum short enough to fit on a page has been produced. See link:spgist-implementation.html#SPGIST-LIMITS[Section 69.4.1] for more information.
[.term]#`+inner_consistent+`#::
  Returns set of nodes (branches) to follow during tree search.
  +
  The SQL declaration of the function must look like this:
  +

+
The first argument is a pointer to a `+spgInnerConsistentIn+` C struct, containing input data for the function. The second argument is a pointer to a `+spgInnerConsistentOut+` C struct, which the function must fill with result data.
+

  +
  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. The array `+orderbys+`, of length `+norderbys+`, describes ordering operators (if any) in the same manner. `+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 parent level. `+traversalValue+` is a pointer to any traverse data passed down from the previous call of `+inner_consistent+` on the parent index tuple, or NULL at the root level. `+traversalMemoryContext+` is the memory context in which to store output traverse values (see below). `+level+` is the current inner tuple's level, starting at zero for the root level. `+returnData+` is `+true+` if reconstructed data is required for this query; this will only be so if the `+config+` function asserted `+canReturnData+`. `+allTheSame+` is true if the current inner tuple is marked [.quote]#“[.quote]#all-the-same#”#; in this case all the nodes have the same label (if any) and so either all or none of them match the query (see link:spgist-implementation.html#SPGIST-ALL-THE-SAME[Section 69.4.3]). `+hasPrefix+` is true if the current inner tuple contains a prefix; if so, `+prefixDatum+` is its value. `+nNodes+` is the number of child nodes contained in the inner tuple, and `+nodeLabels+` is an array of their label values, or NULL if the nodes do not have labels.
  +
  `+nNodes+` must be set to the number of child nodes that need to be visited by the search, and `+nodeNumbers+` must be set to an array of their indexes. If the operator class keeps track of levels, set `+levelAdds+` to an array of the level increments required when descending to each node to be visited. (Often these increments will be the same for all the nodes, but that's not necessarily so, so an array is used.) If value reconstruction is needed, set `+reconstructedValues+` to an array of the values reconstructed for each child node to be visited; otherwise, leave `+reconstructedValues+` as NULL. The reconstructed values are assumed to be of type `+spgConfigOut+`.`+leafType+`. (However, since the core system will do nothing with them except possibly copy them, it is sufficient for them to have the same `+typlen+` and `+typbyval+` properties as `+leafType+`.) If ordered search is performed, set `+distances+` to an array of distance values according to `+orderbys+` array (nodes with lowest distances will be processed first). Leave it NULL otherwise. If it is desired to pass down additional out-of-band information ([.quote]#“[.quote]#traverse values#”#) to lower levels of the tree search, set `+traversalValues+` to an array of the appropriate traverse values, one for each child node to be visited; otherwise, leave `+traversalValues+` as NULL. Note that the `+inner_consistent+` function is responsible for palloc'ing the `+nodeNumbers+`, `+levelAdds+`, `+distances+`, `+reconstructedValues+`, and `+traversalValues+` arrays in the current memory context. However, any output traverse values pointed to by the `+traversalValues+` array should be allocated in `+traversalMemoryContext+`. Each traverse value must be a single palloc'd chunk.
[.term]#`+leaf_consistent+`#::
  Returns true if a leaf tuple satisfies a query.
  +
  The SQL declaration of the function must look like this:
  +

+
The first argument is a pointer to a `+spgLeafConsistentIn+` C struct, containing input data for the function. The second argument is a pointer to a `+spgLeafConsistentOut+` C struct, which the function must fill with result data.
+

+
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. The array `+orderbys+`, of length `+norderbys+`, describes the ordering operators in the same manner. `+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 parent level. `+traversalValue+` is a pointer to any traverse data passed down from the previous call of `+inner_consistent+` on the parent index tuple, or NULL at the root level. `+level+` is the current leaf tuple's level, starting at zero for the root level. `+returnData+` is `+true+` if reconstructed data is required for this query; this will only be so if the `+config+` function asserted `+canReturnData+`. `+leafDatum+` is the key value of `+spgConfigOut+`.`+leafType+` stored in the current leaf tuple.
+
The function must return `+true+` if the leaf tuple matches the query, or `+false+` if not. In the `+true+` case, if `+returnData+` is `+true+` then `+leafValue+` must be set to the value (of type `+spgConfigIn+`.`+attType+`) 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(s) must be re-applied to the actual heap tuple to verify the match. If ordered search is performed, set `+distances+` to an array of distance values according to `+orderbys+` array. Leave it NULL otherwise. If at least one of returned distances is not exact, set `+recheckDistances+` to true. In this case, the executor will calculate the exact distances after fetching the tuple from the heap, and will reorder the tuples if needed.

+
The function is passed a pointer to a `+local_relopts+` struct, which needs to be filled with a set of operator class specific options. The options can be accessed from other support functions using the `+PG_HAS_OPCLASS_OPTIONS()+` and `+PG_GET_OPCLASS_OPTIONS()+` macros.
+
Since the representation of the key in SP-GiST is flexible, it may depend on user-specified parameters.