SPI_MODIFYTUPLE(3)

💖 SPI_modifytuple 💖

okay bestie, welcome to the SPI_modifytuple(3) page from the PostgreSQL 13.23 Documentation. This one is literally about making a new row by swapping out selected fields of an existing row — and yes, the original row stays untouched. Main character energy: the new row gets returned in the upper executor context. Periodt. ✨

---

🎀 NAME 🎀

SPI_modifytuple — create a row by replacing selected fields of a given row 💅

---

✨ SYNOPSIS ✨

HeapTuple SPI_modifytuple(Relation rel, HeapTuple row, int ncols,
                                 int * colnum, Datum * values, const char * nulls)

---

🌸 DESCRIPTION 🌸

So the way this works: SPI_modifytuple creates a brand-new row by substituting new values for selected columns, and it copies the original row’s columns at the other positions. The input row is not modified — no cap. The new row is returned in the upper executor context. 🫶

This function can only be used while connected to SPI. Otherwise, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. That’s the vibe check, bestie. 😭

---

🦋 ARGUMENTS 🦋

• Relation rel — used only as the source of the row descriptor for the row. Passing a relation rather than a row descriptor is a misfeature. (I don’t make the rules 💀)
• HeapTuple row — row to be modified.
• int ncols — number of columns to be changed.
• int * colnum — an array of length ncols, containing the numbers of the columns that are to be changed (column numbers start at 1).
• Datum * values — an array of length ncols, containing the new values for the specified columns.
• const char * nulls — an array of length ncols, describing which new values are null.

If nulls is NULL then SPI_modifytuple assumes that no new values are null. Otherwise, each entry of the nulls array should be ' ' if the corresponding new value is non-null, or 'n' if the corresponding new value is null. (In the latter case, the actual value in the corresponding values entry doesn’t matter.) Note that nulls is not a text string, just an array: it does not need a '\0' terminator. 🧚

---

👑 RETURN VALUE 👑

New row with modifications, allocated in the upper executor context, or NULL on error (see SPI_result for an error indication).

On error, SPI_result is set as follows:

• SPI_ERROR_ARGUMENT — if rel is NULL, or if row is NULL, or if ncols is less than or equal to 0, or if colnum is NULL, or if values is NULL.
• SPI_ERROR_NOATTRIBUTE — if colnum contains an invalid column number (less than or equal to 0 or greater than the number of columns in row).
• SPI_ERROR_UNCONNECTED — if SPI is not active.

---

sign-off era: brought to you by PostgreSQL 13.23, dated 2025 — this page ate, no crumbs 💅✨💖