begriffs open source - ai-pg/blob - full-docs/txt/ddl-generated-columns.txt

   1
   2 5.4. Generated Columns #
   3
   4    A generated column is a special column that is always computed from
   5    other columns. Thus, it is for columns what a view is for tables. There
   6    are two kinds of generated columns: stored and virtual. A stored
   7    generated column is computed when it is written (inserted or updated)
   8    and occupies storage as if it were a normal column. A virtual generated
   9    column occupies no storage and is computed when it is read. Thus, a
  10    virtual generated column is similar to a view and a stored generated
  11    column is similar to a materialized view (except that it is always
  12    updated automatically).
  13
  14    To create a generated column, use the GENERATED ALWAYS AS clause in
  15    CREATE TABLE, for example:
  16 CREATE TABLE people (
  17     ...,
  18     height_cm numeric,
  19     height_in numeric GENERATED ALWAYS AS (height_cm / 2.54)
  20 );
  21
  22    A generated column is by default of the virtual kind. Use the keywords
  23    VIRTUAL or STORED to make the choice explicit. See CREATE TABLE for
  24    more details.
  25
  26    A generated column cannot be written to directly. In INSERT or UPDATE
  27    commands, a value cannot be specified for a generated column, but the
  28    keyword DEFAULT may be specified.
  29
  30    Consider the differences between a column with a default and a
  31    generated column. The column default is evaluated once when the row is
  32    first inserted if no other value was provided; a generated column is
  33    updated whenever the row changes and cannot be overridden. A column
  34    default may not refer to other columns of the table; a generation
  35    expression would normally do so. A column default can use volatile
  36    functions, for example random() or functions referring to the current
  37    time; this is not allowed for generated columns.
  38
  39    Several restrictions apply to the definition of generated columns and
  40    tables involving generated columns:
  41      * The generation expression can only use immutable functions and
  42        cannot use subqueries or reference anything other than the current
  43        row in any way.
  44      * A generation expression cannot reference another generated column.
  45      * A generation expression cannot reference a system column, except
  46        tableoid.
  47      * A virtual generated column cannot have a user-defined type, and the
  48        generation expression of a virtual generated column must not
  49        reference user-defined functions or types, that is, it can only use
  50        built-in functions or types. This applies also indirectly, such as
  51        for functions or types that underlie operators or casts. (This
  52        restriction does not exist for stored generated columns.)
  53      * A generated column cannot have a column default or an identity
  54        definition.
  55      * A generated column cannot be part of a partition key.
  56      * Foreign tables can have generated columns. See CREATE FOREIGN TABLE
  57        for details.
  58      * For inheritance and partitioning:
  59           + If a parent column is a generated column, its child column
  60             must also be a generated column of the same kind (stored or
  61             virtual); however, the child column can have a different
  62             generation expression.
  63             For stored generated columns, the generation expression that
  64             is actually applied during insert or update of a row is the
  65             one associated with the table that the row is physically in.
  66             (This is unlike the behavior for column defaults: for those,
  67             the default value associated with the table named in the query
  68             applies.) For virtual generated columns, the generation
  69             expression of the table named in the query applies when a
  70             table is read.
  71           + If a parent column is not a generated column, its child column
  72             must not be generated either.
  73           + For inherited tables, if you write a child column definition
  74             without any GENERATED clause in CREATE TABLE ... INHERITS,
  75             then its GENERATED clause will automatically be copied from
  76             the parent. ALTER TABLE ... INHERIT will insist that parent
  77             and child columns already match as to generation status, but
  78             it will not require their generation expressions to match.
  79           + Similarly for partitioned tables, if you write a child column
  80             definition without any GENERATED clause in CREATE TABLE ...
  81             PARTITION OF, then its GENERATED clause will automatically be
  82             copied from the parent. ALTER TABLE ... ATTACH PARTITION will
  83             insist that parent and child columns already match as to
  84             generation status, but it will not require their generation
  85             expressions to match.
  86           + In case of multiple inheritance, if one parent column is a
  87             generated column, then all parent columns must be generated
  88             columns. If they do not all have the same generation
  89             expression, then the desired expression for the child must be
  90             specified explicitly.
  91
  92    Additional considerations apply to the use of generated columns.
  93      * Generated columns maintain access privileges separately from their
  94        underlying base columns. So, it is possible to arrange it so that a
  95        particular role can read from a generated column but not from the
  96        underlying base columns.
  97        For virtual generated columns, this is only fully secure if the
  98        generation expression uses only leakproof functions (see CREATE
  99        FUNCTION), but this is not enforced by the system.
 100      * Privileges of functions used in generation expressions are checked
 101        when the expression is actually executed, on write or read
 102        respectively, as if the generation expression had been called
 103        directly from the query using the generated column. The user of a
 104        generated column must have permissions to call all functions used
 105        by the generation expression. Functions in the generation
 106        expression are executed with the privileges of the user executing
 107        the query or the function owner, depending on whether the functions
 108        are defined as SECURITY INVOKER or SECURITY DEFINER.
 109      * Generated columns are, conceptually, updated after BEFORE triggers
 110        have run. Therefore, changes made to base columns in a BEFORE
 111        trigger will be reflected in generated columns. But conversely, it
 112        is not allowed to access generated columns in BEFORE triggers.
 113      * Generated columns are allowed to be replicated during logical
 114        replication according to the CREATE PUBLICATION parameter
 115        publish_generated_columns or by including them in the column list
 116        of the CREATE PUBLICATION command. This is currently only supported
 117        for stored generated columns. See Section 29.6 for details.