<!--

Documentation of the system catalogs, directed toward PostgreSQL developers

$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.96 2005/02/13 03:04:15 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.97 2005/03/27 23:52:51 tgl Exp $

-->

<chapter id="catalogs">

<entry>Name of the access method</entry>

</row>

<row>

<entry><structfield>amowner</structfield></entry>

<entry><type>int4</type></entry>

<entry><literal><link linkend="catalog-pg-shadow"><structname>pg_shadow</structname></link>.usesysid</literal></entry>

<entry>User ID of the owner (currently not used)</entry>

</row>

<row>

<entry><structfield>amstrategies</structfield></entry>

<entry><type>int2</type></entry>

</row>

<row>

<entry><structfield>amgettuple</structfield></entry>

<entry><structfield>aminsert</structfield></entry>

<entry><type>regproc</type></entry>

<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>

<entry><quote>Next valid tuple</quote> function</entry>

<entry><quote>Insert this tuple</quote> function</entry>

</row>

<row>

<entry><structfield>aminsert</structfield></entry>

<entry><structfield>ambeginscan</structfield></entry>

<entry><type>regproc</type></entry>

<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>

<entry><quote>Insert this tuple</quote> function</entry>

<entry><quote>Start new scan</quote> function</entry>

</row>

<row>

<entry><structfield>ambeginscan</structfield></entry>

<entry><structfield>amgettuple</structfield></entry>

<entry><type>regproc</type></entry>

<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>

<entry><quote>Start new scan</quote> function</entry>

<entry><quote>Next valid tuple</quote> function</entry>

</row>

<row>

<entry><structfield>amgetmulti</structfield></entry>

<entry><type>regproc</type></entry>

<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>

<entry><quote>Fetch multiple tuples</quote> function</entry>

</row>

<row>

<!--

$PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.2 2005/03/21 01:23:55 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.3 2005/03/2723:52:51 tgl Exp $

-->

<chapter id="indexam">

<para>

<programlisting>

boolean

amgetmulti (IndexScanDesc scan,

ItemPointer tids,

int32 max_tids,

int32 *returned_tids);

</programlisting>

Fetch multiple tuples in the given scan. Returns TRUE if the scan should

continue, FALSE if no matching tuples remain. <literal>tids</> points to

a caller-supplied array of <literal>max_tids</>

<structname>ItemPointerData</> records, which the call fills with TIDs of

matching tuples. <literal>*returned_tids</> is set to the number of TIDs

actually returned. This can be less than <literal>max_tids</>, or even

zero, even when the return value is TRUE. (This provision allows the

access method to choose the most efficient stopping points in its scan,

for example index page boundaries.) <function>amgetmulti</> and

<function>amgettuple</> cannot be used in the same index scan; there

are other restrictions too when using <function>amgetmulti</>, as explained

in <xref linkend="index-scanning">.

</para>

<para>

<programlisting>

void

amrescan (IndexScanDesc scan,

ScanKey key);

<programlisting>

void

amcostestimate (Query *root,

RelOptInfo *rel,

IndexOptInfo *index,

List *indexQuals,

Cost *indexStartupCost,

true, insertions or deletions from other backends must be handled as well.)

</para>

<para>

Instead of using <function>amgettuple</>, an index scan can be done with

<function>amgetmulti</> to fetch multiple tuples per call. This can be

noticeably more efficient than <function>amgettuple</> because it allows

avoiding lock/unlock cycles within the access method. In principle

<function>amgetmulti</> should have the same effects as repeated

<function>amgettuple</> calls, but we impose several restrictions to

simplify matters. In the first place, <function>amgetmulti</> does not

take a <literal>direction</> argument, and therefore it does not support

backwards scan nor intrascan reversal of direction. The access method

need not support marking or restoring scan positions during an

<function>amgetmulti</> scan, either. (These restrictions cost little

since it would be difficult to use these features in an

<function>amgetmulti</> scan anyway: adjusting the caller's buffered

list of TIDs would be complex.) Finally, <function>amgetmulti</> does

not guarantee any locking of the returned tuples, with implications

spelled out in <xref linkend="index-locking">.

</para>

</sect1>

<sect1 id="index-locking">

and only visit the heap tuples sometime later, requires much less index

locking overhead and may allow a more efficient heap access pattern.

Per the above analysis, we must use the synchronous approach for

non-MVCC-compliant snapshots, but an asynchronous scan would be safe

for a query using an MVCC snapshot. This possibility is not exploited

as of <productname>PostgreSQL</productname> 8.0, but it is likely to be

investigated soon.

non-MVCC-compliant snapshots, but an asynchronous scan is workable

for a query using an MVCC snapshot.

</para>

<para>

In an <function>amgetmulti</> index scan, the access method need not

guarantee to keep an index pin on any of the returned tuples. (It would be

impractical to pin more than the last one anyway.) Therefore

it is only safe to use such scans with MVCC-compliant snapshots.

</para>

</sect1>

<programlisting>

void

amcostestimate (Query *root,

RelOptInfo *rel,

IndexOptInfo *index,

List *indexQuals,

Cost *indexStartupCost,

</listitem>

</varlistentry>

<varlistentry>

<term>rel</term>

<listitem>

<para>

The relation the index is on.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>index</term>

<listitem>

<para>

The indexitself.

The indexbeing considered.

</para>

</listitem>

</varlistentry>

<para>

The index access costs should be computed in the units used by

<filename>src/backend/optimizer/path/costsize.c</filename>: a sequential disk block fetch

has cost 1.0, a nonsequential fetch has cost random_page_cost, and

the cost of processing one index row should usually be taken as

In addition,an appropriate multiple of cpu_operator_cost should be charged

<filename>src/backend/optimizer/path/costsize.c</filename>: a sequential

disk block fetchhas cost 1.0, a nonsequential fetch has cost

<varname>random_page_cost</>, andthe cost of processing one index row

an appropriate multiple of<varname>cpu_operator_cost</> should be charged

for any comparison operators invoked during index processing (especially

evaluation of the indexQuals themselves).

</para>

<para>

The access costs should include all disk and CPU costs associated with

scanning the index itself, butNOT the costs of retrieving or processing

the parent-table rows that are identified by the index.

scanning the index itself, but<emphasis>not</> the costs of retrieving or

processingthe parent-table rows that are identified by the index.

</para>

<para>

<programlisting>

*indexSelectivity = clauselist_selectivity(root, indexQuals,

rel-&gt;relid, JOIN_INNER);

index-&gt;rel-&gt;relid, JOIN_INNER);

</programlisting>

</para>

</step>

PG_RETURN_BOOL(res);

}

gistgetmulti(PG_FUNCTION_ARGS)

{

IndexScanDescs= (IndexScanDesc)PG_GETARG_POINTER(0);

ItemPointertids= (ItemPointer)PG_GETARG_POINTER(1);

int32max_tids=PG_GETARG_INT32(2);

int32*returned_tids= (int32*)PG_GETARG_POINTER(3);

boolres= true;

int32ntids=0;

while (ntids<max_tids)

{

if (ItemPointerIsValid(&(s->currentItemData)))

res=gistnext(s,ForwardScanDirection);

res=gistfirst(s,ForwardScanDirection);

if (!res)

break;

tids[ntids]=s->xs_ctup.t_self;

ntids++;

}

*returned_tids=ntids;

PG_RETURN_BOOL(res);

}

gistfirst(IndexScanDescs,ScanDirectiondir)

{

}

hashgetmulti(PG_FUNCTION_ARGS)

{

IndexScanDescscan= (IndexScanDesc)PG_GETARG_POINTER(0);

ItemPointertids= (ItemPointer)PG_GETARG_POINTER(1);

int32max_tids=PG_GETARG_INT32(2);

int32*returned_tids= (int32*)PG_GETARG_POINTER(3);

HashScanOpaqueso= (HashScanOpaque)scan->opaque;

Relationrel=scan->indexRelation;

boolres= true;

int32ntids=0;

if (BufferIsValid(so->hashso_curbuf))

_hash_chgbufaccess(rel,so->hashso_curbuf,HASH_NOLOCK,HASH_READ);

while (ntids<max_tids)

{

if (ItemPointerIsValid(&(scan->currentItemData)))

res=_hash_next(scan,ForwardScanDirection);

res=_hash_first(scan,ForwardScanDirection);

if (scan->ignore_killed_tuples)

{

while (res)

{

Pagepage;

OffsetNumberoffnum;

offnum=ItemPointerGetOffsetNumber(&(scan->currentItemData));

page=BufferGetPage(so->hashso_curbuf);

if (!ItemIdDeleted(PageGetItemId(page,offnum)))

break;

res=_hash_next(scan,ForwardScanDirection);

}

}

if (!res)

break;

tids[ntids]=scan->xs_ctup.t_self;

ntids++;

}

if (BufferIsValid(so->hashso_curbuf))

_hash_chgbufaccess(rel,so->hashso_curbuf,HASH_READ,HASH_NOLOCK);

*returned_tids=ntids;

PG_RETURN_BOOL(res);

}

LockBuffer(buffer,BUFFER_LOCK_SHARE);

dp= (PageHeader)BufferGetPage(buffer);

dp= (PageHeader)BufferGetPage(buffer);

offnum=ItemPointerGetOffsetNumber(tid);

if (offnum<FirstOffsetNumber||offnum>PageGetMaxOffsetNumber(dp))

{

LockBuffer(buffer,BUFFER_LOCK_UNLOCK);

if (keep_buf)

*userbuf=buffer;

{

ReleaseBuffer(buffer);

*userbuf=InvalidBuffer;

}

tuple->t_datamcxt=NULL;

tuple->t_data=NULL;

return false;

}

lp=PageGetItemId(dp,offnum);

if (!ItemIdIsUsed(lp))

{