Home Explore Blog CI



postgresql

13th chunk of `doc/src/sgml/indexam.sgml`
414d4ae9bd55486ead8f1debf16712bfce14db5851c9010a0000000100000fa0
 <function>amrescan</function>, or <function>amendscan</function>
   call for the scan.
  </para>

  <para>
   The <function>amgettuple</function> function need only be provided if the access
   method supports <quote>plain</quote> index scans.  If it doesn't, the
   <structfield>amgettuple</structfield> field in its <structname>IndexAmRoutine</structname>
   struct must be set to NULL.
  </para>

  <para>
<programlisting>
int64
amgetbitmap (IndexScanDesc scan,
             TIDBitmap *tbm);
</programlisting>
   Fetch all tuples in the given scan and add them to the caller-supplied
   <type>TIDBitmap</type> (that is, OR the set of tuple IDs into whatever set is already
   in the bitmap).  The number of tuples fetched is returned (this might be
   just an approximate count, for instance some AMs do not detect duplicates).
   While inserting tuple IDs into the bitmap, <function>amgetbitmap</function> can
   indicate that rechecking of the scan conditions is required for specific
   tuple IDs.  This is analogous to the <literal>xs_recheck</literal> output parameter
   of <function>amgettuple</function>.  Note: in the current implementation, support
   for this feature is conflated with support for lossy storage of the bitmap
   itself, and therefore callers recheck both the scan conditions and the
   partial index predicate (if any) for recheckable tuples.  That might not
   always be true, however.
   <function>amgetbitmap</function> and
   <function>amgettuple</function> cannot be used in the same index scan; there
   are other restrictions too when using <function>amgetbitmap</function>, as explained
   in <xref linkend="index-scanning"/>.
  </para>

  <para>
   The <function>amgetbitmap</function> function need only be provided if the access
   method supports <quote>bitmap</quote> index scans.  If it doesn't, the
   <structfield>amgetbitmap</structfield> field in its <structname>IndexAmRoutine</structname>
   struct must be set to NULL.
  </para>

  <para>
<programlisting>
void
amendscan (IndexScanDesc scan);
</programlisting>
   End a scan and release resources.  The <literal>scan</literal> struct itself
   should not be freed, but any locks or pins taken internally by the
   access method must be released, as well as any other memory allocated
   by <function>ambeginscan</function> and other scan-related functions.
  </para>

  <para>
<programlisting>
void
ammarkpos (IndexScanDesc scan);
</programlisting>
   Mark current scan position.  The access method need only support one
   remembered scan position per scan.
  </para>

  <para>
   The <function>ammarkpos</function> function need only be provided if the access
   method supports ordered scans.  If it doesn't,
   the <structfield>ammarkpos</structfield> field in its <structname>IndexAmRoutine</structname>
   struct may be set to NULL.
  </para>

  <para>
<programlisting>
void
amrestrpos (IndexScanDesc scan);
</programlisting>
   Restore the scan to the most recently marked position.
  </para>

  <para>
   The <function>amrestrpos</function> function need only be provided if the access
   method supports ordered scans.  If it doesn't,
   the <structfield>amrestrpos</structfield> field in its <structname>IndexAmRoutine</structname>
   struct may be set to NULL.
  </para>

  <para>
   In addition to supporting ordinary index scans, some types of index
   may wish to support <firstterm>parallel index scans</firstterm>, which allow
   multiple backends to cooperate in performing an index scan.  The
   index access method should arrange things so that each cooperating
   process returns a subset of the tuples that would be performed by
   an ordinary, non-parallel index scan, but in such a way that the
   union of those subsets is equal to the set of tuples that would be
   returned by an ordinary, non-parallel index scan.  Furthermore, while
   there need not be any global ordering of tuples returned by a parallel
   scan, the ordering of that subset of tuples returned within

Title: Index Access Method Functions: amendscan, ammarkpos, amrestrpos, and Parallel Index Scans
Summary
This section describes additional index access method functions: amendscan ends a scan and releases resources, ammarkpos marks the current scan position (for ordered scans), and amrestrpos restores the scan to the marked position (also for ordered scans). It also discusses parallel index scans, where multiple backends cooperate to perform an index scan, each returning a subset of tuples.