Polymorphic table functions

[findepi]

Add support for polymorphic table functions (https://www.iso.org/standard/69776.html)

related PRs: https://github.com/trinodb/trino/pull/11336 https://github.com/trinodb/trino/pull/12350 https://github.com/trinodb/trino/pull/12338

This document was moved from: https://github.com/trinodb/trino/issues/11937 It serves the following purposes:

1. Decompose, prioritise and schedule the work.
2. Provide visibility into state of the task.
3. Provide a place for discussion and questions.

Definitions

A Table Function is a function which returns a relation, as opposed to a scalar function which returns a single value. A Polymorphic Table Function (PTF) is a Table Function which fulfils at least one of the following conditions:

• the row type of the returned table is not known at the time when the function is created
• the function takes a table as an argument, whose row type is not known when the function is created

Specifically, the output type of the Polymorphic Table Function may depend on the arbitrary table passed as an argument.

Scope of the task

The scope of the task is to provide full support for Table Functions, including Polymorphic Table Functions.

Subtasks

• [X] Add language support for PTF invocation

  • [X] grammar
  • [X] AST representation
  • [X] tests

• [x] Add SPI support for declaring PTFs by connectors

  • [x] The main interface: ConnectorTableFunction
    • [X] analyze(): a method for required and custom analysis
    • [X] Analysis: a class to provide the required and custom analysis results to Trino Analyzer
    • [X] ConnectorTableFunctionHandle: an interface for passing the custom analysis results
    • [x] fulfil(): a method to provide the function logic to Trino
  • [X] Classes representing argument declarations, and returned type declaration
  • [X] Classes representing the actual passed arguments

• [X] Add mechanism for registering PTFs

  • [X] Add TableFunctionRegistry with table function resolution
    • [X] Use path resolution
  • [X] Add register - unregister mechanisms

• [X] Analyze PTF invocation

  • [X] scalar arguments
  • [X] DESCRIPTOR arguments
  • [X] TABLE arguments
  • [X] tests

• [X] Plan PTF invocation

  • [X] Add a dedicated PlanNode: TableFunctionNode
  • [X] Implement relevant PlanVisitors
  • [X] Explain

• [X] Execute PTF through pushdown to connector

  • [X] Add apply() methods
  • [X] Add RewriteTableFunctionToTableScan Optimizer rule

• [X] Add example PTF implementations: query pass-through

  • [x] query function for JDBC connectors:
    • [x] Druid
    • [x] MemSql
    • [x] MySql
    • [x] Oracle
    • [x] PostgreSql
    • [x] Redshift
    • [x] SqlServer
    • [x] MariaDB
    • [x] SingleStore
  • [x] raw_query function for Elasticsearch connector
  • [x] tests

Achieved functionality

Currently, any PTF can be supported, which can be entirely realised by a connector. The connector can "capture" the PTF invocation, and replace it with a ConnectorTableHandle, which represents the PTF result.

Following work

To provide full support for PTF, as in the SQL standard, we need to:

• [x] Support TABLE arguments (starting from the Analyzer)
• [x] Support DESCRIPTOR arguments (starting from the Analyzer)
• [x] EXPLAIN: think of rendering TABLE arguments, which are both function arguments, and PlanNode sources
• [x] Support optimizations of plans involving TableFunctionNode: column pruning, etc
• [x] Implement COPARTITION as JOIN
• [x] Choose distribution of sources, regarding size, number of sources, and row/set semantics (see: DetermineJoinDistributionType)
• [x] Handle TableFunctionNode in AddExchanges / AddLocalExchanges: realise the partitioning and ordering of input tables respecting their actual properties. Also, consider the output properties of TableFunctionNode.
• [x] Figure out the interfaces between the PTF logic (the fulfil() method), and the Operator: in what form data will be provided to the PTF logic, and in what form the results will be returned to the Operator
• [x] Add the Operator:
  • [x] arbitrary number of sources: 0 to n
  • [x] final partitioning and sorting of the sources (see: WindowOperator)
  • [x] invoking the PTF logic on cartesian product of the partitions from all the sources (see: Nested Loops for implementation choices)
  • [x] appending the pass-through columns and the partitioning columns from the source tables

Follow-ups

Possible improvements to be implemented if desired:

• [ ] Optimize hash generation for TableFunctionProcessorNode with HashGenerationOptimizer. notes: requires outputting the hash symbol; hash symbol has no marker symbol.
• [ ] Prune table function's unreferenced proper outputs so that the function does not produce them. Requires new api to negotiate with the function.
• [ ] Prune table function's pass-through columns. If all pass-through columns from a certain source are unreferenced, the function could skip producing the pass-through index column for such source. Requires new api to negotiate with the function.
• [ ] Decompose a table function with set semantics (like aggregations are decomposed into partial and final). With set semantics, each partition is processed on a single node. When no partitioning is specified, the whole input constitutes a single partition which is processed on a single node. Decomposition would allow to split partitions into streams and perform partial computations in parallel. Requires new interfaces to determine if and how the function can be decomposed.
• [ ] Enhance user and developer documentation with examples

[emerson-zhao]

How's it going now?

[tooptoop4]

I guess this would be like MSSQL 'Linked Server' functionality: https://docs.microsoft.com/en-us/sql/t-sql/functions/openquery-transact-sql?view=sql-server-ver15 / https://docs.microsoft.com/en-us/sql/relational-databases/linked-servers/linked-servers-database-engine?view=sql-server-ver15

[buremba]

The issue looks old, is there any interest in implementing table functions at the moment?

It would be great if we can add the support for syntax as a start.

[findepi]

https://github.com/trinodb/trino/pull/11336 is just merged

[zhicwu]

Quick question: will mutation be supported? Sometimes we issue multi-statement query(or just a stored procedure) on target database, where the last statement is for updating.

I noticed Query not supported: ResultSetMetaData not available for query in unit test, but I'm not sure if this will be addressed in the future or it's by design - perhaps you can fixed metadata(e.g. affected_rows Long) for non-query statements?

[findepi]

Quick question: will mutation be supported? Sometimes we issue multi-statement query(or just a stored procedure) on target database, where the last statement is for updating.

@zhicwu you may want to see https://github.com/trinodb/trino/pull/12322

I noticed Query not supported: ResultSetMetaData not available for query in unit test, but I'm not sure if this will be addressed in the future or it's by design

https://github.com/trinodb/trino/pull/12325 is by design for queries reading data.

[zhicwu]

Thanks @findepi. Does it make sense to you to support PTF by both embedded jdbc connector and external bridge server? I think clickhouse-jdbc-bridge is something very similar to the latter. It's just an inmature thought, but maybe I can rewrite jdbc bridge to benefit both sides.

[findepi]

The feature is generally available. The various follow-ups possible, or bugs like https://github.com/trinodb/trino/issues/20398 are tracked as separate issues.

awesome work @kasiafi