Package org.apache.juneau.beanquery.sql

Interface SqlDialect

All Known Implementing Classes:
PostgresDialect
public interface SqlDialect
The SQL-generation strategy for a SQL BeanQueryContext: it quotes identifiers, renders each built-in $-operator into a dialect-correct predicate, and renders pagination.

The shared JDBC context (the juneau-beanquery-sql module) is dialect-agnostic plumbing: it walks a parsed search tree, delegates every leaf to the dialect, and combines leaves with AND/OR/NOT itself. All dialect-specific SQL text — identifier quoting, the built-in operator predicates, the LIMIT/ OFFSET clause — lives here. A custom operator instead carries its own SearchSqlRenderer (attached with SearchOperator.Builder.extension); the context calls that renderer, passing this dialect so it can branch on id().

Juneau ships exactly one dialect today (Postgres, in juneau-beanquery-postgres). A dialect returns null from builtinRenderer(String) for any built-in it cannot express (for example $regex on a database without regex support), and the context then rejects the query with BAD_VALUE rather than emitting SQL that differs from the in-memory result.

Example:

SqlDialect dialect = PostgresDialect.INSTANCE; SqlFragment frag = dialect.renderBare(dialect.quote("status"), SearchType.ENUM, "OPEN", false); // frag.sql() == "lower(\"status\"::text) = lower(?)", frag.binds() == ["OPEN"] // A NUMERIC column receives the already-typed value, not the raw token. SqlFragment age = dialect.renderBare(dialect.quote("age"), SearchType.NUMERIC, new BigDecimal("30"), false); // age.sql() == "\"age\" = ?", age.binds() == [30]

Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    SearchSqlRenderer
    builtinRenderer(String operatorName)
    The renderer for a built-in leaf operator (for example "$eq"), or null if this dialect cannot express it.
    String
    id()
    The stable lowercase dialect id (for example "postgres").
    String
    quote(String identifier)
    Quotes a column or table identifier for this dialect (for example age → "age").
    SqlFragment
    renderBare(String columnSql, SearchType type, Object value, boolean quoted)
    Renders a bare pattern term (design §5.1) — text with optional */? wildcards, a version prefix, or an exact value for the other types — into a predicate.
    String
    renderLimitOffset(Long limit, Long offset)
    Renders the pagination clause appended to a SELECT (for example " LIMIT 10 OFFSET 20").
    default boolean
    supportsVersionOrdering()
    Whether this dialect orders SearchType.VERSION columns as dotted integer tuples, like the in-memory engine (so 9.10 is greater than 9.9).

  • Method Details

    • id

      String id()
      The stable lowercase dialect id (for example "postgres").
      Returns:
      The dialect id, never null or blank.

    • quote

      String quote(String identifier)
      Quotes a column or table identifier for this dialect (for example age → "age").
      Parameters:
      identifier - The raw identifier. Must not be null.
      Returns:
      The quoted identifier.

    • renderBare

      SqlFragment renderBare(String columnSql, SearchType type, Object value, boolean quoted)
      Renders a bare pattern term (design §5.1) — text with optional */? wildcards, a version prefix, or an exact value for the other types — into a predicate.
      Parameters:
      columnSql - The dialect-quoted column reference. Must not be null.
      type - The column's value type. Must not be null.
      value - The literal's already-typed value (SearchExpression.typedValue()): a BigDecimal for NUMERIC, a Boolean for BOOLEAN, an OffsetDateTime, LocalDateTime or LocalDate for TIMESTAMP, and the already-$$-decoded String for TEXT, ID, ENUM and VERSION. Must not be null.
      quoted - Whether the literal was quoted in the search string; a quoted literal is never given wildcard interpretation, even if it contains * or ?.
      Returns:
      The predicate fragment.

    • builtinRenderer

      SearchSqlRenderer builtinRenderer(String operatorName)
      The renderer for a built-in leaf operator (for example "$eq"), or null if this dialect cannot express it.

      The context calls this only for built-in leaves; it handles the $and/$or/$not combinators itself. A null return makes the context fail with a clear error rather than emit wrong SQL.

      Parameters:
      operatorName - The built-in operator name, including the leading $. Must not be null.
      Returns:
      The renderer, or null if unsupported.

    • supportsVersionOrdering

      default boolean supportsVersionOrdering()
      Whether this dialect orders SearchType.VERSION columns as dotted integer tuples, like the in-memory engine (so 9.10 is greater than 9.9).

      When false (the default), a range or ordering operator ($gt, $gte, $lt, $lte, $between) on a VERSION column is rejected with BAD_VALUE instead of silently comparing text (where 9.10 sorts before 9.9). Equality, $in, $ne and $prefix are not affected.

      Example:

      // A dialect that compares versions as integer tuples opts in. @Override public boolean supportsVersionOrdering() { return true; }

      Returns:
      true if version range comparisons match the in-memory semantics.

    • renderLimitOffset

      String renderLimitOffset(Long limit, Long offset)
      Renders the pagination clause appended to a SELECT (for example " LIMIT 10 OFFSET 20").

      The limit/offset are inlined as integer literals (never bind values), so the returned text carries no placeholders.

      Parameters:
      limit - The maximum row count, or null for no limit.
      offset - The zero-based start offset, or null/0 for none.
      Returns:
      The pagination clause (possibly empty, never null).