Module com.darkcollective.relix.processor
Package com.darkcollective.relix.processor.internal

Interface DataSourceConnector

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CsvDataSourceConnector, GeneratorDataSourceConnector, HttpDataSourceConnector, JdbcDataSourceConnector, JsonFileDataSourceConnector
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface DataSourceConnector extends AutoCloseable
Plug-in boundary between the query executor and an external data source.

Implementations supply a Stream of Rows for a named relation backed by data that lives outside the .relix script itself — for example, a JDBC database table or an HTTP/CSV endpoint.

inline relations are served directly from the symbol table without going through this interface; the executor only calls a connector for database and source relations.

The returned stream must be closed by the caller after use. Connector implementations should wrap their underlying resources (JDBC ResultSet, HTTP response body, etc.) in a stream that releases those resources on close.

A connector is free to choose either shape, and both are in the tree: the CSV, JSON, and HTTP connectors read their whole payload before building a stream, so theirs holds nothing; the JDBC connector's is lazy over a live ResultSet and holds that ResultSet, its Statement, and a pooled Connection until closed. Because the lazy shape exists, the engine treats every row stream as a resource — see the child-stream lifecycle rule on ChildDispatch, which is what makes a blocking operator close the input it drains.

This is a functional interface: simple connectors can be supplied as lambdas.

Native-query pushdown

When the planner folds a selection/projection/limit sub-tree over a database connection into a single native query, it emits a PhysicalNode.PushedScan and the executor calls openQuery(java.lang.String, java.lang.String, com.darkcollective.relix.symbol.Schema). The default implementation throws, so only connectors that understand the native query language (e.g. the JDBC connector) need to override it; a plan over a pushdown-incapable connector simply never produces a PushedScan.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Releases any resources the connector holds (e.g.
    Stream<Row>
    open(String relationName, Schema schema)
    Opens a stream of rows for the named relation.
    default Stream<Row>
    openQuery(String connection, String nativeQuery, Schema schema)
    Runs a pushed-down native query on a named connection and streams the result.
    default Stream<Row>
    openQuery(String connectorType, String connection, String nativeQuery, Schema schema)
    Runs a pushed-down native query, dispatching by the connection's connectorType: a SQL string for a jdbc connection, an aggregation pipeline for a mongodb connection, etc.

  • Method Details

    • open

      Stream<Row> open(String relationName, Schema schema)
      Opens a stream of rows for the named relation.
      Parameters:
      relationName - the canonical (lower-cased) relation name
      schema - the expected schema; may be used to map source columns to the correct positions and types
      Returns:
      a stream of rows; the caller is responsible for closing it
      Throws:
      EvaluationException - if the relation cannot be opened

    • close

      default void close()
      Releases any resources the connector holds (e.g. a pool of database connections). The default does nothing, so simple lambda connectors need not implement it; resource-backed connectors override it. Overrides do not throw checked exceptions, so try-with-resources needs no extra catch.
      Specified by:
      close in interface AutoCloseable

    • openQuery

      default Stream<Row> openQuery(String connection, String nativeQuery, Schema schema)
      Runs a pushed-down native query on a named connection and streams the result.

      Columns are read positionally, in schema order, so the query's result column order must match schema. The default implementation rejects pushdown; connectors that support native-query execution override it.

      Parameters:
      connection - the canonical name of the connection to run the query on
      nativeQuery - the backend-native query text (SQL for JDBC, etc.)
      schema - the expected output schema; columns are read by position
      Returns:
      a stream of rows; the caller is responsible for closing it
      Throws:
      EvaluationException - if the query cannot be run

    • openQuery

      default Stream<Row> openQuery(String connectorType, String connection, String nativeQuery, Schema schema)
      Runs a pushed-down native query, dispatching by the connection's connectorType: a SQL string for a jdbc connection, an aggregation pipeline for a mongodb connection, etc. The default ignores the type and delegates to openQuery(String, String, Schema), so a single-backend connector (e.g. the JDBC connector) need only override the three-argument form; a composite connector overrides this to route by type.
      Parameters:
      connectorType - the connection's connector type token (e.g. "jdbc", "mongodb")
      connection - the canonical name of the connection to run the query on
      nativeQuery - the backend-native query text
      schema - the expected output schema
      Returns:
      a stream of rows; the caller is responsible for closing it
      Throws:
      EvaluationException - if the query cannot be run