PREPARE(7)							   SQL Commands 							PREPARE(7)

NAME

       PREPARE - create a prepared query

SYNOPSIS

	  PREPARE plan_name [ (datatype [, ...] ) ] AS query

   INPUTS
       plan_name
	      An  arbitrary  name  given  to  this particular prepared query. It must be unique within a single session, and is used to execute or
	      remove a previously prepared query.

       datatype
	      The data-type of a parameter to the prepared query.  To refer to the parameters in the prepared query itself, use $1, $2, etc.

   OUTPUTS
       PREPARE
	      The query has been prepared successfully.

DESCRIPTION

       PREPARE creates a prepared query. A prepared query is a server-side object that can be used  to	optimize  performance.	When  the  PREPARE
       statement  is  executed, the specified query is parsed, rewritten, and planned. When a subsequent EXECUTE statement is issued, the prepared
       query need only be executed. Thus, the parsing, rewriting, and planning stages are only performed once, instead of every time the query	is
       executed.

       Prepared  queries  can take parameters: values that are substituted into the query when it is executed. To specify the parameters to a pre-
       pared query, include a list of data-types with the PREPARE statement. In the query itself, you can refer  to  the  parameters  by  position
       using  $1,  $2,	etc. When executing the query, specify the actual values for these parameters in the EXECUTE statement -- refer to EXECUTE
       [execute(7)] for more information.

       Prepared queries are stored locally (in the current backend), and only exist for the duration of the current  database  session.  When  the
       client exits, the prepared query is forgotten, and so it must be re-created before being used again. This also means that a single prepared
       query cannot be used by multiple simultaneous database clients; however, each client can create their own prepared query to use.

       Prepared queries have the largest performance advantage when a single backend is being used to execute a large number of  similar  queries.
       The  performance  difference  will  be  particularly  significant  if the queries are complex to plan or rewrite. For example, if the query
       involves a join of many tables or requires the application of several rules. If the query is relatively simple to plan and rewrite but rel-
       atively expensive to execute, the performance advantage of prepared queries will be less noticeable.

   NOTES
       In  some situations, the query plan produced by PostgreSQL for a prepared query may be inferior to the plan produced if the query were sub-
       mitted and executed normally. This is because when the query is planned (and the optimizer attempts to determine the optimal  query  plan),
       the  actual  values of any parameters specified in the query are unavailable. PostgreSQL collects statistics on the distribution of data in
       the table, and can use constant values in a query to make guesses about the likely result of  executing	the  query.  Since  this  data	is
       unavailable when planning prepared queries with parameters, the chosen plan may be sub-optimal.

       For  more  information  on query planning and the statistics collected by PostgreSQL for query optimization purposes, see the ANALYZE [ana-
       lyze(7)] documentation.

COMPATIBILITY

   SQL92
       SQL92 includes a PREPARE statement, but it is only for use in embedded SQL clients. The PREPARE statement implemented  by  PostgreSQL  also
       uses a somewhat different syntax.

SQL - Language Statements					    2002-11-22								PREPARE(7)