SPI_MODIFYTUPLE(3)

💅 SPI_MODIFYTUPLE(3) — the PostgreSQL glow-up page ✨

okay bestie, welcome to SPI_MODIFYTUPLE(3) from the PostgreSQL 17.11 docs — like, yes it's a C function page, but it's actually iconic once you get it 🫶

---

🌸 NAME 🌸

SPI_modifytuple — makes a whole new row by swapping out the fields you pick from a row you already have 👑

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

So SPI_modifytuple creates a new row by substituting new values into selected columns, and it copies over the original row's columns everywhere else. The way it just... leaves the input row alone? respectful. untouched. not modified. periodt 💅 The new row comes back to you in the upper executor context.

⚠️ Big caveat, no cap: this function can only be used while connected to SPI. If you're not connected, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. it's giving "you must be this tall to ride" 🎢

🎀 ARGUMENTS 🎀

• Relation rel — literally only used as the source of the row descriptor for the row. ngl the docs themselves call passing a relation instead of a row descriptor a misfeature 💀 so like. know that going in 🙈
• HeapTuple row — the row you're gonna modify ✨
• int ncols — how many columns you're changing 🔢
• int * colnum — an array of length ncols holding the numbers of the columns to be changed. heads up: column numbers start at 1 🌟
• Datum * values — an array of length ncols with the new values for those specified columns 💖
• const char * nulls — an array of length ncols that describes which of your 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 that null case, the actual value sitting in the corresponding values entry doesn't matter at all — it's giving decorative 🎀) Also important: nulls is not a text string, it's just an array, so it does not need a '\0' terminator 🚫

🌈 RETURN VALUE 🌈

A new row with your modifications, allocated in the upper executor context — or NULL on error (peep SPI_result for the error indication 👀).

On error, SPI_result gets set like this:

• 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. basically if anything's missing, she's not doing it 💀
• 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 😭

---

and that's the whole page bestie, you ate that 🍓 — this was SPI_MODIFYTUPLE(3) from the PostgreSQL 17.11 documentation, dated 2026. go be the main character of your own query planner 👑💜