@uwdata/mosaic-core/dist/src/SelectionClause.d.ts

Scalable and extensible linked data views.

import { MosaicClient } from './MosaicClient.js';
import type { ExprNode, ExprValue, ScaleOptions, ScaleDomain } from '@uwdata/mosaic-sql';
import { contains, prefix, regexp_matches, suffix } from '@uwdata/mosaic-sql';
/**
 * Selection clause metadata to guide possible query optimizations.
 * Sub-interfaces provide more information about the specifics of a
 * given selection based on the selection type.
 */
export interface ClauseMetadata {
    /**
     * The selection type, such as `'point'`, `'interval'`, or `'match'`.
     */
    type: string;
}
/**
 * Selection clause metadata indicating selection of one or more discrete
 * point values, typically based on equality or is distinctiveness checks.
 */
export interface PointMetadata extends ClauseMetadata {
    type: 'point';
}
/**
 * Selection clause metadata indicating text search matching.
 */
export interface MatchMetadata extends ClauseMetadata {
    type: 'match';
    /** The text search matching method used. */
    method?: 'contains' | 'prefix' | 'suffix' | 'regexp' | (string & {});
}
/** A binning method name. */
export type BinMethod = 'floor' | 'ceil' | 'round';
/**
 * Selection clause metadata for one or more selected intervals. This
 * metadata can be used to determine appropriate data-space binning
 * schemes that correspond to pixel-level bins in screen space.
 */
export interface IntervalMetadata extends ClauseMetadata {
    type: 'interval';
    /**
     * The interactive pixel size used by the generating component.
     * Values larger than one indicate intervals that "snap-to" values
     * greater than a single pixel. If unspecified, assumed to be `1`.
     */
    pixelSize?: number;
    /**
     * An array of one or more scale descriptors that describe the
     * mapping from data values to screen pixels.
     */
    scales?: ScaleOptions[];
    /**
     * A hint for the binning method to use when discretizing the
     * interval domain. If unspecified, the default is `'floor'`.
     */
    bin?: BinMethod;
}
export type ClauseSource = object & {
    reset?: () => void;
};
/**
 * A selection clause representing filtering criteria
 * to apply within a Mosaic Selection.
 */
export interface SelectionClause {
    /**
     * A unique identifier (according to object equality) for the source
     * component that generated this clause. In many cases, this is a
     * reference to the originating component itself.
     */
    source: ClauseSource;
    /**
     * A set of Mosaic clients associated with this clause that should not
     * be updated when this clause is applied in a cross-filtering context.
     */
    clients?: Set<MosaicClient>;
    /**
     * A selected value associated with this clause. For example, for a 1D
     * interval selection clause the value may be a [lo, hi] array.
     */
    value: unknown;
    /**
     * A predicate SQL expression suitable for use in a query WHERE clause.
     * The predicate should apply filtering criteria consistent with this
     * clause's *value* property.
     */
    predicate: ExprNode | null;
    /**
     * Optional clause metadata that varies based on the selection type.
     * The metadata can be used to optimize selection queries, for example
     * by creating materialized views of pre-aggregated data when applicable.
     */
    meta?: ClauseMetadata;
}
interface PointOptions {
    source: ClauseSource;
    clients?: Set<MosaicClient>;
}
/**
 * Generate a selection clause for a single selected point value.
 * @param field The table column or expression to select.
 * @param value The selected value.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients The Mosaic clients associated
 *  with this clause. These clients are not filtered by this clause in
 *  cross-filtering contexts.
 * @returns The generated selection clause.
 */
export declare function clausePoint(field: ExprValue, value: unknown, { source, clients }: PointOptions): SelectionClause;
/**
 * Generate a selection clause for multiple selected point values.
 * @param fields The table columns or expressions to select.
 * @param value The selected values, as an array of
 *  arrays. Each subarray contains values for each *fields* entry.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients The Mosaic clients associated
 *  with this clause. These clients are not filtered by this clause in
 *  cross-filtering contexts.
 * @returns The generated selection clause.
 */
export declare function clausePoints(fields: ExprValue[], value: unknown[][] | null | undefined, { source, clients }: PointOptions): SelectionClause;
/** Interval selection clause options. */
interface IntervalOptions {
    source: ClauseSource;
    clients?: Set<MosaicClient>;
    bin?: BinMethod;
    pixelSize?: number;
}
/**
 * Generate a selection clause for a selected 1D interval.
 * @param field The table column or expression to select.
 * @param value The selected interval as a [lo, hi] array.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients The Mosaic clients associated
 *  with this clause. These clients are not filtered by this clause in
 *  cross-filtering contexts.
 * @param options.scale The scale mapping descriptor.
 * @param options.bin A binning method hint.
 * @param options.pixelSize The interactive pixel size.
 * @returns The generated selection clause.
 */
export declare function clauseInterval(field: ExprValue, value: ScaleDomain | null | undefined, { source, clients, bin, scale, pixelSize }: IntervalOptions & {
    scale?: ScaleOptions;
}): SelectionClause;
/**
 * Generate a selection clause for multiple selected intervals.
 * @param fields The table columns or expressions to select.
 * @param value The selected intervals, as an array of extents.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients The Mosaic clients associated
 *  with this clause. These clients are not filtered by this clause in
 *  cross-filtering contexts.
 * @param options.scales The scale mapping descriptors,
 *  in an order matching the given *fields* and *value* extents.
 * @param options.bin A binning method hint.
 * @param options.pixelSize The interactive pixel size.
 * @returns The generated selection clause.
 */
export declare function clauseIntervals(fields: ExprValue[], value: ScaleDomain[] | null | undefined, { source, clients, bin, scales, pixelSize }: IntervalOptions & {
    scales?: ScaleOptions[];
}): SelectionClause;
declare const MATCH_METHODS: {
    contains: typeof contains;
    prefix: typeof prefix;
    suffix: typeof suffix;
    regexp: typeof regexp_matches;
};
/** Text search matching methods. */
export type MatchMethod = keyof typeof MATCH_METHODS;
/** Text matching selection clause options. */
export interface MatchOptions {
    source: ClauseSource;
    clients?: Set<MosaicClient>;
    method?: MatchMethod;
    caseSensitive?: boolean;
}
/**
 * Generate a selection clause for text search matching over a single column.
 * @param field The table column or expression to match.
 * @param value The selected text search query string.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients Mosaic clients associated with this clause.
 *  These clients are not filtered by this clause in cross-filtering contexts.
 * @param options.method The text matching method to use, default `'contains'`.
 * @param options.caseSensitive Flag for case sensitive matching, default `false`.
 * @returns The generated selection clause.
 */
export declare function clauseMatch(field: string | ExprNode, value: string | null | undefined, { source, clients, method, caseSensitive }: MatchOptions): SelectionClause;
/**
 * Generate a selection clause for text search matching over multiple columns.
 * A match will succeed if any field successfully matches.
 * @param fields The table columns or expressions to match.
 * @param value The selected text search query string.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients Mosaic clients associated with this clause.
 *  These clients are not filtered by this clause in cross-filtering contexts.
 * @param options.method The text matching method to use, default `'contains'`.
 * @param options.caseSensitive Flag for case sensitive matching, default `false`.
 * @returns The generated selection clause.
 */
export declare function clauseMatchAny(fields: (string | ExprNode)[], value: string | null, { source, clients, method, caseSensitive }: MatchOptions): SelectionClause;
/**
 * Generate a selection clause for a single selected point value in a list.
 * @param field The table column or expression to select, which must be a list.
 * @param value The selected value.
 * @param options Additional clause properties.
 * @param options.source The source component generating this clause.
 * @param options.clients The Mosaic clients associated
 *  with this clause. These clients are not filtered by this clause in
 *  cross-filtering contexts.
 * @returns The generated selection clause.
 */
export declare function clauseList(field: ExprValue, value: unknown, { source, clients, listMatch }: {
    source: ClauseSource;
    clients?: Set<MosaicClient>;
    listMatch?: 'any' | 'all';
}): SelectionClause;
export {};
//# sourceMappingURL=SelectionClause.d.ts.map