Home Explore Blog CI



postgresql

11th chunk of `doc/src/sgml/fdwhandler.sgml`
b112436fb1315a8c8110a1aa9ef6f8a37bb8227a85b7c8850000000100000fac
 The data in the returned slot is used only if the <command>INSERT</command>
     statement involves a view
     <literal>WITH CHECK OPTION</literal>; or if the foreign table has
     an <literal>AFTER ROW</literal> trigger.  Triggers require all columns,
     but the FDW could choose to optimize away returning some or all columns
     depending on the contents of the
     <literal>WITH CHECK OPTION</literal> constraints.
    </para>

    <para>
     If the <function>ExecForeignBatchInsert</function> or
     <function>GetForeignModifyBatchSize</function> pointer is set to
     <literal>NULL</literal>, attempts to insert into the foreign table will
     use <function>ExecForeignInsert</function>.
     This function is not used if the <command>INSERT</command> has the
     <literal>RETURNING</literal> clause.
    </para>

    <para>
     Note that this function is also called when inserting routed tuples into
     a foreign-table partition or executing <command>COPY FROM</command> on
     a foreign table, in which case it is called in a different way than it
     is in the <command>INSERT</command> case.  See the callback functions
     described below that allow the FDW to support that.
    </para>

    <para>
<programlisting>
int
GetForeignModifyBatchSize(ResultRelInfo *rinfo);
</programlisting>

     Report the maximum number of tuples that a single
     <function>ExecForeignBatchInsert</function> call can handle for
     the specified foreign table.  The executor passes at most
     the given number of tuples to <function>ExecForeignBatchInsert</function>.
     <literal>rinfo</literal> is the <structname>ResultRelInfo</structname> struct describing
     the target foreign table.
     The FDW is expected to provide a foreign server and/or foreign
     table option for the user to set this value, or some hard-coded value.
    </para>

    <para>
     If the <function>ExecForeignBatchInsert</function> or
     <function>GetForeignModifyBatchSize</function> pointer is set to
     <literal>NULL</literal>, attempts to insert into the foreign table will
     use <function>ExecForeignInsert</function>.
    </para>

    <para>
<programlisting>
TupleTableSlot *
ExecForeignUpdate(EState *estate,
                  ResultRelInfo *rinfo,
                  TupleTableSlot *slot,
                  TupleTableSlot *planSlot);
</programlisting>

     Update one tuple in the foreign table.
     <literal>estate</literal> is global execution state for the query.
     <literal>rinfo</literal> is the <structname>ResultRelInfo</structname> struct describing
     the target foreign table.
     <literal>slot</literal> contains the new data for the tuple; it will match the
     row-type definition of the foreign table.
     <literal>planSlot</literal> contains the tuple that was generated by the
     <structname>ModifyTable</structname> plan node's subplan.  Unlike
     <literal>slot</literal>, this tuple contains only the new values for
     columns changed by the query, so do not rely on attribute numbers of the
     foreign table to index into <literal>planSlot</literal>.
     Also, <literal>planSlot</literal> typically contains
     additional <quote>junk</quote> columns.  In particular, any junk columns
     that were requested by <function>AddForeignUpdateTargets</function> will
     be available from this slot.
    </para>

    <para>
     The return value is either a slot containing the row as it was actually
     updated (this might differ from the data supplied, for example as a
     result of trigger actions), or NULL if no row was actually updated
     (again, typically as a result of triggers).  The passed-in
     <literal>slot</literal> can be re-used for this purpose.
    </para>

    <para>
     The data in the returned slot is used only if the <command>UPDATE</command>
     statement has a <literal>RETURNING</literal> clause or involves a view
     <literal>WITH CHECK OPTION</literal>; or if the foreign table has
     an <literal>AFTER ROW</literal>

Title: Foreign Table Update Routines: GetForeignModifyBatchSize and ExecForeignUpdate Details
Summary
This section elaborates on the behavior of `ExecForeignBatchInsert` when either it or `GetForeignModifyBatchSize` is NULL, defaulting to `ExecForeignInsert`, and its exclusion from `INSERT` statements with `RETURNING` clauses. It introduces `GetForeignModifyBatchSize`, which reports the maximum number of tuples a single `ExecForeignBatchInsert` call can handle, expecting the FDW to provide user-configurable options. If either this or `ExecForeignBatchInsert` are NULL, `ExecForeignInsert` is used. Finally, it details `ExecForeignUpdate`, which updates a tuple in the foreign table, using the `slot` for new data and `planSlot` for the subplan-generated tuple. It highlights the use of junk columns in `planSlot`. The function returns a slot with the updated row or NULL if no row was updated, which is used by `UPDATE` statements with `RETURNING` or views with `WITH CHECK OPTION`.