Why Functions returning SETOF in PostgreSQL? - Purpose & Use Cases

The Big Idea

What if you could get all matching data with one simple call, no matter how big your table is?

The Scenario

Imagine you have a big list of customer orders in a spreadsheet. You want to find all orders for a specific customer. Manually scanning through thousands of rows to pick out matching orders is tiring and slow.

The Problem

Manually filtering data means scrolling endlessly, risking mistakes like missing some orders or mixing up details. It's slow and frustrating, especially when the list updates often or grows larger.

The Solution

Functions returning SETOF let you write a small reusable piece of code that fetches all matching rows automatically. You just call the function with a customer ID, and it returns all their orders neatly, saving time and avoiding errors.

Before vs After

✗ Before

SELECT * FROM orders WHERE customer_id = 123;

✓ After

CREATE FUNCTION get_orders_for_customer(cust_id INT) RETURNS SETOF orders AS $$ SELECT * FROM orders WHERE customer_id = cust_id; $$ LANGUAGE sql; SELECT * FROM get_orders_for_customer(123);

What It Enables

This lets you package complex queries into simple calls that return multiple rows, making your database work smarter and faster.

Real Life Example

A sales manager can quickly get all orders for a client by calling a function, instead of writing long queries each time or manually searching through data.

Key Takeaways

Manual filtering of data is slow and error-prone.

Functions returning SETOF return multiple rows easily and cleanly.

This makes querying repetitive or complex data simple and reliable.

Practice

1.

What does a PostgreSQL function declared with RETURNS SETOF do?

easy

A. It returns multiple rows as a set of values.

B. It returns a single scalar value.

C. It returns a boolean indicating success or failure.

D. It returns a JSON object.

Solution

1. Step 1: Understand the meaning of RETURNS SETOF

   In PostgreSQL, RETURNS SETOF means the function returns multiple rows, not just one value.

2. Step 2: Compare with other return types

   Other return types like scalar or boolean return single values, not sets of rows.

3. Final Answer:

   It returns multiple rows as a set of values. -> Option A

4. Quick Check:

   RETURNS SETOF = multiple rows [OK]

Hint: SETOF means multiple rows, not one value [OK]

Common Mistakes:

• Thinking it returns a single value
• Confusing SETOF with JSON return
• Assuming it returns a boolean

2.

Which of the following is the correct syntax to declare a PostgreSQL function that returns a set of integers?

CREATE FUNCTION get_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN QUERY SELECT ...; END; $$ LANGUAGE plpgsql;

easy

A. CREATE FUNCTION get_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN 1; END; $$ LANGUAGE plpgsql;

B. CREATE FUNCTION get_numbers() RETURNS integer AS $$ BEGIN RETURN QUERY SELECT 1; END; $$ LANGUAGE plpgsql;

C. CREATE FUNCTION get_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN QUERY SELECT 1; END; $$ LANGUAGE plpgsql;

D. CREATE FUNCTION get_numbers() RETURNS TABLE(integer) AS $$ BEGIN RETURN QUERY SELECT 1; END; $$ LANGUAGE plpgsql;

Solution

1. Step 1: Check the correct RETURNS clause

   To return multiple rows of integers, use RETURNS SETOF integer.

2. Step 2: Use RETURN QUERY for sets

   Inside the function, RETURN QUERY SELECT ... returns multiple rows properly.

3. Final Answer:

   CREATE FUNCTION get_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN QUERY SELECT 1; END; $$ LANGUAGE plpgsql; -> Option C

4. Quick Check:

   RETURNS SETOF + RETURN QUERY = CREATE FUNCTION get_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN QUERY SELECT 1; END; $$ LANGUAGE plpgsql; [OK]

Hint: Use RETURNS SETOF and RETURN QUERY for multiple rows [OK]

Common Mistakes:

• Using RETURNS integer instead of SETOF integer
• Using RETURN instead of RETURN QUERY for sets
• Confusing RETURNS TABLE with RETURNS SETOF

3.

Given this function:

CREATE FUNCTION get_even_numbers() RETURNS SETOF integer AS $$ BEGIN RETURN QUERY SELECT generate_series(1,5) WHERE generate_series % 2 = 0; END; $$ LANGUAGE plpgsql;

What will SELECT * FROM get_even_numbers(); return?

medium

A. Empty set

B. [1, 3, 5]

C. [1, 2, 3, 4, 5]

D. [2, 4]

Solution

1. Step 1: Understand generate_series and filter

   The function selects numbers from 1 to 5 but filters only even numbers using WHERE generate_series % 2 = 0.

2. Step 2: Identify even numbers in range

   Even numbers between 1 and 5 are 2 and 4.

3. Final Answer:

   [2, 4] -> Option D

4. Quick Check:

   Even numbers 1-5 = [2,4] [OK]

Hint: Filter generate_series with modulo for evens [OK]

Common Mistakes:

• Including odd numbers by mistake
• Returning all numbers without filter
• Expecting empty set due to syntax confusion

4.

Identify the error in this function that returns a set of text values:

CREATE FUNCTION get_names() RETURNS SETOF text AS $$ BEGIN RETURN SELECT name FROM users; END; $$ LANGUAGE plpgsql;

medium

A. Missing RETURN QUERY before SELECT statement.

B. RETURNS SETOF text is invalid syntax.

C. Function must return TABLE, not SETOF.

D. LANGUAGE plpgsql is not allowed for set-returning functions.

Solution

1. Step 1: Check how to return multiple rows in plpgsql

   To return multiple rows, use RETURN QUERY SELECT ... inside the function.

2. Step 2: Identify missing keyword

   The function uses RETURN SELECT ... which is invalid; it must be RETURN QUERY SELECT ....

3. Final Answer:

   Missing RETURN QUERY before SELECT statement. -> Option A

4. Quick Check:

   Use RETURN QUERY for sets [OK]

Hint: Use RETURN QUERY to return sets inside plpgsql [OK]

Common Mistakes:

• Using RETURN instead of RETURN QUERY
• Confusing RETURNS SETOF with RETURNS TABLE
• Thinking LANGUAGE plpgsql disallows set returns

5.

You want to create a function that returns all employees with salary above a given amount. Which is the best way to write this function?

CREATE FUNCTION get_high_salary(min_salary numeric) RETURNS SETOF employees AS $$ BEGIN RETURN QUERY SELECT * FROM employees WHERE salary > min_salary; END; $$ LANGUAGE plpgsql;

What is the correct way to call this function to get all employees earning more than 50000?

hard

A. SELECT get_high_salary(50000);

B. SELECT * FROM get_high_salary(50000);

C. CALL get_high_salary(50000);

D. EXECUTE get_high_salary(50000);

Solution

1. Step 1: Understand function returns SETOF employees

   The function returns multiple rows, so it must be called in a FROM clause to get rows.

2. Step 2: Choose correct call syntax

   Use SELECT * FROM function_name(args); to get all rows returned by the function.

3. Final Answer:

   SELECT * FROM get_high_salary(50000); -> Option B

4. Quick Check:

   Call set-returning function in FROM clause [OK]

Hint: Call set-returning functions with SELECT * FROM [OK]

Common Mistakes:

• Using SELECT function() without FROM
• Using CALL which is for procedures
• Using EXECUTE which is for dynamic SQL