Home Explore Blog CI



postgresql

15th chunk of `doc/src/sgml/plpgsql.sgml`
023d889ba987e14c1b679d7303c8ac95c01f3462e7be3a4c0000000100000fa7
 <command>SELECT</command> command, but replace the
     initial keyword <command>SELECT</command> with <command>PERFORM</command>.
     For <command>WITH</command> queries, use <command>PERFORM</command> and then
     place the query in parentheses.  (In this case, the query can only
     return one row.)
     <application>PL/pgSQL</application> variables will be
     substituted into the query just as described above,
     and the plan is cached in the same way.  Also, the special variable
     <literal>FOUND</literal> is set to true if the query produced at
     least one row, or false if it produced no rows (see
     <xref linkend="plpgsql-statements-diagnostics"/>).
    </para>

    <note>
     <para>
      One might expect that writing <command>SELECT</command> directly
      would accomplish this result, but at
      present the only accepted way to do it is
      <command>PERFORM</command>.  An SQL command that can return rows,
      such as <command>SELECT</command>, will be rejected as an error
      unless it has an <literal>INTO</literal> clause as discussed in the
      next section.
     </para>
    </note>

    <para>
     An example:
<programlisting>
PERFORM create_mv('cs_session_page_requests_mv', my_query);
</programlisting>
    </para>
   </sect2>

   <sect2 id="plpgsql-statements-sql-onerow">
    <title>Executing a Command with a Single-Row Result</title>

    <indexterm zone="plpgsql-statements-sql-onerow">
     <primary>SELECT INTO</primary>
     <secondary>in PL/pgSQL</secondary>
    </indexterm>

    <indexterm zone="plpgsql-statements-sql-onerow">
     <primary>RETURNING INTO</primary>
     <secondary>in PL/pgSQL</secondary>
    </indexterm>

    <para>
     The result of an SQL command yielding a single row (possibly of multiple
     columns) can be assigned to a record variable, row-type variable, or list
     of scalar variables.  This is done by writing the base SQL command and
     adding an <literal>INTO</literal> clause.  For example,

<synopsis>
SELECT <replaceable>select_expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>target</replaceable> FROM ...;
INSERT ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>target</replaceable>;
UPDATE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>target</replaceable>;
DELETE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>target</replaceable>;
MERGE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>target</replaceable>;
</synopsis>

     where <replaceable>target</replaceable> can be a record variable, a row
     variable, or a comma-separated list of simple variables and
     record/row fields.
     <application>PL/pgSQL</application> variables will be
     substituted into the rest of the command (that is, everything but the
     <literal>INTO</literal> clause) just as described above,
     and the plan is cached in the same way.
     This works for <command>SELECT</command>,
     <command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command>/<command>MERGE</command>
     with <literal>RETURNING</literal>, and certain utility commands
     that return row sets, such as <command>EXPLAIN</command>.
     Except for the <literal>INTO</literal> clause, the SQL command is the same
     as it would be written outside <application>PL/pgSQL</application>.
    </para>

   <tip>
    <para>
     Note that this interpretation of <command>SELECT</command> with <literal>INTO</literal>
     is quite different from <productname>PostgreSQL</productname>'s regular
     <command>SELECT INTO</command> command, wherein the <literal>INTO</literal>
     target is a newly created table.  If you want to create a table from a
     <command>SELECT</command> result inside a
     <application>PL/pgSQL</application> function, use the syntax
     <command>CREATE

Title: PERFORM Statement and Single-Row Results with SELECT INTO
Summary
The PERFORM statement executes a query, discarding the result but setting the FOUND variable. It's the preferred way to execute a SELECT statement for its side effects. To capture a single-row result, use SELECT INTO, INSERT/UPDATE/DELETE/MERGE with RETURNING INTO, or certain utility commands. The target of INTO can be a record, row variable, or a list of scalar variables. PL/pgSQL variables are substituted into the command (excluding the INTO clause), and the plan is cached.