@malloydata/malloy 0.0.434 → 0.0.436

package/dist/connection/dbmeta.js

@@ -0,0 +1,46 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbmetaProperty = exports.DBMETA_ROUTE = void 0;
+exports.dbmetaAnnotations = dbmetaAnnotations;
+const malloy_tag_1 = require("@malloydata/malloy-tag");
+/**
+ * The annotation route a connection writes database metadata to:
+ * `#(dbmeta) description="..."`.
+ */
+exports.DBMETA_ROUTE = 'dbmeta';
+const DBMETA_LOCATION = {
+    url: `internal://${exports.DBMETA_ROUTE}`,
+    range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+};
+/**
+ * The connection property that turns on database metadata. Connections that
+ * support it register this definition, so the option has the same name and
+ * meaning on every backend. Off unless set.
+ */
+exports.dbmetaProperty = {
+    name: 'dbmeta',
+    displayName: 'Database Metadata',
+    type: 'boolean',
+    optional: true,
+    advanced: true,
+    description: 'Copy table and column descriptions from the database onto the schema, ' +
+        'as #(dbmeta) description annotations.',
+};
+/**
+ * The `#(dbmeta)` annotation for a table or column, as a fragment to spread
+ * into its field or table def: `{annotations}`, or `{}` when there is nothing
+ * to say.
+ */
+function dbmetaAnnotations(meta) {
+    var _a;
+    const description = (_a = meta.description) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!description)
+        return {};
+    const text = `#(${exports.DBMETA_ROUTE}) description=${(0, malloy_tag_1.quoteString)(description)}\n`;
+    return { annotations: { notes: [{ text, at: DBMETA_LOCATION }] } };
+}
+//# sourceMappingURL=dbmeta.js.map

package/dist/connection/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './base_connection';
 export * from './registry';
+export * from './dbmeta';

package/dist/connection/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./base_connection"), exports);
 __exportStar(require("./registry"), exports);
+__exportStar(require("./dbmeta"), exports);
 //# sourceMappingURL=index.js.map

package/dist/dialect/databricks/databricks.d.ts

@@ -1,5 +1,5 @@
-import type { Sampling, MeasureTimeExpr, RegexMatchExpr, TimeExtractExpr, TypecastExpr, BasicAtomicTypeDef, AtomicTypeDef, ArrayLiteralNode, RecordLiteralNode } from '../../model/malloy_types';
-import type { BooleanTypeSupport, CompiledOrderBy, DialectFieldList, FieldReferenceType, LateralJoinExpression, OrderByClauseType, OrderByRequest, QueryInfo } from '../dialect';
+import type { Sampling, MeasureTimeExpr, RegexMatchExpr, TypecastExpr, BasicAtomicTypeDef, AtomicTypeDef, ArrayLiteralNode, RecordLiteralNode, ATimestampTypeDef, TimestampUnit, ExtractUnit } from '../../model/malloy_types';
+import type { CivilTime, BooleanTypeSupport, CompiledOrderBy, DialectFieldList, FieldReferenceType, LateralJoinExpression, OrderByClauseType, OrderByRequest, QueryInfo } from '../dialect';
 import { Dialect } from '../dialect';
 import type { DialectFunctionOverloadDef } from '../functions';
 export declare class DatabricksDialect extends Dialect {
@@ -66,18 +66,17 @@ export declare class DatabricksDialect extends Dialect {
     sqlSelectAliasAsStruct(alias: string, fieldList: DialectFieldList): string;
     sqlCreateTableAsSelect(tableName: string, sql: string): string;
     sqlNowExpr(): string;
-    sqlConvertToCivilTime(expr: string, timezone: string, _typeDef: AtomicTypeDef): {
-        sql: string;
-        typeDef: AtomicTypeDef;
-    };
-    sqlConvertFromCivilTime(expr: string, timezone: string, _destTypeDef: AtomicTypeDef): string;
-    sqlTruncate(expr: string, unit: string, _typeDef: AtomicTypeDef, _inCivilTime: boolean, _timezone?: string): string;
-    sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: string, _typeDef: AtomicTypeDef, _inCivilTime: boolean, _timezone?: string): string;
-    sqlTimeExtractExpr(qi: QueryInfo, te: TimeExtractExpr): string;
-    sqlCast(qi: QueryInfo, cast: TypecastExpr): string;
+    sqlConvertToCivilTime(expr: string, timezone: string, _typeDef: ATimestampTypeDef): string;
+    sqlConvertFromCivilTime(expr: string, timezone: string, _destTypeDef: ATimestampTypeDef): string;
+    sqlTruncate(expr: string, unit: TimestampUnit, _civilType: CivilTime): string;
+    sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: TimestampUnit, _civilType: CivilTime): string;
+    sqlCivilExtract(expr: string, units: ExtractUnit, _civilType: CivilTime): string;
+    sqlCivilToDate(expr: string): string;
+    sqlDateToCivil(expr: string): string;
+    sqlCast(_qi: QueryInfo, cast: TypecastExpr): string;
     sqlRegexpMatch(df: RegexMatchExpr): string;
     sqlDateLiteral(_qi: QueryInfo, literal: string): string;
-    sqlTimestampLiteral(qi: QueryInfo, literal: string, timezone: string | undefined): string;
+    sqlCivilLiteral(literal: string): string;
     sqlTimestamptzLiteral(_qi: QueryInfo, _literal: string, _timezone: string): string;
     sqlMeasureTimeExpr(df: MeasureTimeExpr): string;
     sqlSampleTable(tableSQL: string, sample: Sampling | undefined): string;

package/dist/dialect/databricks/databricks.js

@@ -300,19 +300,19 @@ class DatabricksDialect extends dialect_1.Dialect {
     sqlNowExpr() {
         return 'CURRENT_TIMESTAMP()';
     }
+    // Civil time is a TIMESTAMP whose reading in the session zone, UTC, is
+    // the civil time
     sqlConvertToCivilTime(expr, timezone, _typeDef) {
-        // Databricks has no timestamptz type; timestamps are stored as UTC
-        // Convert from UTC to local timezone for civil time operations
-        return {
-            sql: `FROM_UTC_TIMESTAMP(${expr}, ${this.sqlTimezoneLiteral(timezone)})`,
-            typeDef: { type: 'timestamp' },
-        };
+        return timezone === 'UTC'
+            ? expr
+            : `FROM_UTC_TIMESTAMP(${expr}, ${this.sqlTimezoneLiteral(timezone)})`;
     }
     sqlConvertFromCivilTime(expr, timezone, _destTypeDef) {
-        // Convert from local timezone back to UTC
-        return `TO_UTC_TIMESTAMP(${expr}, ${this.sqlTimezoneLiteral(timezone)})`;
+        return timezone === 'UTC'
+            ? expr
+            : `TO_UTC_TIMESTAMP(${expr}, ${this.sqlTimezoneLiteral(timezone)})`;
     }
-    sqlTruncate(expr, unit, _typeDef, _inCivilTime, _timezone) {
+    sqlTruncate(expr, unit, _civilType) {
         // Databricks DATE_TRUNC starts weeks on Monday; Malloy wants Sunday.
         // Add 1 day before truncating, subtract 1 day after.
         if (unit === 'week') {
@@ -320,7 +320,7 @@ class DatabricksDialect extends dialect_1.Dialect {
         }
         return `DATE_TRUNC('${unit}', ${expr})`;
     }
-    sqlOffsetTime(expr, op, magnitude, unit, _typeDef, _inCivilTime, _timezone) {
+    sqlOffsetTime(expr, op, magnitude, unit, _civilType) {
         // Use TIMESTAMPADD which accepts expressions for magnitude,
         // unlike INTERVAL which only accepts literals in Databricks.
         let offsetUnit = unit.toUpperCase();
@@ -336,31 +336,23 @@ class DatabricksDialect extends dialect_1.Dialect {
         const n = op === '+' ? offsetMag : `-(${offsetMag})`;
         return `TIMESTAMPADD(${offsetUnit}, ${n}, ${expr})`;
     }
-    sqlTimeExtractExpr(qi, te) {
-        const units = extractionMap[te.units] || te.units;
-        let extractFrom = te.e.sql;
-        if (malloy_types_1.TD.isTimestamp(te.e.typeDef)) {
-            const tz = (0, dialect_1.qtz)(qi);
-            if (tz) {
-                extractFrom = `FROM_UTC_TIMESTAMP(${extractFrom}, ${this.sqlTimezoneLiteral(tz)})`;
-            }
-        }
-        if (extractionMap[te.units]) {
+    sqlCivilExtract(expr, units, _civilType) {
+        const extractUnits = extractionMap[units];
+        if (extractUnits) {
             // DAYOFWEEK, DAYOFYEAR are functions
-            return `${units}(${extractFrom})`;
+            return `${extractUnits}(${expr})`;
         }
-        return `EXTRACT(${units} FROM ${extractFrom})`;
+        return `EXTRACT(${units} FROM ${expr})`;
+    }
+    sqlCivilToDate(expr) {
+        return `CAST(${expr} AS DATE)`;
+    }
+    sqlDateToCivil(expr) {
+        return `CAST(${expr} AS TIMESTAMP)`;
     }
-    sqlCast(qi, cast) {
+    sqlCast(_qi, cast) {
         const srcSQL = cast.e.sql || 'internal-error-in-sql-generation';
-        const { op, srcTypeDef, dstTypeDef, dstSQLType } = this.sqlCastPrep(cast);
-        const tz = (0, dialect_1.qtz)(qi);
-        if (op === 'timestamp::date' && tz) {
-            return `CAST(FROM_UTC_TIMESTAMP(${srcSQL}, ${this.sqlTimezoneLiteral(tz)}) AS DATE)`;
-        }
-        else if (op === 'date::timestamp' && tz) {
-            return `TO_UTC_TIMESTAMP(CAST(${srcSQL} AS TIMESTAMP_NTZ), ${this.sqlTimezoneLiteral(tz)})`;
-        }
+        const { srcTypeDef, dstTypeDef, dstSQLType } = this.sqlCastPrep(cast);
         if (!malloy_types_1.TD.eq(srcTypeDef, dstTypeDef)) {
             if (cast.safe) {
                 return `TRY_CAST(${srcSQL} AS ${dstSQLType})`;
@@ -378,11 +370,7 @@ class DatabricksDialect extends dialect_1.Dialect {
     sqlDateLiteral(_qi, literal) {
         return `DATE '${literal}'`;
     }
-    sqlTimestampLiteral(qi, literal, timezone) {
-        const tz = timezone || (0, dialect_1.qtz)(qi);
-        if (tz) {
-            return `TO_UTC_TIMESTAMP(TIMESTAMP_NTZ '${literal}', ${this.sqlTimezoneLiteral(tz)})`;
-        }
+    sqlCivilLiteral(literal) {
         return `TIMESTAMP '${literal}'`;
     }
     sqlTimestamptzLiteral(_qi, _literal, _timezone) {

package/dist/dialect/dialect.d.ts

@@ -1,4 +1,4 @@
-import type { Expr, Sampling, AtomicTypeDef, MeasureTimeExpr, TimeExtractExpr, TypecastExpr, RegexMatchExpr, TimeLiteralExpr, RecordLiteralNode, ArrayLiteralNode, BasicAtomicTypeDef, OrderBy, TimestampUnit, ATimestampTypeDef, TimeExpr, TemporalFieldType } from '../model/malloy_types';
+import type { Expr, Sampling, AtomicTypeDef, MeasureTimeExpr, TimeExtractExpr, TypecastExpr, RegexMatchExpr, TimeLiteralExpr, RecordLiteralNode, ArrayLiteralNode, BasicAtomicTypeDef, OrderBy, TimestampUnit, ATimestampTypeDef, TimeExpr, TemporalFieldType, ExtractUnit } from '../model/malloy_types';
 import type { DialectFunctionOverloadDef } from './functions';
 import type { ValidateTablePathResult } from './table-path';
 /**
@@ -68,10 +68,26 @@ export interface QueryInfo {
     queryTimezone?: string;
     systemTimezone?: string;
 }
+/**
+ * The two kinds of civil time: a calendar date, and a date with a time of
+ * day. Neither has a zone.
+ */
+export declare const CivilTime: {
+    readonly Date: "date";
+    readonly DateAndTime: "date_and_time";
+};
+export type CivilTime = (typeof CivilTime)[keyof typeof CivilTime];
+/** Add or subtract `magnitude` units of time */
+export interface TimeOffset {
+    op: '+' | '-';
+    magnitude: string;
+    unit: TimestampUnit;
+}
 export type FieldReferenceType = 'table' | 'nest source' | 'array[scalar]' | 'array[record]' | 'record';
 export declare const dayIndex: number;
 export declare function inDays(units: string): boolean;
-export declare function qtz(qi: QueryInfo): string | undefined;
+/** The query time zone, or UTC when the query has none. */
+export declare function queryZone(qi: QueryInfo): string;
 /**
  * The per-element condition for an aggregate turtle (sqlAggregateTurtle). On
  * the normal path it gates each row by its group_set (and a projection's own
@@ -83,6 +99,7 @@ export declare function qtz(qi: QueryInfo): string | undefined;
  */
 export declare function turtleGroupSetCondition(groupSet: number | undefined, filterSQL: string | undefined): string | undefined;
 export type OrderByClauseType = 'output_name' | 'ordinal' | 'expression';
+export type GroupByClauseType = 'ordinal' | 'expression';
 export type OrderByRequest = 'query' | 'turtle' | 'analytical';
 export type BooleanTypeSupport = 'supported' | 'simulated' | 'none';
 /**
@@ -115,6 +132,14 @@ export declare abstract class Dialect {
     abstract supportsSafeCast: boolean;
     abstract supportsNesting: boolean;
     abstract experimental: boolean;
+    /**
+     * What the compiler consults, not `experimental` itself. The test harness
+     * calls `acceptExperimental()` on the dialect under test so the shared
+     * suites can run on an experimental dialect without every test enabling it.
+     */
+    private experimentalAccepted;
+    isExperimental(): boolean;
+    acceptExperimental(): void;
     cantPartitionWindowFunctionsOnExpressions: boolean;
     sqlLateralJoinBag(_expressions: LateralJoinExpression[]): string;
     supportsPipelinesInViews: boolean;
@@ -123,6 +148,9 @@ export declare abstract class Dialect {
     hasTimestamptz: boolean;
     readsNestedData: boolean;
     orderByClause: OrderByClauseType;
+    groupByClause: GroupByClauseType;
+    /** The ordering and row limit which end a SELECT stage */
+    sqlOrderByLimit(orderTerms: string[], limit: number | undefined): string;
     nullMatchesFunctionSignature: boolean;
     supportsSelectReplace: boolean;
     supportsBigIntPrecision: boolean;
@@ -140,6 +168,7 @@ export declare abstract class Dialect {
     compoundObjectInSchema: boolean;
     booleanType: BooleanTypeSupport;
     likeEscape: boolean;
+    likeExtraWildcards: string[];
     /**
      * Mappings from integer value ranges to Malloy number types.
      *
@@ -270,175 +299,43 @@ export declare abstract class Dialect {
     sqlLiteralNumber(literal: string): string;
     ignoreInProject(_fieldName: string): boolean;
     abstract sqlNowExpr(): string;
-    abstract sqlTimeExtractExpr(qi: QueryInfo, xFrom: TimeExtractExpr): string;
     abstract sqlMeasureTimeExpr(e: MeasureTimeExpr): string;
     /**
-     * Generate SQL for type casting expressions.
-     *
-     * Most casts are simple: `CAST(expr AS type)` or `TRY_CAST(expr AS type)` for safe casts.
-     *
-     * However, when a query timezone is set, casts between temporal types (date, timestamp, timestamptz)
-     * require special handling to ensure correct timezone semantics:
-     *
-     * **Timezone-Aware Cast Semantics:**
-     *
-     * 1. **TIMESTAMP → DATE**:
-     *    - TIMESTAMP represents UTC wall clock
-     *    - Convert to query timezone, then extract date
-     *    - Example: TIMESTAMP '2020-02-20 00:00:00' with tz 'America/Mexico_City' → '2020-02-19'
-     *
-     * 2. **TIMESTAMPTZ → DATE**:
-     *    - TIMESTAMPTZ represents absolute instant
-     *    - Convert to query timezone, then extract date
-     *    - Example: TIMESTAMPTZ '2020-02-20 00:00:00 UTC' with tz 'America/Mexico_City' → '2020-02-19'
-     *
-     * 3. **DATE → TIMESTAMP**:
-     *    - DATE represents civil date
-     *    - Interpret as midnight in query timezone, return UTC wall clock
-     *    - Example: DATE '2020-02-20' with tz 'America/Mexico_City' → TIMESTAMP '2020-02-20 06:00:00' (UTC)
-     *
-     * 4. **DATE → TIMESTAMPTZ**:
-     *    - DATE represents civil date
-     *    - Interpret as midnight in query timezone, create instant
-     *    - Example: DATE '2020-02-20' with tz 'America/Mexico_City' → instant at 2020-02-20 06:00:00 UTC
-     *
-     * 5. **TIMESTAMPTZ → TIMESTAMP**:
-     *    - TIMESTAMPTZ represents absolute instant
-     *    - Extract wall clock in query timezone, return as TIMESTAMP
-     *    - Example: TIMESTAMPTZ '2020-02-20 00:00:00 UTC' with tz 'America/Mexico_City' → TIMESTAMP '2020-02-19 18:00:00'
-     *
-     * 6. **TIMESTAMP → TIMESTAMPTZ**:
-     *    - TIMESTAMP represents UTC wall clock
-     *    - Interpret as being in query timezone
-     *    - Example: TIMESTAMP '2020-02-20 00:00:00' with tz 'America/Mexico_City' → instant at 2020-02-20 06:00:00 UTC
-     *
-     * **Implementation Notes:**
-     *
-     * - Dialects without timestamptz support (MySQL, BigQuery, StandardSQL) only need cases 1-3
-     * - Without query timezone, most casts are simple `CAST(expr AS type)`
-     *
-     * @param qi - Query info containing timezone and other context
-     * @param cast - The typecast expression to generate SQL for
-     * @returns SQL string for the cast operation
+     * Generate SQL for a cast. Casts between date, timestamp and timestamptz
+     * never reach here; they are made by sqlTimeCast.
      */
     abstract sqlCast(qi: QueryInfo, cast: TypecastExpr): string;
     abstract sqlRegexpMatch(df: RegexMatchExpr): string;
+    /** The civil time which `timezone` shows at the instant `expr`. */
+    abstract sqlConvertToCivilTime(expr: string, timezone: string, typeDef: ATimestampTypeDef): string;
     /**
-     * Converts a Malloy timestamp to "civil time" for calendar operations in a timezone.
-     *
-     * Each dialect selects its own SQL type to represent civil time (e.g., plain TIMESTAMP,
-     * TIMESTAMP WITH TIME ZONE, or DATETIME). The civil space is where timezone-aware
-     * truncation and interval arithmetic happen. Operations like sqlTruncate and sqlOffsetTime
-     * are aware of the civil space and work correctly within it.
-     *
-     * @param expr The SQL expression for the Malloy timestamp (plain or timestamptz)
-     * @param timezone The target timezone for civil operations
-     * @param typeDef The Malloy type of the input expression
-     * @returns Object with SQL expression and the SQL type it evaluates to (the civil type)
-     */
-    abstract sqlConvertToCivilTime(expr: string, timezone: string, typeDef: AtomicTypeDef): {
-        sql: string;
-        typeDef: AtomicTypeDef;
-    };
-    /**
-     * Converts from civil time back to a Malloy timestamp type.
-     *
-     * This is the inverse of sqlConvertToCivilTime. Takes a value in the dialect's
-     * civil space and converts it back to either a plain timestamp (UTC) or a
-     * timestamptz, depending on the destination type.
-     *
-     * @param expr The SQL expression in civil time
-     * @param timezone The timezone of the civil time
-     * @param destTypeDef The destination Malloy timestamp type (plain or timestamptz)
-     * @returns SQL expression representing the Malloy timestamp
+     * The instant at which `timezone` shows the civil time `expr`, as a
+     * value of `destTypeDef`.
      */
     abstract sqlConvertFromCivilTime(expr: string, timezone: string, destTypeDef: ATimestampTypeDef): string;
+    /** The start of the unit containing `expr`. A week starts on Sunday. */
+    abstract sqlTruncate(expr: string, unit: TimestampUnit, civilType: CivilTime): string;
+    abstract sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: TimestampUnit, civilType: CivilTime): string;
+    /** One field of `expr`. A day_of_week counts from 1 on Sunday. */
+    abstract sqlCivilExtract(expr: string, units: ExtractUnit, civilType: CivilTime): string;
+    /** The date part of the civil time `expr`. */
+    abstract sqlCivilToDate(expr: string): string;
+    /** Midnight at the start of the date `expr`, as civil time. */
+    abstract sqlDateToCivil(expr: string): string;
+    /** The civil time written as `literal`, 'YYYY-MM-DD HH:MM:SS'. */
+    abstract sqlCivilLiteral(literal: string): string;
+    sqlTimeExtractExpr(qi: QueryInfo, from: TimeExtractExpr): string;
     /**
-     * Truncates a time expression to the specified unit.
-     *
-     * @param expr The SQL expression to truncate
-     * @param unit The unit to truncate to (year, month, day, hour, etc.)
-     * @param typeDef The Malloy type of the expression (date, timestamp, etc.)
-     * @param inCivilTime If true, the expression is already in civil (local) time and should not
-     *                    be converted. If false, may need timezone conversion for timestamps.
-     * @param timezone Optional timezone for the operation. Only provided when timezone-aware
-     *                 truncation is needed but inCivilTime is false.
-     * @returns SQL expression representing the truncated time
-     */
-    abstract sqlTruncate(expr: string, unit: TimestampUnit, typeDef: AtomicTypeDef, inCivilTime: boolean, timezone?: string): string;
-    /**
-     * Adds or subtracts a time interval from a time expression.
-     *
-     * @param expr The SQL expression to offset
-     * @param op The operation: '+' for addition, '-' for subtraction
-     * @param magnitude The SQL expression for the interval magnitude (e.g., '6', '(delta_val)')
-     * @param unit The interval unit (year, month, day, hour, etc.)
-     * @param typeDef The Malloy type of the expression (date, timestamp, etc.)
-     * @param inCivilTime If true, the expression is already in civil (local) time and should not
-     *                    be converted. If false, may need timezone conversion for timestamps.
-     * @param timezone Optional timezone for the operation. Only provided when timezone-aware
-     *                 offset is needed but inCivilTime is false.
-     * @returns SQL expression representing the offset time
-     */
-    abstract sqlOffsetTime(expr: string, op: '+' | '-', magnitude: string, unit: TimestampUnit, typeDef: AtomicTypeDef, inCivilTime: boolean, timezone?: string): string;
-    /**
-     * Determines whether a truncation and/or offset operation needs to be performed in
-     * civil (local) time, and if so, which timezone to use.
-     *
-     * Calendar-based operations (day, week, month, quarter, year) typically need civil time
-     * computation because these units can cross DST boundaries, changing the UTC offset.
-     *
-     * Default implementation:
-     * - Returns true for timestamps with truncation or calendar-unit offsets
-     * - Uses the query timezone from QueryInfo, or 'UTC' if none specified
-     * - Returns false for dates or sub-day offsets (hour, minute, second)
-     *
-     * Dialects can override this if they have different rules about which operations
-     * require civil time computation.
-     *
-     * @param typeDef The Malloy type of the base expression
-     * @param truncateTo The truncation unit, if any
-     * @param offsetUnit The offset unit, if any
-     * @param qi Query information including timezone settings
-     * @returns Object with `needed` boolean and optional `tz` string
+     * Truncation and/or offset, the offset applied after the truncation.
+     * Doing both in one pass converts to and from civil time only once.
      */
-    needsCivilTimeComputation(typeDef: AtomicTypeDef, truncateTo: TimestampUnit | undefined, offsetUnit: TimestampUnit | undefined, qi: QueryInfo): {
-        needed: boolean;
-        tz: string | undefined;
-    };
+    sqlTruncAndOffset(baseExpr: TimeExpr, qi: QueryInfo, truncateTo?: TimestampUnit, offset?: TimeOffset): string;
+    private civilTruncAndOffset;
     /**
-     * Unified function for truncation and/or offset operations. This turns out to
-     * be a very common operation and one which can be optimized by doing it together.
-     *
-     * Much of the complexity has to do with getting timezone values set up so that
-     * they will truncate/offset in the query timezone instead of UTC.
-     *
-     * The intention is that this implementation will work for all dialects, and all
-     * the dialect peculiarities are handled with the new primitives introduced to
-     * support this function:
-     * - needsCivilTimeComputation: Determines if operation needs civil time
-     * - sqlConvertToCivilTime/sqlConvertFromCivilTime: Timezone conversion
-     * - sqlTruncate: Truncation operation
-     * - sqlOffsetTime: Interval arithmetic
-     *
-     * OFFSET TIMESTAMP BEHAVIOR:
-     * - Plain timestamps (offset=false): Always return plain TIMESTAMP in UTC
-     * - Offset timestamps (offset=true):
-     *   - Simple path: Operate in native embedded timezone, return TIMESTAMPTZ
-     *   - Civil path: Convert to query timezone (preserving instant), operate there,
-     *     return TIMESTAMPTZ in query timezone via sqlConvertFromCivilTime
-     * - BigQuery/MySQL: No offset timestamp support, this logic never runs
-     *
-     * @param baseExpr The time expression to operate on (already compiled, with .sql populated)
-     * @param qi Query information including timezone
-     * @param truncateTo Optional truncation unit (year, month, day, etc.)
-     * @param offset Optional offset to apply (after truncation if both present)
+     * A cast between date, timestamp and timestamptz, or undefined for any
+     * other cast.
      */
-    sqlTruncAndOffset(baseExpr: TimeExpr, qi: QueryInfo, truncateTo?: TimestampUnit, offset?: {
-        op: '+' | '-';
-        magnitude: string;
-        unit: TimestampUnit;
-    }): string;
+    sqlTimeCast(qi: QueryInfo, cast: TypecastExpr): string | undefined;
     /**
      * Generate SQL for a DATE literal.
      * @param literal - The date string in format 'YYYY-MM-DD'
@@ -446,18 +343,10 @@ export declare abstract class Dialect {
      */
     abstract sqlDateLiteral(qi: QueryInfo, literal: string): string;
     /**
-     * Generate SQL for a plain TIMESTAMP literal (without timezone offset).
-     * @param literal - The timestamp string in format 'YYYY-MM-DD HH:MM:SS'
-     * @param timezone - Optional timezone name (e.g., 'America/Los_Angeles')
-     *   - If undefined: Create plain timestamp literal from the literal string
-     *   - If defined: The literal string represents a civil time in the given timezone.
-     *     Convert it to a plain timestamp (typically by interpreting as timestamptz
-     *     in that timezone, then casting to plain timestamp). This happens when:
-     *     1. A constant with timezone is used (constants don't have dialect context)
-     *     2. A literal with timezone is used in a dialect that doesn't support offset timestamps
-     * @returns SQL that produces a plain TIMESTAMP value
+     * The timestamp at which `timezone`, or the query time zone when there is
+     * none, shows the civil time `literal`.
      */
-    abstract sqlTimestampLiteral(qi: QueryInfo, literal: string, timezone: string | undefined): string;
+    sqlTimestampLiteral(qi: QueryInfo, literal: string, timezone: string | undefined): string;
     /**
      * Generate SQL for an offset TIMESTAMP literal (TIMESTAMP WITH TIME ZONE).
      * Only called for dialects where hasOffsetTimestamp = true.
@@ -503,7 +392,7 @@ export declare abstract class Dialect {
     exprToSQL(qi: QueryInfo, df: Expr): string | undefined;
     sqlSumDistinct(_key: string, _value: string, _funcName: string): string;
     sqlAggDistinct(_key: string, _values: string[], _func: (valNames: string[]) => string): string;
-    sqlSampleTable(tableSQL: string, sample: Sampling | undefined): string;
+    sqlSampleTable(tableSQL: string, sample: Sampling | undefined, _onBaseTable?: boolean): string;
     /**
      * MySQL is NULLs first, all other dialects have a way to make NULLs last.
      * isBaseOrdering is a hack to allow the MySQL dialect to partially implement
@@ -535,6 +424,16 @@ export declare abstract class Dialect {
      * SQL to generate to get a boolean value for a boolean expression
      */
     sqlBoolean(bv: boolean): string;
+    /**
+     * Malloy's `not`: of NULL, true. A dialect with booleanType 'none' has no
+     * boolean value for COALESCE to return, so the test is written as a
+     * condition.
+     */
+    sqlNot(condition: string): string;
+    /**
+     * A condition Malloy defines as true when SQL says NULL: `!=` and `!~`
+     */
+    sqlNullIsTrue(condition: string): string;
     /**
      * What a boolean value looks like in a query result
      */