Module org.apache.derby.engine
Package org.apache.derby.vti

## Interface VTICosting

-     public interface VTICosting

  VTICosting is the interface that the query optimizer uses to cost Table Functions. The methods on this interface provide the optimizer with the following information:

  - The estimated number of rows returned by the Table Function in a single instantiation.
  - The estimated cost to instantiate and iterate through the Table Function.
  - Whether or not the Table Function can be instantiated multiple times within a single query execution.

  The optimizer places a Table Function in the join order after making some assumptions:

  - Cost - The optimizer hard-codes a guess about how expensive it is to materialize a Table Function.
  - Count - The optimizer also hard-codes a guess about how many rows a Table Function returns.
  - Repeatability - The optimizer assumes that the same results come back each time you invoke a Table Function.

  The class which contains your Table Function can override these assumptions and improve the join order as follows:

  - Implement - The class must implement VTICosting.
  - Construct - The class must contain a public, no-arg constructor.

  The methods in this interface take a VTIEnvironment argument. This is a state variable created by the optimizer. The methods in this interface can use this state variable to pass information to one another and learn other details of the operating environment.

  See Also:
    `VTIEnvironment`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static double` | `defaultEstimatedCost` | A useful constant: The default estimated cost of instantiating and iterating throught a Table Function.
    `static double` | `defaultEstimatedRowCount` | A useful constant: the default estimated number of rows returned by a Table Function.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `double` | `getEstimatedCostPerInstantiation​(VTIEnvironment vtiEnvironment)` | Get the estimated cost for a single instantiation of a Table Function.
    `double` | `getEstimatedRowCount​(VTIEnvironment vtiEnvironment)` | Get the estimated row count for a single scan of a Table Function.
    `boolean` | `supportsMultipleInstantiations​(VTIEnvironment vtiEnvironment)` | Find out if the ResultSet of the Table Function can be instantiated multiple times.

- - ### Field Detail

    - #### defaultEstimatedRowCount

          static final double defaultEstimatedRowCount

      A useful constant: the default estimated number of rows returned by a Table Function.
      See Also:
        Constant Field Values

    - #### defaultEstimatedCost

          static final double defaultEstimatedCost

      A useful constant: The default estimated cost of instantiating and iterating throught a Table Function.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getEstimatedRowCount

          double getEstimatedRowCount​(VTIEnvironment vtiEnvironment)
                               throws SQLException

      Get the estimated row count for a single scan of a Table Function.
      Parameters:
        `vtiEnvironment` - The state variable for optimizing the Table Function.
      Returns:
        The estimated row count for a single scan of the Table Function.
      Throws:
        `SQLException` - thrown if the costing fails.

    - #### getEstimatedCostPerInstantiation

          double getEstimatedCostPerInstantiation​(VTIEnvironment vtiEnvironment)
                                           throws SQLException

      Get the estimated cost for a single instantiation of a Table Function.
      Parameters:
        `vtiEnvironment` - The state variable for optimizing the Table Function.
      Returns:
        The estimated cost for a single instantiation of the Table Function.
      Throws:
        `SQLException` - thrown if the costing fails.

    - #### supportsMultipleInstantiations

          boolean supportsMultipleInstantiations​(VTIEnvironment vtiEnvironment)
                                          throws SQLException

      Find out if the ResultSet of the Table Function can be instantiated multiple times.
      Parameters:
        `vtiEnvironment` - The state variable for optimizing the Table Function.
      Returns:
        True if the ResultSet can be instantiated multiple times, false if can only be instantiated once.
      Throws:
        `SQLException` - thrown if the costing fails.