github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/sql/sem/tree/generators.go (about)

     1  // Copyright 2017 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  package tree
    12  
    13  import (
    14  	"context"
    15  
    16  	"github.com/cockroachdb/cockroach/pkg/kv"
    17  	"github.com/cockroachdb/cockroach/pkg/sql/types"
    18  )
    19  
    20  // Table generators, also called "set-generating functions", are
    21  // special functions that return an entire table.
    22  //
    23  // Overview of the concepts:
    24  //
    25  // - ValueGenerator is an interface that offers a
    26  //   Start/Next/Values/Stop API similar to sql.planNode.
    27  //
    28  // - because generators are regular functions, it is possible to use
    29  //   them in any expression context. This is useful to e.g
    30  //   pass an entire table as argument to the ARRAY( ) conversion
    31  //   function.
    32  //
    33  // - the data source mechanism in the sql package has a special case
    34  //   for generators appearing in FROM contexts and knows how to
    35  //   construct a special row source from them.
    36  
    37  // ValueGenerator is the interface provided by the value generator
    38  // functions for SQL SRfs. Objects that implement this interface are
    39  // able to produce rows of values in a streaming fashion (like Go
    40  // iterators or generators in Python).
    41  type ValueGenerator interface {
    42  	// ResolvedType returns the type signature of this value generator.
    43  	ResolvedType() *types.T
    44  
    45  	// Start initializes the generator. Must be called once before
    46  	// Next() and Values(). It can be called again to restart
    47  	// the generator after Next() has returned false.
    48  	//
    49  	// txn represents the txn that the generator will run inside of. The generator
    50  	// is expected to hold on to this txn and use it in Next() calls.
    51  	Start(ctx context.Context, txn *kv.Txn) error
    52  
    53  	// Next determines whether there is a row of data available.
    54  	Next(context.Context) (bool, error)
    55  
    56  	// Values retrieves the current row of data.
    57  	Values() (Datums, error)
    58  
    59  	// Close must be called after Start() before disposing of the
    60  	// ValueGenerator. It does not need to be called if Start() has not
    61  	// been called yet. It must not be called in-between restarts.
    62  	Close()
    63  }
    64  
    65  // GeneratorFactory is the type of constructor functions for
    66  // ValueGenerator objects.
    67  type GeneratorFactory func(ctx *EvalContext, args Datums) (ValueGenerator, error)