Module com.darkcollective.relix.semantic
Package com.darkcollective.relix.semantic

Interface CatalogProvider

All Known Implementing Classes:
CatalogSnapshot
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 CatalogProvider
Supplies table metadata for database connections during semantic analysis.

This is the seam through which the analyzer learns the schema of a table referenced by a connection (e.g. sales.orders) when no schema was declared in the script. A real implementation introspects the live database; the default NONE resolves nothing, so dotted references without a declared schema produce a clear "schema unavailable" error in offline use.

The seam also supplies optional RelationStatistics (row counts, keys) for the cost model via tableStatistics(com.darkcollective.relix.lang.ast.ConnectionDeclaration, java.lang.String), and the tables a connection holds via tables(com.darkcollective.relix.lang.ast.ConnectionDeclaration); both default to Optional.empty(), so a schema-only provider needs no extra work.

  • Field Details

    • NONE

      static final CatalogProvider NONE
      A provider that resolves nothing — the default for offline analysis.

  • Method Details

    • tableSchema

      Optional<Schema> tableSchema(ConnectionDeclaration connection, String table)
      Returns the output schema of table within connection, or Optional.empty() if it cannot be determined.
      Parameters:
      connection - the declared connection the table belongs to
      table - the (possibly schema-qualified) remote table name
      Returns:
      the table's schema, or empty if unavailable

    • tableStatistics

      default Optional<RelationStatistics> tableStatistics(ConnectionDeclaration connection, String table)
      Returns optimizer statistics (row count, keys) for table within connection, or Optional.empty() if none are available.

      The default returns empty; introspecting providers override this to query the live catalog. Statistics are advisory: a missing or partial value never affects correctness, only the quality of cost-based decisions.

      Parameters:
      connection - the declared connection the table belongs to
      table - the (possibly schema-qualified) remote table name
      Returns:
      the table's statistics, or empty if unavailable

    • tables

      default Optional<List<String>> tables(ConnectionDeclaration connection)
      Returns the names of the tables connection holds, as far as this provider knows them, or Optional.empty() if it cannot enumerate them.

      The analyser uses the list to suggest a table when a reference names one the provider cannot describe, as it already suggests a column. The default returns empty, which suits live introspection: asking a database for every table to correct one typo is not a cost worth paying during analysis. A provider holding a fixed set of tables, such as a CatalogSnapshot, lists them.

      Parameters:
      connection - the declared connection
      Returns:
      the table names, as a reference would spell them after the connection's name; or empty if this provider cannot enumerate them

    • sourceSchema

      default Optional<Schema> sourceSchema(SourceDeclaration source)
      Returns the heading of a source that declares none, read from what the source names — the start of a CSV file whose schema was left out — or Optional.empty() if this provider does not read sources.

      Unlike a table's schema, there is no declaration to fall back on: a source that left its schema out has its heading here or nowhere. So a provider that reads the source and cannot — the file is missing, or holds no header to name its columns — says why by throwing, and the analyser reports that rather than a column it cannot find. The default reads nothing.

      Parameters:
      source - the declaration, its placeholders resolved
      Returns:
      the source's heading, or empty if this provider does not read sources
      Throws:
      RuntimeException - naming the source when it is read and cannot be described
      Since:
      1.0