Como retornar valores de funções em PL/pgSQL

Quando você escreve funções no PostgreSQL, uma das primeiras dúvidas é como retornar o resultado. Às vezes, você só precisa devolver um número. Outras vezes, uma tabela inteira. E tem hora que até vários conjuntos de dados. Aqui vamos ver todos os jeitos principais: do mais simples RETURN até RETURN QUERY, RETURNS TABLE e SETOF.

Um resultado só: RETURN

Se sua função precisa retornar só um valor — tipo uma soma ou a quantidade de linhas — usa o RETURN normal.

CREATE FUNCTION count_students() RETURNS INT AS $$
DECLARE
    total INT;
BEGIN
    SELECT COUNT(*) INTO total FROM students;
    RETURN total;
END;
$$ LANGUAGE plpgsql;

Quando você cria uma função em PL/pgSQL, tem que dizer o que ela retorna. Isso é o que o RETURNS faz: define o "formato" do resultado que a função vai devolver. Então, se você quer retornar um número, texto ou uma tabela — tudo isso tem que estar na linha do RETURNS.

Um exemplo simples:

CREATE FUNCTION add_numbers(a INT, b INT) RETURNS INT AS $$
BEGIN
    RETURN a + b;
END;
$$ LANGUAGE plpgsql;

Aqui o RETURNS INT mostra que a função devolve um número.

Retornando um valor só

Bora começar do mais básico — uma função que retorna só um valor. Por exemplo, uma função que conta quantos estudantes tem na tabela students:

CREATE FUNCTION count_students() RETURNS INT AS $$
DECLARE
    total INT;
BEGIN
    SELECT COUNT(*) INTO total FROM students; -- Salvando o resultado da query na variável total
    RETURN total; -- Retornando o resultado
END;
$$ LANGUAGE plpgsql;

Agora dá pra chamar essa função assim:

SELECT count_students(); -- Vai retornar a quantidade de estudantes

Retornando vários valores com RETURNS TABLE

Às vezes você precisa devolver não só um valor, mas um conjunto de registros. Tipo uma lista de todos os estudantes com nome e id. Pra isso, usa o RETURNS TABLE.

CREATE FUNCTION get_students() RETURNS TABLE(id INT, name TEXT) AS $$
BEGIN
    RETURN QUERY SELECT id, name FROM students; -- Retornando o resultado da query como tabela
END;
$$ LANGUAGE plpgsql;

Agora dá pra chamar essa função assim:

SELECT * FROM get_students(); -- Vai retornar uma tabela com todos os estudantes

Repara no RETURNS TABLE. Ele diz que a função devolve uma tabela com as colunas que você definiu (id e name nesse caso).

Usando RETURN QUERY

Se você curtiu o exemplo acima, olha só: RETURN QUERY é tipo uma mágica do PL/pgSQL que deixa você devolver dados direto de uma query. Com ele, dá pra retornar o resultado inteiro de uma consulta ou só uma parte.

Por exemplo, se a gente quiser retornar só os estudantes que estão ativos (status active = TRUE no banco):

CREATE FUNCTION get_active_students() RETURNS TABLE(id INT, name TEXT) AS $$
BEGIN
    RETURN QUERY
    SELECT id, name
    FROM students
    WHERE active = TRUE; -- Retornando só os estudantes ativos
END;
$$ LANGUAGE plpgsql;

Agora dá pra chamar a função e pegar só os estudantes ativos:

SELECT * FROM get_active_students();

Retornando várias linhas sem RETURNS TABLE

Em alguns casos, você pode querer devolver linhas de dados sem usar RETURNS TABLE. Pra isso, usa o tipo SETOF. Assim, você retorna linhas de dados com a mesma estrutura. Por exemplo:

CREATE FUNCTION get_student_names() RETURNS SETOF TEXT AS $$
BEGIN
    RETURN QUERY
    SELECT name
    FROM students;
END;
$$ LANGUAGE plpgsql;

Essa função retorna só a lista de nomes dos estudantes:

SELECT * FROM get_student_names();

Retornando valores dependendo dos parâmetros

Funções nem sempre devolvem só resultados fixos. Elas podem usar parâmetros pra mudar o resultado dinamicamente.

Olha um exemplo de retornar dados pelo id do estudante:

CREATE FUNCTION get_student_by_id(student_id INT) RETURNS TABLE(id INT, name TEXT) AS $$
BEGIN
    RETURN QUERY
    SELECT id, name
    FROM students
    WHERE id = student_id; -- Usando o parâmetro student_id
END;
$$ LANGUAGE plpgsql;

Agora você pode buscar info de um estudante específico:

SELECT * FROM get_student_by_id(3); -- Vai retornar os dados do estudante com ID = 3

Retornando dados complexos (vários conjuntos)

Às vezes os dados são tão complexos que você precisa devolver vários conjuntos. Pra isso, dá pra usar cursores. Por exemplo, se você quiser devolver dois conjuntos de dados de uma função — lista de estudantes ativos e inativos.

CREATE FUNCTION get_students_status() RETURNS SETOF RECORD AS $$
BEGIN
    RETURN QUERY
    SELECT id, name, 'active' AS status
    FROM students
    WHERE active = TRUE;

    RETURN QUERY
    SELECT id, name, 'inactive' AS status
    FROM students
    WHERE active = FALSE;
END;
$$ LANGUAGE plpgsql;

Agora dá pra pegar os dois conjuntos de dados:

SELECT * FROM get_students_status();

Erros comuns ao usar RETURNS

Não informar o tipo de retorno: Se você não disser o que a função retorna, o PostgreSQL vai dar erro. Por exemplo:

CREATE FUNCTION no_return_type() AS $$ -- Erro, não tem RETURNS
BEGIN
    RETURN 1;
END;
$$ LANGUAGE plpgsql;

Tipos de dados não batem: garante que os valores retornados combinam com o tipo declarado. Tipo, se você disse que retorna INT, não tenta devolver uma string.

Esqueceu de usar RETURN QUERY: se você esquecer de usar RETURN QUERY pra uma query mais complexa, a função não vai retornar nada.

Retorno errado de vários valores: se você retorna uma linha de dados mas esquece de usar SETOF ou TABLE, o PostgreSQL vai dar erro.