Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
commit: 293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree: fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/index-functions.html
parent: Initial commit. (diff)
download: postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz
postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip
1 files changed, 487 insertions, 0 deletions
diff --git a/doc/src/sgml/html/index-functions.html b/doc/src/sgml/html/index-functions.html
new file mode 100644
index 0000000..c2ccf07
--- /dev/null
+++ b/doc/src/sgml/html/index-functions.html
@@ -0,0 +1,487 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.2. Index Access Method Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="index-api.html" title="64.1. Basic API Structure for Indexes" /><link rel="next" href="index-scanning.html" title="64.3. Index Scanning" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.2. Index Access Method Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-api.html" title="64.1. Basic API Structure for Indexes">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-scanning.html" title="64.3. Index Scanning">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-FUNCTIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.2. Index Access Method Functions <a href="#INDEX-FUNCTIONS" class="id_link">#</a></h2></div></div></div><p>
+   The index construction and maintenance functions that an index access
+   method must provide in <code class="structname">IndexAmRoutine</code> are:
+  </p><p>
+</p><pre class="programlisting">
+IndexBuildResult *
+ambuild (Relation heapRelation,
+         Relation indexRelation,
+         IndexInfo *indexInfo);
+</pre><p>
+   Build a new index.  The index relation has been physically created,
+   but is empty.  It must be filled in with whatever fixed data the
+   access method requires, plus entries for all tuples already existing
+   in the table.  Ordinarily the <code class="function">ambuild</code> function will call
+   <code class="function">table_index_build_scan()</code> to scan the table for existing tuples
+   and compute the keys that need to be inserted into the index.
+   The function must return a palloc'd struct containing statistics about
+   the new index.
+  </p><p>
+</p><pre class="programlisting">
+void
+ambuildempty (Relation indexRelation);
+</pre><p>
+   Build an empty index, and write it to the initialization fork (<code class="symbol">INIT_FORKNUM</code>)
+   of the given relation.  This method is called only for unlogged indexes; the
+   empty index written to the initialization fork will be copied over the main
+   relation fork on each server restart.
+  </p><p>
+</p><pre class="programlisting">
+bool
+aminsert (Relation indexRelation,
+          Datum *values,
+          bool *isnull,
+          ItemPointer heap_tid,
+          Relation heapRelation,
+          IndexUniqueCheck checkUnique,
+          bool indexUnchanged,
+          IndexInfo *indexInfo);
+</pre><p>
+   Insert a new tuple into an existing index.  The <code class="literal">values</code> and
+   <code class="literal">isnull</code> arrays give the key values to be indexed, and
+   <code class="literal">heap_tid</code> is the TID to be indexed.
+   If the access method supports unique indexes (its
+   <code class="structfield">amcanunique</code> flag is true) then
+   <code class="literal">checkUnique</code> indicates the type of uniqueness check to
+   perform.  This varies depending on whether the unique constraint is
+   deferrable; see <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a> for details.
+   Normally the access method only needs the <code class="literal">heapRelation</code>
+   parameter when performing uniqueness checking (since then it will have to
+   look into the heap to verify tuple liveness).
+  </p><p>
+   The <code class="literal">indexUnchanged</code> Boolean value gives a hint
+   about the nature of the tuple to be indexed.  When it is true,
+   the tuple is a duplicate of some existing tuple in the index.  The
+   new tuple is a logically unchanged successor MVCC tuple version.  This
+   happens when an <code class="command">UPDATE</code> takes place that does not
+   modify any columns covered by the index, but nevertheless requires a
+   new version in the index.  The index AM may use this hint to decide
+   to apply bottom-up index deletion in parts of the index where many
+   versions of the same logical row accumulate.  Note that updating a non-key
+   column or a column that only appears in a partial index predicate does not
+   affect the value of <code class="literal">indexUnchanged</code>.  The core code
+   determines each tuple's <code class="literal">indexUnchanged</code> value using a low
+   overhead approach that allows both false positives and false negatives.
+   Index AMs must not treat <code class="literal">indexUnchanged</code> as an
+   authoritative source of information about tuple visibility or versioning.
+  </p><p>
+   The function's Boolean result value is significant only when
+   <code class="literal">checkUnique</code> is <code class="literal">UNIQUE_CHECK_PARTIAL</code>.
+   In this case a true result means the new entry is known unique, whereas
+   false means it might be non-unique (and a deferred uniqueness check must
+   be scheduled).  For other cases a constant false result is recommended.
+  </p><p>
+   Some indexes might not index all tuples.  If the tuple is not to be
+   indexed, <code class="function">aminsert</code> should just return without doing anything.
+  </p><p>
+   If the index AM wishes to cache data across successive index insertions
+   within an SQL statement, it can allocate space
+   in <code class="literal">indexInfo-&gt;ii_Context</code> and store a pointer to the
+   data in <code class="literal">indexInfo-&gt;ii_AmCache</code> (which will be NULL
+   initially).
+  </p><p>
+</p><pre class="programlisting">
+IndexBulkDeleteResult *
+ambulkdelete (IndexVacuumInfo *info,
+              IndexBulkDeleteResult *stats,
+              IndexBulkDeleteCallback callback,
+              void *callback_state);
+</pre><p>
+   Delete tuple(s) from the index.  This is a <span class="quote">“<span class="quote">bulk delete</span>”</span> operation
+   that is intended to be implemented by scanning the whole index and checking
+   each entry to see if it should be deleted.
+   The passed-in <code class="literal">callback</code> function must be called, in the style
+   <code class="literal">callback(<em class="replaceable"><code>TID</code></em>, callback_state) returns bool</code>,
+   to determine whether any particular index entry, as identified by its
+   referenced TID, is to be deleted.  Must return either NULL or a palloc'd
+   struct containing statistics about the effects of the deletion operation.
+   It is OK to return NULL if no information needs to be passed on to
+   <code class="function">amvacuumcleanup</code>.
+  </p><p>
+   Because of limited <code class="varname">maintenance_work_mem</code>,
+   <code class="function">ambulkdelete</code> might need to be called more than once when many
+   tuples are to be deleted.  The <code class="literal">stats</code> argument is the result
+   of the previous call for this index (it is NULL for the first call within a
+   <code class="command">VACUUM</code> operation).  This allows the AM to accumulate statistics
+   across the whole operation.  Typically, <code class="function">ambulkdelete</code> will
+   modify and return the same struct if the passed <code class="literal">stats</code> is not
+   null.
+  </p><p>
+</p><pre class="programlisting">
+IndexBulkDeleteResult *
+amvacuumcleanup (IndexVacuumInfo *info,
+                 IndexBulkDeleteResult *stats);
+</pre><p>
+   Clean up after a <code class="command">VACUUM</code> operation (zero or more
+   <code class="function">ambulkdelete</code> calls).  This does not have to do anything
+   beyond returning index statistics, but it might perform bulk cleanup
+   such as reclaiming empty index pages.  <code class="literal">stats</code> is whatever the
+   last <code class="function">ambulkdelete</code> call returned, or NULL if
+   <code class="function">ambulkdelete</code> was not called because no tuples needed to be
+   deleted.  If the result is not NULL it must be a palloc'd struct.
+   The statistics it contains will be used to update <code class="structname">pg_class</code>,
+   and will be reported by <code class="command">VACUUM</code> if <code class="literal">VERBOSE</code> is given.
+   It is OK to return NULL if the index was not changed at all during the
+   <code class="command">VACUUM</code> operation, but otherwise correct stats should
+   be returned.
+  </p><p>
+   <code class="function">amvacuumcleanup</code> will also be called at completion of an
+   <code class="command">ANALYZE</code> operation.  In this case <code class="literal">stats</code> is always
+   NULL and any return value will be ignored.  This case can be distinguished
+   by checking <code class="literal">info-&gt;analyze_only</code>.  It is recommended
+   that the access method do nothing except post-insert cleanup in such a
+   call, and that only in an autovacuum worker process.
+  </p><p>
+</p><pre class="programlisting">
+bool
+amcanreturn (Relation indexRelation, int attno);
+</pre><p>
+   Check whether the index can support <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes"><em class="firstterm">index-only scans</em></a> on
+   the given column, by returning the column's original indexed value.
+   The attribute number is 1-based, i.e., the first column's attno is 1.
+   Returns true if supported, else false.
+   This function should always return true for included columns
+   (if those are supported), since there's little point in an included
+   column that can't be retrieved.
+   If the access method does not support index-only scans at all,
+   the <code class="structfield">amcanreturn</code> field in its <code class="structname">IndexAmRoutine</code>
+   struct can be set to NULL.
+  </p><p>
+</p><pre class="programlisting">
+void
+amcostestimate (PlannerInfo *root,
+                IndexPath *path,
+                double loop_count,
+                Cost *indexStartupCost,
+                Cost *indexTotalCost,
+                Selectivity *indexSelectivity,
+                double *indexCorrelation,
+                double *indexPages);
+</pre><p>
+   Estimate the costs of an index scan.  This function is described fully
+   in <a class="xref" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Section 64.6</a>, below.
+  </p><p>
+</p><pre class="programlisting">
+bytea *
+amoptions (ArrayType *reloptions,
+           bool validate);
+</pre><p>
+   Parse and validate the reloptions array for an index.  This is called only
+   when a non-null reloptions array exists for the index.
+   <em class="parameter"><code>reloptions</code></em> is a <code class="type">text</code> array containing entries of the
+   form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em>.
+   The function should construct a <code class="type">bytea</code> value, which will be copied
+   into the <code class="structfield">rd_options</code> field of the index's relcache entry.
+   The data contents of the <code class="type">bytea</code> value are open for the access
+   method to define; most of the standard access methods use struct
+   <code class="structname">StdRdOptions</code>.
+   When <em class="parameter"><code>validate</code></em> is true, the function should report a suitable
+   error message if any of the options are unrecognized or have invalid
+   values; when <em class="parameter"><code>validate</code></em> is false, invalid entries should be
+   silently ignored.  (<em class="parameter"><code>validate</code></em> is false when loading options
+   already stored in <code class="structname">pg_catalog</code>; an invalid entry could only
+   be found if the access method has changed its rules for options, and in
+   that case ignoring obsolete entries is appropriate.)
+   It is OK to return NULL if default behavior is wanted.
+  </p><p>
+</p><pre class="programlisting">
+bool
+amproperty (Oid index_oid, int attno,
+            IndexAMProperty prop, const char *propname,
+            bool *res, bool *isnull);
+</pre><p>
+   The <code class="function">amproperty</code> method allows index access methods to override
+   the default behavior of <code class="function">pg_index_column_has_property</code>
+   and related functions.
+   If the access method does not have any special behavior for index property
+   inquiries, the <code class="structfield">amproperty</code> field in
+   its <code class="structname">IndexAmRoutine</code> struct can be set to NULL.
+   Otherwise, the <code class="function">amproperty</code> method will be called with
+   <em class="parameter"><code>index_oid</code></em> and <em class="parameter"><code>attno</code></em> both zero for
+   <code class="function">pg_indexam_has_property</code> calls,
+   or with <em class="parameter"><code>index_oid</code></em> valid and <em class="parameter"><code>attno</code></em> zero for
+   <code class="function">pg_index_has_property</code> calls,
+   or with <em class="parameter"><code>index_oid</code></em> valid and <em class="parameter"><code>attno</code></em> greater than
+   zero for <code class="function">pg_index_column_has_property</code> calls.
+   <em class="parameter"><code>prop</code></em> is an enum value identifying the property being tested,
+   while <em class="parameter"><code>propname</code></em> is the original property name string.
+   If the core code does not recognize the property name
+   then <em class="parameter"><code>prop</code></em> is <code class="literal">AMPROP_UNKNOWN</code>.
+   Access methods can define custom property names by
+   checking <em class="parameter"><code>propname</code></em> for a match (use <code class="function">pg_strcasecmp</code>
+   to match, for consistency with the core code); for names known to the core
+   code, it's better to inspect <em class="parameter"><code>prop</code></em>.
+   If the <code class="structfield">amproperty</code> method returns <code class="literal">true</code> then
+   it has determined the property test result: it must set <code class="literal">*res</code>
+   to the Boolean value to return, or set <code class="literal">*isnull</code>
+   to <code class="literal">true</code> to return a NULL.  (Both of the referenced variables
+   are initialized to <code class="literal">false</code> before the call.)
+   If the <code class="structfield">amproperty</code> method returns <code class="literal">false</code> then
+   the core code will proceed with its normal logic for determining the
+   property test result.
+  </p><p>
+   Access methods that support ordering operators should
+   implement <code class="literal">AMPROP_DISTANCE_ORDERABLE</code> property testing, as the
+   core code does not know how to do that and will return NULL.  It may
+   also be advantageous to implement <code class="literal">AMPROP_RETURNABLE</code> testing,
+   if that can be done more cheaply than by opening the index and calling
+   <code class="function">amcanreturn</code>, which is the core code's default behavior.
+   The default behavior should be satisfactory for all other standard
+   properties.
+  </p><p>
+</p><pre class="programlisting">
+char *
+ambuildphasename (int64 phasenum);
+</pre><p>
+   Return the textual name of the given build phase number.
+   The phase numbers are those reported during an index build via the
+   <code class="function">pgstat_progress_update_param</code> interface.
+   The phase names are then exposed in the
+   <code class="structname">pg_stat_progress_create_index</code> view.
+  </p><p>
+</p><pre class="programlisting">
+bool
+amvalidate (Oid opclassoid);
+</pre><p>
+   Validate the catalog entries for the specified operator class, so far as
+   the access method can reasonably do that.  For example, this might include
+   testing that all required support functions are provided.
+   The <code class="function">amvalidate</code> function must return false if the opclass is
+   invalid.  Problems should be reported with <code class="function">ereport</code>
+   messages, typically at <code class="literal">INFO</code> level.
+  </p><p>
+</p><pre class="programlisting">
+void
+amadjustmembers (Oid opfamilyoid,
+                 Oid opclassoid,
+                 List *operators,
+                 List *functions);
+</pre><p>
+   Validate proposed new operator and function members of an operator family,
+   so far as the access method can reasonably do that, and set their
+   dependency types if the default is not satisfactory.  This is called
+   during <code class="command">CREATE OPERATOR CLASS</code> and during
+   <code class="command">ALTER OPERATOR FAMILY ADD</code>; in the latter
+   case <em class="parameter"><code>opclassoid</code></em> is <code class="literal">InvalidOid</code>.
+   The <code class="type">List</code> arguments are lists
+   of <code class="structname">OpFamilyMember</code> structs, as defined
+   in <code class="filename">amapi.h</code>.
+
+   Tests done by this function will typically be a subset of those
+   performed by <code class="function">amvalidate</code>,
+   since <code class="function">amadjustmembers</code> cannot assume that it is
+   seeing a complete set of members.  For example, it would be reasonable
+   to check the signature of a support function, but not to check whether
+   all required support functions are provided.  Any problems can be
+   reported by throwing an error.
+
+   The dependency-related fields of
+   the <code class="structname">OpFamilyMember</code> structs are initialized by
+   the core code to create hard dependencies on the opclass if this
+   is <code class="command">CREATE OPERATOR CLASS</code>, or soft dependencies on the
+   opfamily if this is <code class="command">ALTER OPERATOR FAMILY ADD</code>.
+   <code class="function">amadjustmembers</code> can adjust these fields if some other
+   behavior is more appropriate.  For example, GIN, GiST, and SP-GiST
+   always set operator members to have soft dependencies on the opfamily,
+   since the connection between an operator and an opclass is relatively
+   weak in these index types; so it is reasonable to allow operator members
+   to be added and removed freely.  Optional support functions are typically
+   also given soft dependencies, so that they can be removed if necessary.
+  </p><p>
+   The purpose of an index, of course, is to support scans for tuples matching
+   an indexable <code class="literal">WHERE</code> condition, often called a
+   <em class="firstterm">qualifier</em> or <em class="firstterm">scan key</em>.  The semantics of
+   index scanning are described more fully in <a class="xref" href="index-scanning.html" title="64.3. Index Scanning">Section 64.3</a>,
+   below.  An index access method can support <span class="quote">“<span class="quote">plain</span>”</span> index scans,
+   <span class="quote">“<span class="quote">bitmap</span>”</span> index scans, or both.  The scan-related functions that an
+   index access method must or may provide are:
+  </p><p>
+</p><pre class="programlisting">
+IndexScanDesc
+ambeginscan (Relation indexRelation,
+             int nkeys,
+             int norderbys);
+</pre><p>
+   Prepare for an index scan.  The <code class="literal">nkeys</code> and <code class="literal">norderbys</code>
+   parameters indicate the number of quals and ordering operators that will be
+   used in the scan; these may be useful for space allocation purposes.
+   Note that the actual values of the scan keys aren't provided yet.
+   The result must be a palloc'd struct.
+   For implementation reasons the index access method
+   <span class="emphasis"><em>must</em></span> create this struct by calling
+   <code class="function">RelationGetIndexScan()</code>.  In most cases
+   <code class="function">ambeginscan</code> does little beyond making that call and perhaps
+   acquiring locks;
+   the interesting parts of index-scan startup are in <code class="function">amrescan</code>.
+  </p><p>
+</p><pre class="programlisting">
+void
+amrescan (IndexScanDesc scan,
+          ScanKey keys,
+          int nkeys,
+          ScanKey orderbys,
+          int norderbys);
+</pre><p>
+   Start or restart an index scan, possibly with new scan keys.  (To restart
+   using previously-passed keys, NULL is passed for <code class="literal">keys</code> and/or
+   <code class="literal">orderbys</code>.)  Note that it is not allowed for
+   the number of keys or order-by operators to be larger than
+   what was passed to <code class="function">ambeginscan</code>.  In practice the restart
+   feature is used when a new outer tuple is selected by a nested-loop join
+   and so a new key comparison value is needed, but the scan key structure
+   remains the same.
+  </p><p>
+</p><pre class="programlisting">
+bool
+amgettuple (IndexScanDesc scan,
+            ScanDirection direction);
+</pre><p>
+   Fetch the next tuple in the given scan, moving in the given
+   direction (forward or backward in the index).  Returns true if a tuple was
+   obtained, false if no matching tuples remain.  In the true case the tuple
+   TID is stored into the <code class="literal">scan</code> structure.  Note that
+   <span class="quote">“<span class="quote">success</span>”</span> means only that the index contains an entry that matches
+   the scan keys, not that the tuple necessarily still exists in the heap or
+   will pass the caller's snapshot test.  On success, <code class="function">amgettuple</code>
+   must also set <code class="literal">scan-&gt;xs_recheck</code> to true or false.
+   False means it is certain that the index entry matches the scan keys.
+   True means this is not certain, and the conditions represented by the
+   scan keys must be rechecked against the heap tuple after fetching it.
+   This provision supports <span class="quote">“<span class="quote">lossy</span>”</span> index operators.
+   Note that rechecking will extend only to the scan conditions; a partial
+   index predicate (if any) is never rechecked by <code class="function">amgettuple</code>
+   callers.
+  </p><p>
+   If the index supports <a class="link" href="indexes-index-only-scans.html" title="11.9. Index-Only Scans and Covering Indexes">index-only
+   scans</a> (i.e., <code class="function">amcanreturn</code> returns true for any
+   of its columns),
+   then on success the AM must also check <code class="literal">scan-&gt;xs_want_itup</code>,
+   and if that is true it must return the originally indexed data for the
+   index entry.  Columns for which <code class="function">amcanreturn</code> returns
+   false can be returned as nulls.
+   The data can be returned in the form of an
+   <code class="structname">IndexTuple</code> pointer stored at <code class="literal">scan-&gt;xs_itup</code>,
+   with tuple descriptor <code class="literal">scan-&gt;xs_itupdesc</code>; or in the form of
+   a <code class="structname">HeapTuple</code> pointer stored at <code class="literal">scan-&gt;xs_hitup</code>,
+   with tuple descriptor <code class="literal">scan-&gt;xs_hitupdesc</code>.  (The latter
+   format should be used when reconstructing data that might possibly not fit
+   into an <code class="structname">IndexTuple</code>.)  In either case,
+   management of the data referenced by the pointer is the access method's
+   responsibility.  The data must remain good at least until the next
+   <code class="function">amgettuple</code>, <code class="function">amrescan</code>, or <code class="function">amendscan</code>
+   call for the scan.
+  </p><p>
+   The <code class="function">amgettuple</code> function need only be provided if the access
+   method supports <span class="quote">“<span class="quote">plain</span>”</span> index scans.  If it doesn't, the
+   <code class="structfield">amgettuple</code> field in its <code class="structname">IndexAmRoutine</code>
+   struct must be set to NULL.
+  </p><p>
+</p><pre class="programlisting">
+int64
+amgetbitmap (IndexScanDesc scan,
+             TIDBitmap *tbm);
+</pre><p>
+   Fetch all tuples in the given scan and add them to the caller-supplied
+   <code class="type">TIDBitmap</code> (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, <code class="function">amgetbitmap</code> can
+   indicate that rechecking of the scan conditions is required for specific
+   tuple IDs.  This is analogous to the <code class="literal">xs_recheck</code> output parameter
+   of <code class="function">amgettuple</code>.  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.
+   <code class="function">amgetbitmap</code> and
+   <code class="function">amgettuple</code> cannot be used in the same index scan; there
+   are other restrictions too when using <code class="function">amgetbitmap</code>, as explained
+   in <a class="xref" href="index-scanning.html" title="64.3. Index Scanning">Section 64.3</a>.
+  </p><p>
+   The <code class="function">amgetbitmap</code> function need only be provided if the access
+   method supports <span class="quote">“<span class="quote">bitmap</span>”</span> index scans.  If it doesn't, the
+   <code class="structfield">amgetbitmap</code> field in its <code class="structname">IndexAmRoutine</code>
+   struct must be set to NULL.
+  </p><p>
+</p><pre class="programlisting">
+void
+amendscan (IndexScanDesc scan);
+</pre><p>
+   End a scan and release resources.  The <code class="literal">scan</code> 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 <code class="function">ambeginscan</code> and other scan-related functions.
+  </p><p>
+</p><pre class="programlisting">
+void
+ammarkpos (IndexScanDesc scan);
+</pre><p>
+   Mark current scan position.  The access method need only support one
+   remembered scan position per scan.
+  </p><p>
+   The <code class="function">ammarkpos</code> function need only be provided if the access
+   method supports ordered scans.  If it doesn't,
+   the <code class="structfield">ammarkpos</code> field in its <code class="structname">IndexAmRoutine</code>
+   struct may be set to NULL.
+  </p><p>
+</p><pre class="programlisting">
+void
+amrestrpos (IndexScanDesc scan);
+</pre><p>
+   Restore the scan to the most recently marked position.
+  </p><p>
+   The <code class="function">amrestrpos</code> function need only be provided if the access
+   method supports ordered scans.  If it doesn't,
+   the <code class="structfield">amrestrpos</code> field in its <code class="structname">IndexAmRoutine</code>
+   struct may be set to NULL.
+  </p><p>
+   In addition to supporting ordinary index scans, some types of index
+   may wish to support <em class="firstterm">parallel index scans</em>, 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 each
+   cooperating backend must match the requested ordering.  The following
+   functions may be implemented to support parallel index scans:
+  </p><p>
+</p><pre class="programlisting">
+Size
+amestimateparallelscan (void);
+</pre><p>
+   Estimate and return the number of bytes of dynamic shared memory which
+   the access method will be needed to perform a parallel scan.  (This number
+   is in addition to, not in lieu of, the amount of space needed for
+   AM-independent data in <code class="structname">ParallelIndexScanDescData</code>.)
+  </p><p>
+   It is not necessary to implement this function for access methods which
+   do not support parallel scans or for which the number of additional bytes
+   of storage required is zero.
+  </p><p>
+</p><pre class="programlisting">
+void
+aminitparallelscan (void *target);
+</pre><p>
+   This function will be called to initialize dynamic shared memory at the
+   beginning of a parallel scan.  <em class="parameter"><code>target</code></em> will point to at least
+   the number of bytes previously returned by
+   <code class="function">amestimateparallelscan</code>, and this function may use that
+   amount of space to store whatever data it wishes.
+  </p><p>
+   It is not necessary to implement this function for access methods which
+   do not support parallel scans or in cases where the shared memory space
+   required needs no initialization.
+  </p><p>
+</p><pre class="programlisting">
+void
+amparallelrescan (IndexScanDesc scan);
+</pre><p>
+   This function, if implemented, will be called when a parallel index scan
+   must be restarted.  It should reset any shared state set up by
+   <code class="function">aminitparallelscan</code> such that the scan will be restarted from
+   the beginning.
+  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-api.html" title="64.1. Basic API Structure for Indexes">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-scanning.html" title="64.3. Index Scanning">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.1. Basic API Structure for Indexes </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.3. Index Scanning</td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
commit	293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree	fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/index-functions.html
parent	Initial commit. (diff)
download	postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip