begriffs open source - ai-pg/blob - full-docs/txt/xfunc-volatility.txt

   1
   2 36.7. Function Volatility Categories #
   3
   4    Every function has a volatility classification, with the possibilities
   5    being VOLATILE, STABLE, or IMMUTABLE. VOLATILE is the default if the
   6    CREATE FUNCTION command does not specify a category. The volatility
   7    category is a promise to the optimizer about the behavior of the
   8    function:
   9      * A VOLATILE function can do anything, including modifying the
  10        database. It can return different results on successive calls with
  11        the same arguments. The optimizer makes no assumptions about the
  12        behavior of such functions. A query using a volatile function will
  13        re-evaluate the function at every row where its value is needed.
  14      * A STABLE function cannot modify the database and is guaranteed to
  15        return the same results given the same arguments for all rows
  16        within a single statement. This category allows the optimizer to
  17        optimize multiple calls of the function to a single call. In
  18        particular, it is safe to use an expression containing such a
  19        function in an index scan condition. (Since an index scan will
  20        evaluate the comparison value only once, not once at each row, it
  21        is not valid to use a VOLATILE function in an index scan
  22        condition.)
  23      * An IMMUTABLE function cannot modify the database and is guaranteed
  24        to return the same results given the same arguments forever. This
  25        category allows the optimizer to pre-evaluate the function when a
  26        query calls it with constant arguments. For example, a query like
  27        SELECT ... WHERE x = 2 + 2 can be simplified on sight to SELECT ...
  28        WHERE x = 4, because the function underlying the integer addition
  29        operator is marked IMMUTABLE.
  30
  31    For best optimization results, you should label your functions with the
  32    strictest volatility category that is valid for them.
  33
  34    Any function with side-effects must be labeled VOLATILE, so that calls
  35    to it cannot be optimized away. Even a function with no side-effects
  36    needs to be labeled VOLATILE if its value can change within a single
  37    query; some examples are random(), currval(), timeofday().
  38
  39    Another important example is that the current_timestamp family of
  40    functions qualify as STABLE, since their values do not change within a
  41    transaction.
  42
  43    There is relatively little difference between STABLE and IMMUTABLE
  44    categories when considering simple interactive queries that are planned
  45    and immediately executed: it doesn't matter a lot whether a function is
  46    executed once during planning or once during query execution startup.
  47    But there is a big difference if the plan is saved and reused later.
  48    Labeling a function IMMUTABLE when it really isn't might allow it to be
  49    prematurely folded to a constant during planning, resulting in a stale
  50    value being re-used during subsequent uses of the plan. This is a
  51    hazard when using prepared statements or when using function languages
  52    that cache plans (such as PL/pgSQL).
  53
  54    For functions written in SQL or in any of the standard procedural
  55    languages, there is a second important property determined by the
  56    volatility category, namely the visibility of any data changes that
  57    have been made by the SQL command that is calling the function. A
  58    VOLATILE function will see such changes, a STABLE or IMMUTABLE function
  59    will not. This behavior is implemented using the snapshotting behavior
  60    of MVCC (see Chapter 13): STABLE and IMMUTABLE functions use a snapshot
  61    established as of the start of the calling query, whereas VOLATILE
  62    functions obtain a fresh snapshot at the start of each query they
  63    execute.
  64
  65 Note
  66
  67    Functions written in C can manage snapshots however they want, but it's
  68    usually a good idea to make C functions work this way too.
  69
  70    Because of this snapshotting behavior, a function containing only
  71    SELECT commands can safely be marked STABLE, even if it selects from
  72    tables that might be undergoing modifications by concurrent queries.
  73    PostgreSQL will execute all commands of a STABLE function using the
  74    snapshot established for the calling query, and so it will see a fixed
  75    view of the database throughout that query.
  76
  77    The same snapshotting behavior is used for SELECT commands within
  78    IMMUTABLE functions. It is generally unwise to select from database
  79    tables within an IMMUTABLE function at all, since the immutability will
  80    be broken if the table contents ever change. However, PostgreSQL does
  81    not enforce that you do not do that.
  82
  83    A common error is to label a function IMMUTABLE when its results depend
  84    on a configuration parameter. For example, a function that manipulates
  85    timestamps might well have results that depend on the TimeZone setting.
  86    For safety, such functions should be labeled STABLE instead.
  87
  88 Note
  89
  90    PostgreSQL requires that STABLE and IMMUTABLE functions contain no SQL
  91    commands other than SELECT to prevent data modification. (This is not a
  92    completely bulletproof test, since such functions could still call
  93    VOLATILE functions that modify the database. If you do that, you will
  94    find that the STABLE or IMMUTABLE function does not notice the database
  95    changes applied by the called function, since they are hidden from its
  96    snapshot.)