</tgroup>

</table>

<para>

Currently, ordering by the distance operator <literal>&lt;-&gt;</>

is supported only with <literal>point</> by the operator classes

of the geometric types.

</para>

<para>

For historical reasons, the <literal>inet_ops</> operator class is

not the default class for types <type>inet</> and <type>cidr</>.

</para>

<para>

Some approximation is allowed when determining the distance,as long as

the result is never greater than the entry's actual distance. Thus, for

example, distance to a bounding box is usually sufficient in geometric

applications. For an internal tree node, the distance returned must not

be greater than the distance to any of the child nodes. If the returned

distance is notaccurate, the function must set *recheck to false. (This

is not necessary for internal tree nodes; for them, the calculation is

always assumed to beinaccurate). The executor will calculate the

accurate distance after fetchingthetuple fromtheheap, and reorder

the tuples if necessary.

Some approximation is allowed when determining the distance,so long

asthe result is never greater than the entry's actual distance. Thus,

forexample, distance to a bounding box is usually sufficient in

geometricapplications. For an internal tree node, the distance

returned must notbe greater than the distance to any of the child

nodes. If the returneddistance is notexact, the function must set

<literal>*recheck</> to true. (Thisis not necessary for internal tree

nodes; for them, the calculation isalways assumed to beinexact.) In

this casetheexecutor will calculatetheaccurate distance after

fetching the tuple from the heap, and reorderthe tuples if necessary.

</para>

<para>

If the distance function returns *recheck=true for a leaf node, the

original ordering operator's return type must be float8 or float4, and

the distance function's return value must be comparable with the actual

distance operator. Otherwise, the distance function's return type can

be any finit <type>float8</> value, as long as the relative order of

the returned values matches the order returned by the ordering operator.

(Infinity and minus infinity are used internally to handle cases such as

nulls, so it is not recommended that <function>distance</> functions

return these values.)

If the distance function returns <literal>*recheck = true</> for any

leaf node, the original ordering operator's return type must

be <type>float8</> or <type>float4</>, and the distance function's

result values must be comparable to those of the original ordering

operator, since the executor will sort using both distance function

results and recalculated ordering-operator results. Otherwise, the

distance function's result values can be any finite <type>float8</>

values, so long as the relative order of the result values matches the

order returned by the ordering operator. (Infinity and minus infinity

are used internally to handle cases such as nulls, so it is not

recommended that <function>distance</> functions return these values.)

</para>

</listitem>

struct, whose 'key' field contains the same datum in the original,

uncompressed form. If the opclass' compress function does nothing for

leaf entries, the fetch method can return the argument as is.

</para>

</para>

<para>

The matching code in the C module could then follow this skeleton:

recheck= false;

dist=FunctionCall5Coll(&key->sk_func,

{

if (so->orderByTypes[i]==FLOAT8OID)

{

if (!scan->xs_orderbynulls[i])

pfree(DatumGetPointer(scan->xs_orderbyvals[i]));

scan->xs_orderbyvals[i]=Float8GetDatum(item->distances[i]);

scan->xs_orderbynulls[i]= false;

}

elseif (so->orderByTypes[i]==FLOAT4OID)

{

if (!scan->xs_orderbynulls[i])

pfree(DatumGetPointer(scan->xs_orderbyvals[i]));

scan->xs_orderbyvals[i]=Float4GetDatum((float4)item->distances[i]);

scan->xs_orderbynulls[i]= false;

}

if (scan->xs_recheckorderby)

elog(ERROR,"GiST operator family's FOR ORDER BY operator must return float8 or float4 if the distance function is lossy");

so->qual_ok= true;/* in case there are zero keys */

if (scan->numberOfOrderBys>0)

{

scan->xs_orderbyvals=palloc(sizeof(Datum)*scan->numberOfOrderBys);

scan->xs_orderbyvals=palloc0(sizeof(Datum)*scan->numberOfOrderBys);

scan->xs_orderbynulls=palloc(sizeof(bool)*scan->numberOfOrderBys);

memset(scan->xs_orderbynulls, true,sizeof(bool)*scan->numberOfOrderBys);

}

scan->opaque=so;

GIST_DISTANCE_PROC,skey->sk_attno,

RelationGetRelationName(scan->indexRelation));

fmgr_info_copy(&(skey->sk_func),finfo,so->giststate->scanCxt);

so->orderByTypes[i]=get_func_rettype(skey->sk_func.fn_oid);

fmgr_info_copy(&(skey->sk_func),finfo,so->giststate->scanCxt);

if (!first_time)

{

HeapTupleresult;

ReorderTuple*topmost;

inti;

topmost= (ReorderTuple*)pairingheap_remove_first(node->iss_ReorderQueue);

result=topmost->htup;

for (i=0;i<node->iss_NumOrderByKeys;i++)

{

if (!node->iss_OrderByTypByVals[i]&& !topmost->orderbynulls[i])

pfree(DatumGetPointer(topmost->orderbyvals[i]));

}

pfree(topmost->orderbyvals);

pfree(topmost->orderbynulls);

pfree(topmost);

Datum*xs_orderbyvals;

bool*xs_orderbynulls;

boolxs_recheckorderby;/* T means ORDER BY exprs must be rechecked */

boolxs_recheckorderby;

boolxs_continue_hot;/* T if must keep walking HOT chain */