cockroach: github.com/cockroachdb/cockroach/pkg/sql/opt/testutils/opttester Index | Files

package opttester

import "github.com/cockroachdb/cockroach/pkg/sql/opt/testutils/opttester"

Index

Package Files

explore_trace.go forcing_opt.go memo_groups.go opt_steps.go opt_tester.go stats_tester.go

type Flags Uses

type Flags struct {
    // ExprFormat controls the output detail of build / opt/ optsteps command
    // directives.
    ExprFormat memo.ExprFmtFlags

    // MemoFormat controls the output detail of memo command directives.
    MemoFormat xform.FmtFlags

    // AllowUnsupportedExpr if set: when building a scalar, the optbuilder takes
    // any TypedExpr node that it doesn't recognize and wraps that expression in
    // an UnsupportedExpr node. This is temporary; it is used for interfacing with
    // the old planning code.
    AllowUnsupportedExpr bool

    // FullyQualifyNames if set: when building a query, the optbuilder fully
    // qualifies all column names before adding them to the metadata. This flag
    // allows us to test that name resolution works correctly, and avoids
    // cluttering test output with schema and catalog names in the general case.
    FullyQualifyNames bool

    // Verbose indicates whether verbose test debugging information will be
    // output to stdout when commands run. Only certain commands support this.
    Verbose bool

    // DisableRules is a set of rules that are not allowed to run.
    DisableRules RuleSet

    // ExploreTraceRule restricts the ExploreTrace output to only show the effects
    // of a specific rule.
    ExploreTraceRule opt.RuleName

    // ExploreTraceSkipNoop hides the ExploreTrace output for instances of rules
    // that fire but don't add any new expressions to the memo.
    ExploreTraceSkipNoop bool

    // ExpectedRules is a set of rules which must be exercised for the test to
    // pass.
    ExpectedRules RuleSet

    // UnexpectedRules is a set of rules which must not be exercised for the test
    // to pass.
    UnexpectedRules RuleSet

    // ColStats is a list of ColSets for which a column statistic is requested.
    ColStats []opt.ColSet

    // PerturbCost indicates how much to randomly perturb the cost. It is used
    // to generate alternative plans for testing. For example, if PerturbCost is
    // 0.5, and the estimated cost of an expression is c, the cost returned by
    // the coster will be in the range [c - 0.5 * c, c + 0.5 * c).
    PerturbCost float64

    // ReorderJoinsLimit is the maximum number of joins in a query which the optimizer
    // should attempt to reorder.
    JoinLimit int

    // Locality specifies the location of the planning node as a set of user-
    // defined key/value pairs, ordered from most inclusive to least inclusive.
    // If there are no tiers, then the node's location is not known. Examples:
    //
    //   [region=eu]
    //   [region=us,dc=east]
    //
    Locality roachpb.Locality

    // Database specifies the current database to use for the query. This field
    // is only used by the save-tables command when rewriteActualFlag=true.
    Database string

    // Table specifies the current table to use for the command. This field
    // is only used by the stats command.
    Table string

    // SaveTablesPrefix specifies the prefix of the table to create or print
    // for each subexpression in the query.
    SaveTablesPrefix string

    // File specifies the name of the file to import. This field is only used by
    // the import command.
    File string
}

Flags are control knobs for tests. Note that specific testcases can override these defaults.

func (*Flags) Set Uses

func (f *Flags) Set(arg datadriven.CmdArg) error

Set parses an argument that refers to a flag. See OptTester.RunCommand for supported flags.

type OptTester Uses

type OptTester struct {
    Flags Flags
    // contains filtered or unexported fields
}

OptTester is a helper for testing the various optimizer components. It contains the boiler-plate code for the following useful tasks:

- Build an unoptimized opt expression tree
- Build an optimized opt expression tree
- Format the optimizer memo structure
- Create a diff showing the optimizer's work, step-by-step
- Build the exec node tree
- Execute the exec node tree

The OptTester is used by tests in various sub-packages of the opt package.

func New Uses

func New(catalog cat.Catalog, sql string) *OptTester

New constructs a new instance of the OptTester for the given SQL statement. Metadata used by the SQL query is accessed via the catalog.

func (*OptTester) ExploreTrace Uses

func (ot *OptTester) ExploreTrace() (string, error)

ExploreTrace steps through exploration transformations performed by the optimizer, one-by-one. The output of each step is the expression on which the rule was applied, and the expressions that were generated by the rule.

func (*OptTester) Expr Uses

func (ot *OptTester) Expr() (opt.Expr, error)

Expr parses the input directly into an expression; see exprgen.Build.

func (*OptTester) ExprNorm Uses

func (ot *OptTester) ExprNorm() (opt.Expr, error)

ExprNorm parses the input directly into an expression and runs normalization; see exprgen.Build.

func (*OptTester) Import Uses

func (ot *OptTester) Import(tb testing.TB)

Import imports a file containing exec-ddl commands in order to add tables and/or stats to the catalog. This allows commonly-used schemas such as TPC-C or TPC-H to be used by multiple test files without copying the schemas and stats multiple times.

func (*OptTester) Memo Uses

func (ot *OptTester) Memo() (string, error)

Memo returns a string that shows the memo data structure that is constructed by the optimizer.

func (*OptTester) OptBuild Uses

func (ot *OptTester) OptBuild() (opt.Expr, error)

OptBuild constructs an opt expression tree for the SQL query, with no transformations applied to it. The untouched output of the optbuilder is the final expression tree.

func (*OptTester) OptNorm Uses

func (ot *OptTester) OptNorm() (opt.Expr, error)

OptNorm constructs an opt expression tree for the SQL query, with all normalization transformations applied to it. The normalized output of the optbuilder is the final expression tree.

func (*OptTester) OptSteps Uses

func (ot *OptTester) OptSteps() (string, error)

OptSteps steps through the transformations performed by the optimizer on the memo, one-by-one. The output of each step is the lowest cost expression tree that also contains the expressions that were changed or added by the transformation. The output of each step is diff'd against the output of a previous step, using the standard unified diff format.

CREATE TABLE a (x INT PRIMARY KEY, y INT, UNIQUE INDEX (y))

SELECT x FROM a WHERE x=1

At the time of this writing, this query triggers 6 rule applications:

EnsureSelectFilters     Wrap Select predicate with Filters operator
FilterUnusedSelectCols  Do not return unused "y" column from Scan
EliminateProject        Remove unneeded Project operator
GenerateIndexScans      Explore scanning "y" index to get "x" values
ConstrainScan           Explore pushing "x=1" into "x" index Scan
ConstrainScan           Explore pushing "x=1" into "y" index Scan

Some steps produce better plans that have a lower execution cost. Other steps don't. However, it's useful to see both kinds of steps. The optsteps output distinguishes these two cases by using stronger "====" header delimiters when a better plan has been found, and weaker "----" header delimiters when not. In both cases, the output shows the expressions that were changed or added by the rule, even if the total expression tree cost worsened.

func (*OptTester) Optimize Uses

func (ot *OptTester) Optimize() (opt.Expr, error)

Optimize constructs an opt expression tree for the SQL query, with all transformations applied to it. The result is the memo expression tree with the lowest estimated cost.

func (*OptTester) RuleStats Uses

func (ot *OptTester) RuleStats() (string, error)

RuleStats performs the optimization and returns statistics about how many rules were applied.

func (*OptTester) RunCommand Uses

func (ot *OptTester) RunCommand(tb testing.TB, d *datadriven.TestData) string

RunCommand implements commands that are used by most tests:

- exec-ddl

  Runs a SQL DDL statement to build the test catalog. Only a small number
  of DDL statements are supported, and those not fully. This is only
  available when using a TestCatalog.

- build [flags]

  Builds an expression tree from a SQL query and outputs it without any
  optimizations applied to it.

- norm [flags]

  Builds an expression tree from a SQL query, applies normalization
  optimizations, and outputs it without any exploration optimizations
  applied to it.

- opt [flags]

  Builds an expression tree from a SQL query, fully optimizes it using the
  memo, and then outputs the lowest cost tree.

- optsteps [flags]

  Outputs the lowest cost tree for each step in optimization using the
  standard unified diff format. Used for debugging the optimizer.

- exploretrace [flags]

  Outputs information about exploration rule application. Used for debugging
  the optimizer.

- memo [flags]

  Builds an expression tree from a SQL query, fully optimizes it using the
  memo, and then outputs the memo containing the forest of trees.

- rulestats [flags]

  Performs the optimization and outputs statistics about applied rules.

- expr

  Builds an expression directly from an opt-gen-like string; see
  exprgen.Build.

- save-tables [flags]

  Fully optimizes the given query and saves the subexpressions as tables
  in the test catalog with their estimated statistics injected.
  If rewriteActualFlag=true, also executes the given query against a
  running database and saves the intermediate results as tables.

- stats [flags]

  Compares estimated statistics for a relational expression with the actual
  statistics calculated by calling CREATE STATISTICS on the output of the
  expression. save-tables must have been called previously to save the
  target expression as a table. The name of this table must be provided
  with the table flag.

- import [flags]

  Imports a file containing exec-ddl commands in order to add tables and/or
  stats to the catalog. This allows commonly-used schemas such as TPC-C or
  TPC-H to be used by multiple test files without copying the schemas and
  stats multiple times. The file name must be provided with the file flag.
  The path of the file should be relative to
  testutils/opttester/testfixtures.

Supported flags:

- format: controls the formatting of expressions for build, opt, and
  optsteps commands. Possible values: show-all, hide-all, or any combination
  of hide-cost, hide-stats, hide-constraints, hide-scalars, hide-qual.
  For example:
    build format=(hide-cost,hide-stats)

- allow-unsupported: wrap unsupported expressions in UnsupportedOp.

- fully-qualify-names: fully qualify all column names in the test output.

- expect: fail the test if the rules specified by name do not match.

- expect-not: fail the test if the rules specified by name match.

- disable: disables optimizer rules by name. Examples:
    opt disable=ConstrainScan
    norm disable=(NegateOr,NegateAnd)

- rule: used with exploretrace; the value is the name of a rule. When
  specified, the exploretrace output is filtered to only show expression
  changes due to that specific rule.

- skip-no-op: used with exploretrace; hide instances of rules that don't
  generate any new expressions.

- colstat: requests the calculation of a column statistic on the top-level
  expression. The value is a column or a list of columns. The flag can
  be used multiple times to request different statistics.

- perturb-cost: used to randomly perturb the estimated cost of each
  expression in the query tree for the purpose of creating alternate query
  plans in the optimizer.

- locality: used to set the locality of the node that plans the query. This
  can affect costing when there are multiple possible indexes to choose
  from, each in different localities.

- database: used to set the current database used by the query. This is
  used by the save-tables command when rewriteActualFlag=true.

- table: used to set the current table used by the command. This is used by
  the stats command.

- save-tables-prefix: must be used with the save-tables command. If
  rewriteActualFlag=true, indicates that a table should be created with the
  given prefix for the output of each subexpression in the query.
  Otherwise, outputs the name of the table that would be created for each
  subexpression.

- file: used to set the name of the file to be imported. This is used by
  the import command.

func (*OptTester) SaveTables Uses

func (ot *OptTester) SaveTables() (opt.Expr, error)

SaveTables optimizes the given query and saves the subexpressions as tables in the test catalog with their estimated statistics injected. If rewriteActualStats=true, it also executes the given query against a running database and saves the intermediate results as tables.

func (*OptTester) Stats Uses

func (ot *OptTester) Stats(d *datadriven.TestData) (string, error)

Stats compares the estimated statistics of a relational expression with actual statistics collected from running CREATE STATISTICS on the output of the relational expression. If the -rewrite-actual-stats flag is used, the actual stats are recalculated.

type RuleSet Uses

type RuleSet = util.FastIntSet

RuleSet efficiently stores an unordered set of RuleNames.

Package opttester imports 37 packages (graph). Updated 2019-12-07. Refresh now. Tools for package owners.