@uwdata/mosaic-core/dist/src/preagg/PreAggregator.d.ts

Scalable and extensible linked data views.

import { ExprNode, SelectQuery, MaybeArray, TableRefNode } from '@uwdata/mosaic-sql';
import type { Coordinator } from '../Coordinator.js';
import type { MosaicClient } from '../MosaicClient.js';
import type { Selection } from '../Selection.js';
import type { ClauseSource, SelectionClause } from '../SelectionClause.js';
declare const Skip: {
    skip: boolean;
    result: null;
};
export interface PreAggregateOptions {
    /** Database schema (namespace) in which to write pre-aggregated materialized views (default 'mosaic'). */
    schema?: string;
    /** Flag to enable or disable the pre-aggregation. This flag can be updated later via the `enabled` property. */
    enabled?: boolean;
}
type ActivePredicate = (p?: ExprNode) => MaybeArray<ExprNode> | undefined;
interface ActiveColumnsResult {
    source: ClauseSource | null;
    columns?: Record<string, ExprNode>;
    predicate?: ActivePredicate;
}
interface PreAggregateInfoOptions {
    table: TableRefNode;
    create: SelectQuery;
    active: ActiveColumnsResult;
    select: SelectQuery;
}
/**
 * Build and query optimized pre-aggregated materaialized views, for fast
 * computation of groupby aggregate queries over compatible client queries
 * and selections. The materialized views contains pre-aggregated data for a
 * Mosaic client, subdivided by possible query values from an active selection
 * clause. These materialized views are database tables that can be queried
 * for rapid updates.
 *
 * Compatible client queries must consist of only groupby dimensions and
 * supported aggregate functions. Compatible selections must contain an active
 * clause that exposes metadata for an interval or point value predicate.
 *
 * Materialized views are written to a dedicated schema (namespace) that
 * can be set using the *schema* constructor option. This schema acts as a
 * persistent cache, and materialized view tables may be used across sessions.
 * The `dropSchema` method issues a query to remove *all* tables within this
 * schema. This may be needed if the original tables have updated data, but
 * should be used with care.
 */
export declare class PreAggregator {
    entries: Map<MosaicClient, PreAggregateInfo | typeof Skip | null>;
    private active;
    private mc;
    private _schema;
    private _enabled;
    /**
     * Create a new manager of materialized views of pre-aggregated data.
     * @param coordinator A Mosaic coordinator.
     * @param options Pre-aggregation options.
     */
    constructor(coordinator: Coordinator, { schema, enabled }?: PreAggregateOptions);
    /**
     * Set the enabled state of this manager. If false, any local state is
     * cleared and subsequent request calls will return null until re-enabled.
     * This method has no effect on any pre-aggregated tables already in the
     * database.
     * @param state The enabled state to set.
     */
    set enabled(state: boolean);
    /**
     * Get the enabled state of this manager.
     * @returns The current enabled state.
     */
    get enabled(): boolean;
    /**
     * Set the database schema used for pre-aggregated materialized view tables.
     * Upon changes, any local state is cleared. This method does _not_ drop any
     * existing materialized views, use `dropSchema` before changing the schema
     * to also remove existing materalized views in the database.
     * @param schema The schema name to set.
     */
    set schema(schema: string);
    /**
     * Get the database schema used for pre-aggregated materialized view tables.
     * @returns The current schema name.
     */
    get schema(): string;
    /**
     * Issues a query through the coordinator to drop the current schema for
     * pre-aggregated materialized views. *All* materialized view tables in the
     * schema will be removed and local state is cleared. Call this method if
     * the underlying base tables have been updated, causing materialized view
     * to become stale and inaccurate. Use this method with care! Once dropped,
     * the schema will be repopulated by future pre-aggregation requests.
     * @returns A query result promise.
     */
    dropSchema(): Promise<unknown>;
    /**
     * Clear the cache of pre-aggregation entries for the current active
     * selection clause. This method does _not_ drop any existing materialized
     * views. Use `dropSchema` to remove existing materialized view tables from
     * the database.
     */
    clear(): void;
    /**
     * Return pre-aggregation information for the active state of a
     * client-selection pair, or null if the client has unstable filters.
     * This method has multiple possible side effects, including materialized
     * view creation and updating internal caches.
     * @param client A Mosaic client.
     * @param selection A Mosaic selection to filter the client by.
     * @param activeClause A representative active selection
     *  clause for which to generate materialized views of pre-aggregates.
     * @returns Information and query generator
     * for pre-aggregated tables, or null if the client has unstable filters.
     */
    request(client: MosaicClient, selection: Selection, activeClause: SelectionClause | null): PreAggregateInfo | typeof Skip | null;
}
/**
 * Metadata and query generator for materialized views of pre-aggregated data.
 * This object provides the information needed to generate and query the
 * materialized views for a client-selection pair relative to a specific
 * active clause and selection state.
 */
export declare class PreAggregateInfo {
    /** The name of the materialized view. */
    table: TableRefNode;
    /** The SQL query used to generate the materialized view. */
    create: SelectQuery;
    /** A result promise returned for the materialized view creation query. */
    result: Promise<unknown> | null;
    /** Definitions and predicate function for the active columns,
     * which are dynamically filtered by the active clause. */
    active: ActiveColumnsResult;
    /** Select query (sans where clause) for materialized views. */
    select: SelectQuery;
    /** Boolean flag indicating a client that should be skipped.
     * This value is always false for a created materialized view. */
    skip: boolean;
    /**
     * Create a new pre-aggregation information instance.
     * @param options Options object.
     */
    constructor({ table, create, active, select }: PreAggregateInfoOptions);
    /**
     * Generate a materialized view query for the given predicate.
     * @param predicate The current active clause predicate.
     * @returns A materialized view query.
     */
    query(predicate: ExprNode): SelectQuery;
}
export {};
//# sourceMappingURL=PreAggregator.d.ts.map