diff --git a/src/current/_includes/v25.2/known-limitations/plpgsql-limitations.md b/src/current/_includes/v25.2/known-limitations/plpgsql-limitations.md index 83e47a0bdaa..c17954748a0 100644 --- a/src/current/_includes/v25.2/known-limitations/plpgsql-limitations.md +++ b/src/current/_includes/v25.2/known-limitations/plpgsql-limitations.md @@ -5,7 +5,6 @@ - PL/pgSQL arguments cannot be referenced with ordinals (e.g., `$1`, `$2`). [#114701](https://github.com/cockroachdb/cockroach/issues/114701) - The following statements are not supported: - `FOR` cursor loops, `FOR` query loops, and `FOREACH` loops. [#105246](https://github.com/cockroachdb/cockroach/issues/105246) - - `RETURN NEXT` and `RETURN QUERY`. [#117744](https://github.com/cockroachdb/cockroach/issues/117744) - `PERFORM`, `EXECUTE`, `GET DIAGNOSTICS`, and `CASE`. [#117744](https://github.com/cockroachdb/cockroach/issues/117744) - PL/pgSQL exception blocks cannot catch [transaction retry errors]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}). [#111446](https://github.com/cockroachdb/cockroach/issues/111446) - `RAISE` statements cannot be annotated with names of schema objects related to the error (i.e., using `COLUMN`, `CONSTRAINT`, `DATATYPE`, `TABLE`, or `SCHEMA`). [#106237](https://github.com/cockroachdb/cockroach/issues/106237) diff --git a/src/current/v25.2/plpgsql.md b/src/current/v25.2/plpgsql.md index 01e735f4d96..c818fefe1bb 100644 --- a/src/current/v25.2/plpgsql.md +++ b/src/current/v25.2/plpgsql.md @@ -343,7 +343,7 @@ CREATE PROCEDURE p() AS $$ #### `RETURN` -Add a `RETURN` statement to a routine with an `OUT` parameter or `VOID` return type to exit the routine immediately. +Add a `RETURN` statement to a routine with an `OUT` parameter, `RETURNS VOID` clause, or `RETURNS SETOF` clause to exit the routine immediately. ~~~ sql BEGIN @@ -351,6 +351,55 @@ BEGIN RETURN; ~~~ +Add a `RETURN` statement in a scalar-returning function to return the result of an expression. + +The following example uses `RETURN` to return the square of the input argument. + +{% include_cached copy-clipboard.html %} +~~~ sql +CREATE FUNCTION square(x INT) RETURNS INT AS $$ +BEGIN + RETURN x * x; +END; +$$ LANGUAGE PLpgSQL; +~~~ + +#### `RETURN NEXT` and `RETURN QUERY` + +Add `RETURN NEXT` or `RETURN QUERY` statements to a [set-returning function]({% link {{ page.version.version }}/create-function.md %}#create-a-function-that-returns-a-set-of-results) to append rows to the result set. You can combine `RETURN NEXT` and `RETURN QUERY` statements in a single function to build the result set. + +Use `RETURN NEXT` within a set-returning function to append a row to the result set. + +In the following example, `RETURN NEXT` returns a new row during each loop iteration. + +{% include_cached copy-clipboard.html %} +~~~ sql +CREATE FUNCTION get_numbers() RETURNS SETOF INT AS $$ +DECLARE + i INT := 1; +BEGIN + WHILE i <= 5 LOOP + RETURN NEXT i; + i := i + 1; + END LOOP; +END +$$ LANGUAGE PLpgSQL; +~~~ + +Use `RETURN QUERY` within a set-returning function to append the results of a SQL query to the result set. + +In the following example, `RETURN QUERY` returns all qualifying rows from the `SELECT` query. + +{% include_cached copy-clipboard.html %} +~~~ sql +CREATE FUNCTION get_even_numbers() RETURNS SETOF INT AS $$ +BEGIN + RETURN QUERY + SELECT i FROM generate_series(1, 10) AS i WHERE i % 2 = 0; +END +$$ LANGUAGE PLpgSQL; +~~~ + #### `CONTINUE` Add a `CONTINUE` statement to end the current iteration of a [loop](#write-loops), skipping any statements below `CONTINUE` and beginning the next iteration of the loop.