Home • Explore • Blog • CI
☰



postgresql
45th chunk of `doc/src/sgml/spi.sgml`
046cf36e886de875e4d10d8407eac82e444718517362ab5d0000000100000fa2
 </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   <type>HeapTupleHeader</type> pointing to copied row,
   or <symbol>NULL</symbol> on error
   (see <varname>SPI_result</varname> for an error indication)
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-modifytuple">
 <indexterm><primary>SPI_modifytuple</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_modifytuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_modifytuple</refname>
  <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parameter>row</parameter>, int <parameter>ncols</parameter>,
                          int * <parameter>colnum</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_modifytuple</function> creates a new row by
   substituting new values for selected columns, copying the original
   row's columns at other positions.  The input row is not modified.
   The new row is returned in the upper executor context.
  </para>

  <para>
   This function can only be used while connected to SPI.
   Otherwise, it returns NULL and sets <varname>SPI_result</varname> to
   <symbol>SPI_ERROR_UNCONNECTED</symbol>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      Used only as the source of the row descriptor for the row.
      (Passing a relation rather than a row descriptor is a
      misfeature.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      row to be modified
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>ncols</parameter></literal></term>
    <listitem>
     <para>
      number of columns to be changed
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int * <parameter>colnum</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, containing the numbers
      of the columns that are to be changed (column numbers start at 1)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, containing the
      new values for the specified columns
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, describing which
      new values are null
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_modifytuple</function> assumes that no new values
      are null.  Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding new value is
      non-null, or <literal>'n'</literal> if the corresponding new value is
      null.  (In the latter case, the actual value in the corresponding
      <parameter>values</parameter> entry doesn't matter.)  Note that
      <parameter>nulls</parameter> is not a text string, just an array: it
      does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   new row with modifications, allocated in the upper
Title: SPI_modifytuple: Creating a Modified Row in SPI
Summary
This section details the `SPI_modifytuple` function, which constructs a new row by substituting specified column values in an existing row, while copying other columns from the original. It takes the relation, the row to be modified, the number of columns to change, arrays of column numbers and new values, and a nulls array indicating null values. The original row remains unchanged, and the newly created row is allocated in the upper executor context. It also requires a connection to SPI; otherwise, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED.