<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.198 2009/02/24 10:06:31 petere Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.199 2009/03/05 23:06:45 tgl Exp $ -->

<!--

Documentation of the system catalogs, directed toward PostgreSQL developers

-->

<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>Next valid tuple</quote> function</entry>

<entry><quote>Next valid tuple</quote> function, or zero if none</entry>

</row>

<row>

<entry><structfield>amgetbitmap</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 all valid tuples</quote> function</entry>

<entry><quote>Fetch all valid tuples</quote> function, or zero if none</entry>

</row>

<row>

<!-- $PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.28 2008/10/17 22:10:29 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/indexam.sgml,v 2.29 2009/03/05 23:06:45 tgl Exp $ -->

<chapter id="indexam">

<title>Index Access Method Interface Definition</title>

extant versions of the same logical row; to an index, each tuple is

an independent object that needs its own index entry. Thus, an

update of a row always creates all-new index entries for the row, even if

the key values did not change. Index entries for dead tuples are

reclaimed (by vacuuming) when the dead tuples themselves are reclaimed.

the key values did not change. (HOT tuples are an exception to this

statement; but indexes do not deal with those, either.) Index entries for

dead tuples are reclaimed (by vacuuming) when the dead tuples themselves

are reclaimed.

</para>

<sect1 id="index-catalog">

The function should construct a <type>bytea</> value, which will be copied

into the <structfield>rd_options</> field of the index's relcache entry.

The data contents of the <type>bytea</> value are open for the access

method to define, butthe standard access methods currently all use struct

method to define; most ofthe standard access methods use struct

<structname>StdRdOptions</>.

When <parameter>validate</> is true, the function should report a suitable

error message if any of the options are unrecognized or have invalid

an indexable <literal>WHERE</> condition, often called a

<firstterm>qualifier</> or <firstterm>scan key</>. The semantics of

index scanning are described more fully in <xref linkend="index-scanning">,

below. The scan-related functions that an index access method must provide

are:

below. An index access method can support <quote>plain</> index scans,

<quote>bitmap</> index scans, or both. The scan-related functions that an

index access method must or may provide are:

</para>

<para>

callers.

</para>

<para>

The <function>amgettuple</> function need only be provided if the access

method supports <quote>plain</> index scans. If it doesn't, the

<structfield>amgettuple</> field in its <structname>pg_am</> row must

be set to zero.

</para>

<para>

<programlisting>

int64

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

</para>

<para>

The <function>amgetbitmap</> function need only be provided if the access

method supports <quote>bitmap</> index scans. If it doesn't, the

<structfield>amgetbitmap</> field in its <structname>pg_am</> row must

be set to zero.

</para>

<para>

<programlisting>

void

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

</para>

<para>

Note that it is permitted for an access method to implement only

<function>amgetbitmap</> and not <function>amgettuple</>, or vice versa,

if its internal implementation is unsuited to one API or the other.

</para>

</sect1>

<sect1 id="index-locking">

((opfamily) == BOOL_BTREE_FAM_OID || (opfamily) == BOOL_HASH_FAM_OID)

{

ST_INDEXSCAN,/* must support amgettuple */

ST_BITMAPSCAN,/* must support amgetbitmap */

}ScanTypeControl;

{

staticList*find_usable_indexes(PlannerInfo*root,RelOptInfo*rel,

List*clauses,List*outer_clauses,

boolistoplevel,RelOptInfo*outer_rel,

SaOpControlsaop_control);

SaOpControlsaop_control,ScanTypeControlscantype);

staticList*find_saop_paths(PlannerInfo*root,RelOptInfo*rel,

List*clauses,List*outer_clauses,

boolistoplevel,RelOptInfo*outer_rel);

indexpaths=find_usable_indexes(root,rel,

rel->baserestrictinfo,NIL,

true,NULL,SAOP_FORBID);

true,NULL,SAOP_FORBID,ST_ANYSCAN);

bitindexpaths=NIL;

foreach(l,indexpaths)

{

IndexPath*ipath= (IndexPath*)lfirst(l);

add_path(rel, (Path*)ipath);

if (ipath->indexinfo->amhasgettuple)

add_path(rel, (Path*)ipath);

if (ipath->indexselectivity<1.0&&

if (ipath->indexinfo->amhasgetbitmap&&

!ScanDirectionIsBackward(ipath->indexscandir))

bitindexpaths=lappend(bitindexpaths,ipath);

}

find_usable_indexes(PlannerInfo*root,RelOptInfo*rel,

List*clauses,List*outer_clauses,

boolistoplevel,RelOptInfo*outer_rel,

SaOpControlsaop_control)

SaOpControlsaop_control,ScanTypeControlscantype)

{

Relidsouter_relids=outer_rel ?outer_rel->relids :NULL;

boolpossibly_useful_pathkeys=has_useful_pathkeys(root,rel);

boolfound_clause;

boolindex_is_ordered;

switch (scantype)

{

caseST_INDEXSCAN:

if (!index->amhasgettuple)

continue;

break;

caseST_BITMAPSCAN:

if (!index->amhasgetbitmap)

continue;

break;

caseST_ANYSCAN:

break;

}

returnfind_usable_indexes(root,rel,

clauses,outer_clauses,

istoplevel,outer_rel,

SAOP_REQUIRE);

SAOP_REQUIRE,ST_BITMAPSCAN);

}

all_clauses,

false,

outer_rel,

SAOP_ALLOW);

SAOP_ALLOW,

ST_BITMAPSCAN);

indlist=list_concat(indlist,

generate_bitmap_or_paths(root,rel,

all_clauses,

false,

outer_rel,

SAOP_ALLOW);

SAOP_ALLOW,

ST_BITMAPSCAN);

}

List*clause_list;

List*indexpaths;

List*bitindexpaths;

List*allindexpaths;

ListCell*l;

InnerIndexscanInfo*info;

MemoryContextoldcontext;

indexpaths=find_usable_indexes(root,rel,

clause_list,NIL,

false,outer_rel,

SAOP_FORBID);

allindexpaths=find_usable_indexes(root,rel,

clause_list,NIL,

false,outer_rel,

SAOP_FORBID,

ST_ANYSCAN);

indexpaths=bitindexpaths=NIL;

foreach(l,allindexpaths)

{

IndexPath*ipath= (IndexPath*)lfirst(l);

if (ipath->indexinfo->amhasgettuple)

indexpaths=lappend(indexpaths,ipath);

if (ipath->indexinfo->amhasgetbitmap)

bitindexpaths=lappend(bitindexpaths,ipath);

}

bitindexpaths=generate_bitmap_or_paths(root,rel,

clause_list,NIL,

outer_rel);

bitindexpaths=list_concat(bitindexpaths,

generate_bitmap_or_paths(root,rel,

clause_list,NIL,

outer_rel));

clause_list,NIL,

false,outer_rel));

bitindexpaths=list_concat(bitindexpaths,list_copy(indexpaths));

info->amcostestimate=indexRelation->rd_am->amcostestimate;

info->amoptionalkey=indexRelation->rd_am->amoptionalkey;

info->amsearchnulls=indexRelation->rd_am->amsearchnulls;

info->amhasgettuple=OidIsValid(indexRelation->rd_am->amgettuple);

info->amhasgetbitmap=OidIsValid(indexRelation->rd_am->amgetbitmap);

Oidamkeytype;/* type of data in index, or InvalidOid */

regprocaminsert;/* "insert this tuple" function */

regprocambeginscan;/* "start new scan" function */

regprocamgettuple;/* "next valid tuple" function */

regprocamgetbitmap;/* "fetch all valid tuples" function */

regprocamgettuple;/* "next valid tuple" function, or 0 */

regprocamgetbitmap;/* "fetch all valid tuples" function, or 0 */

regprocamrescan;/* "restart this scan" function */

regprocamendscan;/* "end this scan" function */

regprocammarkpos;/* "mark current scan position" function */

boolunique;/* true if a unique index */

boolamoptionalkey;/* can query omit key for the first column? */

boolamsearchnulls;/* can AM search for NULL index entries? */

boolamhasgettuple;/* does AM have amgettuple interface? */

boolamhasgetbitmap;/* does AM have amgetbitmap interface? */

}IndexOptInfo;