Home Explore Blog CI



postgresql

6th chunk of `doc/src/sgml/indexam.sgml`
31f181143892d19caa51437e2b8ef8dd8ad340a1cf3eb1a50000000100000fa9
 system will attempt to allocate parallel workers for the build.
   Access methods supporting only non-parallel index builds should leave
   this flag set to <literal>false</literal>.
  </para>

  <para>
<programlisting>
void
ambuildempty (Relation indexRelation);
</programlisting>
   Build an empty index, and write it to the initialization fork (<symbol>INIT_FORKNUM</symbol>)
   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.
  </para>

  <para>
<programlisting>
bool
aminsert (Relation indexRelation,
          Datum *values,
          bool *isnull,
          ItemPointer heap_tid,
          Relation heapRelation,
          IndexUniqueCheck checkUnique,
          bool indexUnchanged,
          IndexInfo *indexInfo);
</programlisting>
   Insert a new tuple into an existing index.  The <literal>values</literal> and
   <literal>isnull</literal> arrays give the key values to be indexed, and
   <literal>heap_tid</literal> is the TID to be indexed.
   If the access method supports unique indexes (its
   <structfield>amcanunique</structfield> flag is true) then
   <literal>checkUnique</literal> indicates the type of uniqueness check to
   perform.  This varies depending on whether the unique constraint is
   deferrable; see <xref linkend="index-unique-checks"/> for details.
   Normally the access method only needs the <literal>heapRelation</literal>
   parameter when performing uniqueness checking (since then it will have to
   look into the heap to verify tuple liveness).
  </para>

  <para>
   The <literal>indexUnchanged</literal> 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 <command>UPDATE</command> 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 <literal>indexUnchanged</literal>.  The core code
   determines each tuple's <literal>indexUnchanged</literal> value using a low
   overhead approach that allows both false positives and false negatives.
   Index AMs must not treat <literal>indexUnchanged</literal> as an
   authoritative source of information about tuple visibility or versioning.
  </para>

  <para>
   The function's Boolean result value is significant only when
   <literal>checkUnique</literal> is <literal>UNIQUE_CHECK_PARTIAL</literal>.
   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.
  </para>

  <para>
   Some indexes might not index all tuples.  If the tuple is not to be
   indexed, <function>aminsert</function> should just return without doing anything.
  </para>

  <para>
   If the index AM wishes to cache data across successive index insertions
   within an SQL statement, it can allocate space
   in <literal>indexInfo-&gt;ii_Context</literal> and store a pointer to the
   data in <literal>indexInfo-&gt;ii_AmCache</literal> (which will be NULL
   initially).  If resources other than memory have to be released after
   index insertions, <function>aminsertcleanup</function> may be provided,
   which will be called before the memory is released.
  </para>

  <para>
<programlisting>
void
aminsertcleanup (Relation indexRelation,
                 IndexInfo *indexInfo);
</programlisting>
   Clean up state that was maintained across successive

Title: Index Access Method Functions: ambuildempty and aminsert
Summary
ambuildempty builds an empty index in the initialization fork for unlogged indexes, which is copied on server restart. aminsert inserts a tuple into an index, using values, isnull, and heap_tid. It handles unique indexes with checkUnique, and utilizes heapRelation for checking tuple liveness. indexUnchanged indicates if the tuple is a duplicate, aiding bottom-up index deletion. The boolean result of aminsert is significant when checkUnique is UNIQUE_CHECK_PARTIAL, indicating uniqueness status. Not all tuples may be indexed, and aminsert should return without action if a tuple isn't to be indexed. Index AM can cache data via indexInfo->ii_Context and indexInfo->ii_AmCache, with aminsertcleanup for releasing resources.