doc-exports/docs/dws/dev/dws_06_0272.html

<a name="EN-US_TOPIC_0000001145510639"></a><a name="EN-US_TOPIC_0000001145510639"></a>

<h1 class="topictitle1">Scalability</h1>
<div id="body8662426"><p id="EN-US_TOPIC_0000001145510639__a89022a97a68c4171b16809924bb29774">The GIN interface has a high level of abstraction, requiring the access method implementer only to implement the semantics of the data type being accessed. The GIN layer itself takes care of concurrency, logging and searching the tree structure.</p>
<p id="EN-US_TOPIC_0000001145510639__af9875987914d46c0a1d26b781abf403c">All it takes to get a GIN access method working is to implement multiple user-defined methods, which define the behavior of keys in the tree and the relationships between keys, indexed items, and indexable queries. In short, GIN combines extensibility with generality, code reuse, and a clean interface.</p>
<p id="EN-US_TOPIC_0000001145510639__a97446d8dfb1d44dda6b3053438deb048">There are four methods that an operator class for GIN must provide:</p>
<ul id="EN-US_TOPIC_0000001145510639__u3c8252d31a074d41b8219478baedc907"><li id="EN-US_TOPIC_0000001145510639__l3e9fea1ac5ce44e2ba28ce18f4a6e05d">int compare(Datum a, Datum b)<p id="EN-US_TOPIC_0000001145510639__a42ac978dcc834cb1a6a2259317c77392"><a name="EN-US_TOPIC_0000001145510639__l3e9fea1ac5ce44e2ba28ce18f4a6e05d"></a><a name="l3e9fea1ac5ce44e2ba28ce18f4a6e05d"></a>Compares two keys (not indexed items) and returns an integer less than zero, zero, or greater than zero, indicating whether the first key is less than, equal to, or greater than the second. Null keys are never passed to this function.</p>
</li></ul>
<ul id="EN-US_TOPIC_0000001145510639__ud47eb4f6690840b48419366cba088219"><li id="EN-US_TOPIC_0000001145510639__l4a5fed8e1ad444ae9b7cc50e58e8caf1">Datum *extractValue(Datum itemValue, int32 *nkeys, bool **nullFlags)<p id="EN-US_TOPIC_0000001145510639__a9ed9a7f96f7242d399819f635020b576"><a name="EN-US_TOPIC_0000001145510639__l4a5fed8e1ad444ae9b7cc50e58e8caf1"></a><a name="l4a5fed8e1ad444ae9b7cc50e58e8caf1"></a>Returns a palloc'd array of keys given an item to be indexed. The number of returned keys must be stored into <strong id="EN-US_TOPIC_0000001145510639__b842352706193510">*nkeys</strong>. If any of the keys can be null, also palloc an array of <strong id="EN-US_TOPIC_0000001145510639__b842352706193543">*nkeys</strong> bool fields, store its address at <strong id="EN-US_TOPIC_0000001145510639__b842352706193549">*nullFlags</strong>, and set these null flags as needed. <strong id="EN-US_TOPIC_0000001145510639__b842352706193623">*nullFlags</strong> can be left NULL (its initial value) if all keys are non-null. The returned value can be NULL if the item contains no keys.</p>
</li></ul>
<ul id="EN-US_TOPIC_0000001145510639__udf89265b31ff4f488986c1e110092886"><li id="EN-US_TOPIC_0000001145510639__l5b598e6299f04dfb9dd2e29e9ee3de78">Datum *extractQuery(Datum query, int32 *nkeys, StrategyNumber n, bool **pmatch, Pointer **extra_data, bool **nullFlags, int32 *searchMode)<p id="EN-US_TOPIC_0000001145510639__acc296694939549ebb56cdc8e33590042"><a name="EN-US_TOPIC_0000001145510639__l5b598e6299f04dfb9dd2e29e9ee3de78"></a><a name="l5b598e6299f04dfb9dd2e29e9ee3de78"></a>Returns a palloc'd array of keys given a value to be queried; that is, query is the value on the right-hand side of an indexable operator whose left-hand side is the indexed column. n is the strategy number of the operator within the operator class. Often, extractQuery will need to consult n to determine the data type of query and the method it should use to extract key values. The number of returned keys must be stored into <strong id="EN-US_TOPIC_0000001145510639__b842352706193510_1">*nkeys</strong>. If any of the keys can be null, also palloc an array of <strong id="EN-US_TOPIC_0000001145510639__b842352706193543_1">*nkeys</strong> bool fields, store its address at <strong id="EN-US_TOPIC_0000001145510639__b842352706193549_1">*nullFlags</strong>, and set these null flags as needed. <strong id="EN-US_TOPIC_0000001145510639__b842352706193623_1">*nullFlags</strong> can be left NULL (its initial value) if all keys are non-null. The returned value can be NULL if the query contains no keys.</p>
<p id="EN-US_TOPIC_0000001145510639__ab24e88af7fad47fba4216356620b8251"><strong id="EN-US_TOPIC_0000001145510639__b842352706145948">searchMode</strong> is an output argument that allows <strong id="EN-US_TOPIC_0000001145510639__b842352706145951">extractQuery</strong> to specify details about how the search will be done. If <strong id="EN-US_TOPIC_0000001145510639__b842352706193826">*searchMode</strong> is set to <strong id="EN-US_TOPIC_0000001145510639__b842352706193830">GIN_SEARCH_MODE_DEFAULT</strong> (which is the value it is initialized to before call), only items that match at least one of the returned keys are considered candidate matches. If <strong id="EN-US_TOPIC_0000001145510639__b8423527061511">*searchMode</strong> is set to <strong id="EN-US_TOPIC_0000001145510639__b8423527061513">GIN_SEARCH_MODE_INCLUDE_EMPTY</strong>, then in addition to items containing at least one matching key, items that contain no keys at all are considered candidate matches. (This mode is useful for implementing is-subset-of operators, for example.) If <strong id="EN-US_TOPIC_0000001145510639__b84235270615119">*searchMode</strong> is set to <strong id="EN-US_TOPIC_0000001145510639__b84235270615121">GIN_SEARCH_MODE_ALL</strong>, then all non-null items in the index are considered candidate matches, whether they match any of the returned keys or not.</p>
<p id="EN-US_TOPIC_0000001145510639__a31798fa3ad2d4489905c3ba487877aa6"><strong id="EN-US_TOPIC_0000001145510639__b84235270619414">pmatch</strong> is an output argument for use when partial match is supported. To use it, <strong id="EN-US_TOPIC_0000001145510639__b8423527061549">extractQuery</strong> must allocate an array of *nkeys Booleans and store its address at <strong id="EN-US_TOPIC_0000001145510639__b8423527061543">*pmatch</strong>. Each element of the array should be set to <strong id="EN-US_TOPIC_0000001145510639__b842352706194024">TRUE</strong> if the corresponding key requires partial match, <strong id="EN-US_TOPIC_0000001145510639__b842352706194026">FALSE</strong> if not. If <strong id="EN-US_TOPIC_0000001145510639__b84235270615432">*pmatch</strong> is set to <strong id="EN-US_TOPIC_0000001145510639__b84235270615435">NULL</strong> then GIN assumes partial match is not required. The variable is initialized to NULL before call, so this argument can simply be ignored by operator classes that do not support partial match.</p>
<p id="EN-US_TOPIC_0000001145510639__aa6bf809a28704553a899e20387c5e46c"><strong id="EN-US_TOPIC_0000001145510639__b84235270615510">extra_data</strong> is an output argument that allows <strong id="EN-US_TOPIC_0000001145510639__b84235270615511">extractQuery</strong> to pass additional data to the <strong id="EN-US_TOPIC_0000001145510639__b84235270615519">consistent</strong> and <strong id="EN-US_TOPIC_0000001145510639__b84235270615522">comparePartial</strong> methods. To use it, <strong id="EN-US_TOPIC_0000001145510639__b84235270615535">extractQuery</strong> must allocate an array of <strong id="EN-US_TOPIC_0000001145510639__b84235270615537">*nkeys</strong> pointers and store its address at <strong id="EN-US_TOPIC_0000001145510639__b84235270615544">*extra_data</strong>, then store whatever it wants to into the individual pointers. The variable is initialized to <strong id="EN-US_TOPIC_0000001145510639__b84235270615559">NULL</strong> before call, so this argument can simply be ignored by operator classes that do not require extra data. If <strong id="EN-US_TOPIC_0000001145510639__b842352706172214">*extra_data</strong> is set, the whole array is passed to the <strong id="EN-US_TOPIC_0000001145510639__b842352706172217">consistent</strong> method, and the appropriate element to the <strong id="EN-US_TOPIC_0000001145510639__b842352706172222">comparePartial</strong> method.</p>
</li></ul>
<ul id="EN-US_TOPIC_0000001145510639__u8f2304541b5c43d588e0aee8b1ab5e0e"><li id="EN-US_TOPIC_0000001145510639__l7ad5069f04554126ba53e625315ddc30">bool consistent(bool check[], StrategyNumber n, Datum query, int32 nkeys, Pointer extra_data[], bool *recheck, Datum queryKeys[], bool nullFlags[])<p id="EN-US_TOPIC_0000001145510639__af09d5752678c4e1f9063b8e9bc419a1b"><a name="EN-US_TOPIC_0000001145510639__l7ad5069f04554126ba53e625315ddc30"></a><a name="l7ad5069f04554126ba53e625315ddc30"></a>Returns <strong id="EN-US_TOPIC_0000001145510639__b842352706172757">TRUE</strong> if an indexed item satisfies the query operator with StrategyNumber <strong id="EN-US_TOPIC_0000001145510639__b84235270617282">n</strong> (or might satisfy it, if the recheck indication is returned). This function does not have direct access to the indexed item's value, since GIN does not store items explicitly. Rather, what is available is knowledge about which key values extracted from the query appear in a given indexed item. The check array has length <strong id="EN-US_TOPIC_0000001145510639__b84235270615740">nkeys</strong>, which is the same as the number of keys previously returned by <strong id="EN-US_TOPIC_0000001145510639__b84235270615738">extractQuery</strong> for this query datum. Each element of the check array is <strong id="EN-US_TOPIC_0000001145510639__b84235270615756">TRUE</strong> if the indexed item contains the corresponding query key, for example, if (check[i] == TRUE), the i-th key of the extractQuery result array is present in the indexed item. The original query datum is passed in case the <strong id="EN-US_TOPIC_0000001145510639__b84235270617232">consistent</strong> method needs to consult it, and so are the <strong id="EN-US_TOPIC_0000001145510639__b84235270615937">queryKeys[]</strong> and <strong id="EN-US_TOPIC_0000001145510639__b84235270615939">nullFlags[]</strong> arrays previously returned by <strong id="EN-US_TOPIC_0000001145510639__b201665248015933">extractQuery</strong>. <strong id="EN-US_TOPIC_0000001145510639__b84235270615919">extra_data</strong> is the extra-data array returned by <strong id="EN-US_TOPIC_0000001145510639__b84235270615922">extractQuery</strong>, or <strong id="EN-US_TOPIC_0000001145510639__b84235270615925">NULL</strong> if none.</p>
<p id="EN-US_TOPIC_0000001145510639__a507683028459468eac8027fbec55382b">When <strong id="EN-US_TOPIC_0000001145510639__b84235270615957">extractQuery</strong> returns a null key in <strong id="EN-US_TOPIC_0000001145510639__b84235270615959">queryKeys[]</strong>, the corresponding <strong id="EN-US_TOPIC_0000001145510639__b842352706151131">check[]</strong> element is <strong id="EN-US_TOPIC_0000001145510639__b842352706151137">TRUE</strong> if the indexed item contains a null key; that is, the semantics of <strong id="EN-US_TOPIC_0000001145510639__b84235270615123">check[]</strong> are like <strong id="EN-US_TOPIC_0000001145510639__b842352706151154">IS NOT DISTINCT FROM</strong>. The <strong id="EN-US_TOPIC_0000001145510639__b842352706151227">consistent</strong> function can examine the corresponding <strong id="EN-US_TOPIC_0000001145510639__b842352706151222">nullFlags[]</strong> element if it needs to tell the difference between a regular value match and a null match.</p>
<p id="EN-US_TOPIC_0000001145510639__a2165af0c59dc4266bfc5fcda5e8a6ad5">On success, <strong id="EN-US_TOPIC_0000001145510639__b84235270615131">*recheck</strong> should be set to <strong id="EN-US_TOPIC_0000001145510639__b84235270615133">TRUE</strong> if the heap tuple needs to be rechecked against the query operator, or <strong id="EN-US_TOPIC_0000001145510639__b84235270615134">FALSE</strong> if the index test is exact. That is, a <strong id="EN-US_TOPIC_0000001145510639__a6b623eeef3db4f64bf30af5b1217a5f1">FALSE</strong> return value guarantees that the heap tuple does not match the query; a <strong id="EN-US_TOPIC_0000001145510639__a78b422b168f3425b8786867eb3994c56">TRUE</strong> return value with <strong id="EN-US_TOPIC_0000001145510639__a52744bf51b334906a90cef91ea14ed82">*recheck</strong> set to <strong id="EN-US_TOPIC_0000001145510639__a3332bfbc371c41508dd97737df718935">FALSE</strong> guarantees that the heap tuple does match the query; and a <strong id="EN-US_TOPIC_0000001145510639__ad47b0908388947b185ddcb6ba4ec886e">TRUE</strong> return value with <strong id="EN-US_TOPIC_0000001145510639__aa66040784f334b268bffac8e004b5937">*recheck</strong> set to <strong id="EN-US_TOPIC_0000001145510639__a497c82eb45d64f7dae6d485e6f5bc876">TRUE</strong> means that the heap tuple might match the query, so it needs to be fetched and rechecked by evaluating the query operator directly against the originally indexed item.</p>
</li></ul>
<p id="EN-US_TOPIC_0000001145510639__adc4d925ec63b49c6913f54ea297bc6a0">Optionally, an operator class for GIN can supply the following method:</p>
<ul id="EN-US_TOPIC_0000001145510639__u553e661dcfc9438c9d11c206a9267993"><li id="EN-US_TOPIC_0000001145510639__l4872925ba50b4269b4970c1e19d9ed98">int comparePartial(Datum partial_key, Datum key, StrategyNumber n, Pointer extra_data)<p id="EN-US_TOPIC_0000001145510639__a75b085aec6d940ed86a8e448dabecb37"><a name="EN-US_TOPIC_0000001145510639__l4872925ba50b4269b4970c1e19d9ed98"></a><a name="l4872925ba50b4269b4970c1e19d9ed98"></a>Compares a partial-match query key to an index key. Returns an integer whose sign indicates the result: less than zero means the index key does not match the query, but the index scan should continue; zero means that the index key matches the query; greater than zero indicates that the index scan should stop because no more matches are possible. The strategy number <strong id="EN-US_TOPIC_0000001145510639__b842352706172856">n</strong> of the operator that generated the partial match query is provided, in case its semantics are needed to determine when to end the scan. Also, <strong id="EN-US_TOPIC_0000001145510639__b842352706151620">extra_data</strong> is the corresponding element of the extra-data array made by <strong id="EN-US_TOPIC_0000001145510639__b842352706151624">extractQuery</strong>, or <strong id="EN-US_TOPIC_0000001145510639__b842352706151626">NULL</strong> if none. Null keys are never passed to this function.</p>
</li></ul>
<p id="EN-US_TOPIC_0000001145510639__a8a60e9c0d9bb457e931ea259c6884377">To support "partial match" queries, an operator class must provide the <strong id="EN-US_TOPIC_0000001145510639__b842352706151655">comparePartial</strong> method, and its <strong id="EN-US_TOPIC_0000001145510639__b842352706151657">extractQuery</strong> method must set the <strong id="EN-US_TOPIC_0000001145510639__b84235270615170">pmatch</strong> parameter when a partial-match query is encountered. For details, see <a href="dws_06_0273.html#EN-US_TOPIC_0000001098671094__s0bd3fd059839486ebc1bf5f9d11459d9">Partial Match Algorithm</a>.</p>
<p id="EN-US_TOPIC_0000001145510639__a0f16ec12c95f434cb634b250d29af741">The actual data types of the various Datum values mentioned in this section vary depending on the operator class. The item values passed to <strong id="EN-US_TOPIC_0000001145510639__b842352706151754">extractValue</strong> are always of the operator class's input type, and all key values must be of the class's <strong id="EN-US_TOPIC_0000001145510639__b842352706151758">STORAGE</strong> type. The type of the query argument passed to <strong id="EN-US_TOPIC_0000001145510639__b842352706151810">extractQuery</strong>, consistent and <strong id="EN-US_TOPIC_0000001145510639__b842352706151812">triConsistent</strong> is whatever is specified as the right-hand input type of the class member operator identified by the strategy number. This need not be the same as the item type, so long as key values of the correct type can be extracted from it.</p>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="dws_06_0270.html">GIN Indexes</a></div>
</div>
</div>