github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/sql/opt/ops/README.md (about)

     1  Optimizer operator definitions
     2  ==============================
     3  
     4  This directory contains definitions for the optimizer operators.
     5  
     6  The syntax should be fairly self-evident from the existing definitions. Each
     7  operator can contain, in this order:
     8   - any number of "child" expressions (relational and/or scalar);
     9   - at most one "private" field. If multiple fields are necessary, the private
    10     can be an embedded, separately defined structure (using similar syntax and
    11     the `Private` tag). The private fields are interned with the expression and
    12     can be used by rules; they must be initialized before construction of the
    13     expression. Private fields can be accessed by rules.
    14   - at most one `Typ` field (only for Scalar operators). If this field is not
    15     present, the scalar type of the operator is inferred from its inputs.
    16   - any number of unexported fields. Unexported fields are typically used to
    17     cache information that can be deduced from the children and the private. If
    18     there are unexported fields, an `initUnexportedFields(*Memo)` method must be
    19     implemented for the operator (in `opt/memo/expr.go`). This method is used to
    20     initialize these fields as necessary. The unexported fields cannot be used by
    21     rules (they are initialized after any normalization rules run).
    22  
    23  Try to keep the formatting consistent. In particular:
    24   - use 4 spaces (no tabs) for indentation;
    25   - include a comment describing the operator;
    26   - include comments for non-trivial fields;
    27   - put Private definitions after the corresponding operator.
    28  
    29  If a new type is necessary for a field definition, an entry must be added in
    30  optgen (`opt/optgen/cmd/optgen/metadata.go`), and `HashXX / IsXXEqual` functions
    31  must be added to the interner (`opt/memo/interner.go`).
    32  
    33  ## Tags
    34  
    35  Operators can have various tags. This section lists all the used tags and their
    36  intended semantics.
    37  
    38  General operator type tags (each operator has exactly one of these tags):
    39   - `Relational`: used for relational operators.
    40   - `Scalar`: used for scalar operators.
    41   - `Enforcer`: used for enforcers.
    42  
    43  Tags for scalar operators:
    44   - `List`: used for scalar lists operators.
    45   - `ListItem`: used for scalar list items.
    46   - `Binary`: used for binary operators.
    47   - `Bool`: used for operators that always return a boolean.
    48   - `Int`: used for operators that always return an integer.
    49   - `Float`: used for operators that always return a float.
    50   - `Comparison`: used for binary operators that return a boolean.
    51   - `ConstValue`: used for operators that represent a constant value.
    52   - `Aggregate`: used for operators that represent an aggregation function.
    53   - `Window`: used for operators that represent a window function.
    54  
    55  Tags for relational operators:
    56   - `Join`: used for logical variations of join, including apply joins (but not
    57     physical variations like lookup join).
    58   - `JoinApply`: used for logical variations of apply join.
    59   - `JoinNonApply`: used for logical variations of join, not including apply
    60     joins.
    61   - `Grouping`: used for aggregation operators.
    62   - `Set`: used for set operation operators (like Union, Intersect).
    63   - `Telemetry`: if used, triggers operator usage tracking via telemetry.
    64   - `Mutation`: used for operators that can mutate data as part of the
    65     transaction. This includes DML operations like INSERT, as well as DDL
    66     operations. In general, anything that can't execute in a read-only
    67     transaction must have this tag.
    68   - `DDL`: used for schema change operations; these operators cannot be executed
    69     following a mutation in the same transaction. Should always be used in
    70     conjunction with the `Mutation` tag.