@loaders.gl/core 5.0.0-alpha.12 → 5.0.0-alpha.13

package/dist/loader-utils/lib/scan-utils/scan-query-metadata.d.ts

@@ -0,0 +1,272 @@
+import type { DataType, FieldMetadata, Schema } from '@loaders.gl/core/schema';
+import type { ColumnarPredicate, ColumnarPredicateProperty } from "./columnar-predicate.js";
+import type { TableQueryCapabilities, TableQueryOperatorSupport, TableQueryOptions } from "./table-query.js";
+import type { PointCloudQueryOptions } from "./point-cloud-query.js";
+import type { RasterQueryCapabilities } from "./raster-query.js";
+import type { TableQueryExplain } from "./table-query-explain.js";
+import { type SpatialReference } from '@math.gl/geospatial/crs';
+/** Semantic role used by query editors to choose appropriate controls for a column. */
+export type ScanColumnRole = 'attribute' | 'identifier' | 'geometry' | 'longitude' | 'latitude' | 'x' | 'y' | 'z' | 'time' | 'intensity' | 'classification' | 'color';
+/** Schema information for one selectable or filterable scan column. */
+export type ScanColumnMetadata = Readonly<{
+    /** Stable source column name used by projections and predicates. */
+    name: string;
+    /** Portable loaders.gl data type. */
+    type: DataType;
+    /** Whether the source may produce null values for the column. */
+    nullable: boolean;
+    /** Semantic role used to select specialized query controls. */
+    role: ScanColumnRole;
+    /** Optional display title obtained from source field metadata. */
+    title?: string;
+    /** Optional human-readable description obtained from source field metadata. */
+    description?: string;
+    /** Original field metadata for source-specific UI extensions. */
+    metadata: Readonly<FieldMetadata>;
+}>;
+/** Axis-aligned source bounds expressed in the source coordinate reference system. */
+export type ScanBounds = Readonly<{
+    /** Inclusive minimum coordinate for each available dimension. */
+    minimum: readonly number[];
+    /** Inclusive maximum coordinate for each available dimension. */
+    maximum: readonly number[];
+}>;
+/** Spatial discovery information shared by vector, point-cloud, and raster query editors. */
+export type ScanSpatialMetadata = Readonly<{
+    /** Source bounds, when declared by format metadata. */
+    bounds?: ScanBounds;
+    /** Coordinate reference system identifiers or definitions advertised by the source. */
+    coordinateReferenceSystems?: readonly string[];
+    /** Normalized source CRS discovery for bounds and coordinate columns. */
+    spatialReference?: SpatialReference;
+}>;
+/** One raster resolution level exposed to a scan query editor. */
+export type ScanRasterLevel = Readonly<{
+    /** Zero-based level index in the source pyramid. */
+    index: number;
+    /** Pixel width at this level. */
+    width: number;
+    /** Pixel height at this level. */
+    height: number;
+    /** Optional scale relative to the full-resolution level. */
+    scale?: readonly [number, number];
+}>;
+/** Capabilities that a common scan-query panel can expose across source families. */
+export type ScanQueryCapabilities = Readonly<{
+    /** Relational projection, predicate, limit, streaming, and cancellation support. */
+    table?: TableQueryCapabilities;
+    /** Spatial bounds support when it is not already represented by a scalar predicate. */
+    bounds?: TableQueryOperatorSupport;
+    /** Hierarchy or resolution selection support for point clouds and multiscale rasters. */
+    levelOfDetail?: TableQueryOperatorSupport;
+    /** Raster variable, slice, window, streaming, and cancellation support. */
+    raster?: RasterQueryCapabilities;
+}>;
+/** Lightweight source statistics obtained without materializing result rows. */
+export type ScanSourceStatistics = Readonly<{
+    /** Exact or estimated source row/feature/point count. */
+    rowCount?: number | bigint;
+    /** Physical byte length when it is available from source metadata. */
+    byteLength?: number | bigint;
+}>;
+/** Common source method that executes the query described by scan metadata. */
+export type ScanExecutionMethod = 'read' | 'query' | 'getRaster' | 'scan';
+/**
+ * Conclusive execution status advertised by a scan-aware source.
+ *
+ * `supported` identifies the common method applications can call today. `metadata-only` means the
+ * source can populate discovery UI but deliberately does not claim common scan execution.
+ */
+export type ScanExecutionSupport = Readonly<{
+    /** The source executes common scan requests. */
+    status: 'supported';
+    /** Public source method that executes the request. */
+    method: ScanExecutionMethod;
+}> | Readonly<{
+    /** The source only supports query metadata discovery. */
+    status: 'metadata-only';
+    /** Concrete missing execution capability shown to users and documentation tooling. */
+    reason: string;
+}>;
+/** Metadata used to populate a source-neutral query editor before executing a scan. */
+export type ScanQueryMetadata = Readonly<{
+    /** Stable adapter or format identifier. */
+    sourceType: string;
+    /** Query family used to enable table, point-cloud, or raster controls. */
+    queryType: 'table' | 'point-cloud' | 'raster';
+    /** Conclusive common execution status and entry point. */
+    execution: ScanExecutionSupport;
+    /** Optional source display name. */
+    name?: string;
+    /** Optional source description. */
+    description?: string;
+    /** Complete query-visible schema, including geometry or coordinate columns. */
+    schema: Schema;
+    /** Query-visible columns in source order. */
+    columns: readonly ScanColumnMetadata[];
+    /** Portable and source-family-specific execution capabilities. */
+    capabilities: ScanQueryCapabilities;
+    /** Optional spatial metadata used to populate bounds controls. */
+    spatial?: ScanSpatialMetadata;
+    /** Optional statistics obtained from source metadata. */
+    statistics?: ScanSourceStatistics;
+    /** Optional multiscale raster levels. */
+    levels?: readonly ScanRasterLevel[];
+}>;
+/** Options accepted by query metadata discovery methods. */
+export type ScanQueryMetadataOptions = Readonly<{
+    /** Cancels metadata discovery without starting a data scan. */
+    signal?: AbortSignal;
+}>;
+/** Terminal state of one observable scan execution. */
+export type ScanExecutionTelemetryStatus = 'completed' | 'early-terminated' | 'cancelled' | 'failed';
+/** Portable execution counters for one physical source in a federated scan. */
+export type ScanSourceExecutionTelemetry = Readonly<{
+    /** Stable registry id when the source was resolved through a DataSourceManager. */
+    sourceId?: string;
+    /** Format or adapter type reported by scan metadata. */
+    sourceType: string;
+    /** Zero-based append position for a federated source. */
+    sourceIndex?: number;
+    /** Terminal state of this physical source iterator. */
+    status: ScanExecutionTelemetryStatus;
+    /** Physical files opened by this source, when measurable. */
+    filesOpened?: number;
+    /** Independently scheduled physical tasks opened by this source, when measurable. */
+    tasksOpened?: number;
+    /** Response bytes fetched from storage, excluding cache hits, when measurable. */
+    bytesFetched?: number;
+    /** Physical batches decoded before common residual execution. */
+    batchesDecoded: number;
+    /** Rows decoded or received from the physical source. */
+    rowsRead: number;
+    /** Rows evaluated by exact predicates in this source. */
+    rowsTested?: number;
+    /** Rows retained by exact predicates in this source. */
+    rowsRetained?: number;
+    /** Rows emitted by this source to its parent executor. */
+    rowsReturned: number;
+    /** Rows or row groups eliminated using metadata before decoding. */
+    rowsPruned?: number;
+    /** Wall-clock time spent consuming this source. */
+    durationMilliseconds: number;
+    /** Source-specific immutable counters retained for detailed diagnostics. */
+    details?: Readonly<Record<string, unknown>>;
+    /** Failure or cancellation reason when one terminated this source. */
+    error?: unknown;
+}>;
+/** Portable execution counters reported when a table scan terminates. */
+export type ScanExecutionTelemetry = Readonly<{
+    /** Terminal state distinguishing completion, early return, cancellation, and failure. */
+    status: ScanExecutionTelemetryStatus;
+    /** Number of physical sources included in the resolved plan. */
+    sourcesPlanned: number;
+    /** Number of physical source iterators that were opened. */
+    sourcesRead: number;
+    /** Number of physical data batches received from those sources. */
+    batchesRead: number;
+    /** Compatibility-neutral name for physical batches decoded by this execution. */
+    batchesDecoded?: number;
+    /** Number of rows received before residual filtering and the global limit. */
+    rowsRead: number;
+    /** Number of rows evaluated by the executor's residual predicate. */
+    rowsTested?: number;
+    /** Number of rows retained by the executor's residual predicate. */
+    rowsRetained?: number;
+    /** Number of rows emitted to the scan consumer. */
+    rowsReturned: number;
+    /** Physical bytes read when the source can measure them without estimation. */
+    bytesRead?: number;
+    /** Response bytes fetched from storage, excluding cache hits, when measurable. */
+    bytesFetched?: number;
+    /** Physical files opened by this execution, when measurable. */
+    filesOpened?: number;
+    /** Independently scheduled physical tasks opened by this execution, when measurable. */
+    tasksOpened?: number;
+    /** Rows or row groups eliminated using metadata before decoding. */
+    rowsPruned?: number;
+    /** Wall-clock execution time measured by the reporting source. */
+    durationMilliseconds: number;
+    /** Why a successfully shortened execution stopped before exhausting its plan. */
+    earlyTerminationReason?: 'limit' | 'consumer-return';
+    /** Per-source physical counters in deterministic append order. */
+    sources?: readonly ScanSourceExecutionTelemetry[];
+    /** Source-specific immutable counters retained for detailed diagnostics. */
+    details?: Readonly<Record<string, unknown>>;
+    /** Failure or cancellation reason when one terminated the scan. */
+    error?: unknown;
+}>;
+/** Receives the immutable final counters for one table scan execution. */
+export type ScanExecutionTelemetryCallback = (telemetry: ScanExecutionTelemetry) => void;
+/**
+ * Delivers a scan telemetry snapshot without allowing an observer failure to alter scan results.
+ * Telemetry is best-effort by design: exporters and diagnostics must not become query failures.
+ */
+export declare function emitScanExecutionTelemetry(callback: ScanExecutionTelemetryCallback | undefined, telemetry: ScanExecutionTelemetry): void;
+/** Structural interface implemented by sources that support query-panel discovery. */
+export type ScanQueryMetadataProvider = {
+    /** Discovers query-visible columns and capabilities without materializing result rows. */
+    getQueryMetadata(options?: ScanQueryMetadataOptions): Promise<ScanQueryMetadata>;
+};
+/** Query options supplied to a table-scan executor, including cooperative cancellation. */
+export type TableScanReadOptions<PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<unknown, ColumnarPredicateProperty>> = TableQueryOptions<PredicateT> & Readonly<{
+    /** Cooperatively cancels source discovery and execution. */
+    signal?: AbortSignal;
+    /** Receives one terminal execution snapshot without changing query semantics. */
+    onTelemetry?: ScanExecutionTelemetryCallback;
+}>;
+/**
+ * Shared table-scan contract implemented by format-specific executors.
+ *
+ * The metadata method powers source-neutral query controls, while `read()` consumes the same
+ * immutable table-query options and emits ordered batches. Format adapters may extend the options
+ * and batch metadata with source-specific planning details.
+ */
+export type TableScanSource<BatchT = unknown, PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate<unknown, ColumnarPredicateProperty>> = ScanQueryMetadataProvider & {
+    /** Explains the logical plan and physical support without decoding result rows. */
+    explain?(options?: TableScanReadOptions<PredicateT>): Promise<TableQueryExplain<PredicateT>>;
+    /** Reads the query result as ordered batches without changing the logical query semantics. */
+    read(options?: TableScanReadOptions<PredicateT>): AsyncIterable<BatchT>;
+};
+/** Point-cloud scan options with a bound on each emitted Arrow batch. */
+export type PointCloudScanReadOptions = PointCloudQueryOptions & Readonly<{
+    /** Maximum number of retained points in each emitted batch. */
+    batchSize?: number;
+}>;
+/** Shared point-cloud scan contract implemented by hierarchy-backed sources. */
+export type PointCloudScanSource<BatchT = unknown> = ScanQueryMetadataProvider & {
+    /** Reads selected hierarchy nodes as ordered, globally limited point batches. */
+    scan(options?: PointCloudScanReadOptions): AsyncIterable<BatchT>;
+};
+/** Inputs used to derive normalized query metadata from a loaders.gl schema. */
+export type CreateScanQueryMetadataOptions = Readonly<{
+    /** Stable adapter or format identifier. */
+    sourceType: string;
+    /** Query family used to enable specialized controls. */
+    queryType: ScanQueryMetadata['queryType'];
+    /** Conclusive common execution status and entry point. */
+    execution: ScanExecutionSupport;
+    /** Complete query-visible schema. */
+    schema: Schema;
+    /** Portable and source-family-specific execution capabilities. */
+    capabilities: ScanQueryCapabilities;
+    /** Optional source display name. */
+    name?: string;
+    /** Optional source description. */
+    description?: string;
+    /** Optional semantic roles keyed by source column name. */
+    columnRoles?: Readonly<Record<string, ScanColumnRole>>;
+    /** Optional spatial metadata. */
+    spatial?: ScanSpatialMetadata;
+    /** Optional source statistics. */
+    statistics?: ScanSourceStatistics;
+    /** Optional multiscale raster levels. */
+    levels?: readonly ScanRasterLevel[];
+}>;
+/**
+ * Creates immutable query metadata and derives panel-ready columns from a loaders.gl schema.
+ *
+ * Source adapters only need to supply semantic roles that cannot be inferred from Arrow types.
+ */
+export declare function createScanQueryMetadata(options: CreateScanQueryMetadataOptions): ScanQueryMetadata;
+//# sourceMappingURL=scan-query-metadata.d.ts.map

package/dist/loader-utils/lib/scan-utils/scan-query-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-query-metadata.d.ts","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/scan-query-metadata.ts"],"names":[],"mappings":"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"}

package/dist/loader-utils/lib/scan-utils/scan-query-metadata.js

@@ -0,0 +1,97 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { createSpatialReference } from '@math.gl/geospatial/crs';
+/**
+ * Delivers a scan telemetry snapshot without allowing an observer failure to alter scan results.
+ * Telemetry is best-effort by design: exporters and diagnostics must not become query failures.
+ */
+export function emitScanExecutionTelemetry(callback, telemetry) {
+    if (!callback)
+        return;
+    try {
+        callback(telemetry);
+    }
+    catch {
+        // Telemetry observers must never change scan behavior.
+    }
+}
+/**
+ * Creates immutable query metadata and derives panel-ready columns from a loaders.gl schema.
+ *
+ * Source adapters only need to supply semantic roles that cannot be inferred from Arrow types.
+ */
+export function createScanQueryMetadata(options) {
+    validateScanExecutionSupport(options.queryType, options.execution);
+    const schema = Object.freeze({
+        fields: Object.freeze(options.schema.fields.map(field => Object.freeze({ ...field, metadata: Object.freeze({ ...field.metadata }) }))),
+        metadata: Object.freeze({ ...options.schema.metadata })
+    });
+    const columns = schema.fields.map(field => Object.freeze({
+        name: field.name,
+        type: field.type,
+        nullable: field.nullable !== false,
+        role: options.columnRoles?.[field.name] || 'attribute',
+        title: getNonEmptyMetadataValue(field.metadata, 'title'),
+        description: getNonEmptyMetadataValue(field.metadata, 'description'),
+        metadata: field.metadata || Object.freeze({})
+    }));
+    return Object.freeze({
+        sourceType: options.sourceType,
+        queryType: options.queryType,
+        execution: Object.freeze({ ...options.execution }),
+        name: options.name,
+        description: options.description,
+        schema,
+        columns: Object.freeze(columns),
+        capabilities: Object.freeze({ ...options.capabilities }),
+        spatial: options.spatial
+            ? Object.freeze({
+                ...options.spatial,
+                bounds: options.spatial.bounds
+                    ? Object.freeze({
+                        minimum: Object.freeze([...options.spatial.bounds.minimum]),
+                        maximum: Object.freeze([...options.spatial.bounds.maximum])
+                    })
+                    : undefined,
+                coordinateReferenceSystems: options.spatial.coordinateReferenceSystems
+                    ? Object.freeze([...options.spatial.coordinateReferenceSystems])
+                    : undefined,
+                spatialReference: options.spatial.spatialReference
+                    ? createSpatialReference(options.spatial.spatialReference)
+                    : undefined
+            })
+            : undefined,
+        statistics: options.statistics ? Object.freeze({ ...options.statistics }) : undefined,
+        levels: options.levels
+            ? Object.freeze(options.levels.map(level => Object.freeze({
+                ...level,
+                scale: level.scale
+                    ? Object.freeze([...level.scale])
+                    : undefined
+            })))
+            : undefined
+    });
+}
+/** Ensures supported metadata names an entry point appropriate for its query family. */
+function validateScanExecutionSupport(queryType, execution) {
+    if (execution.status === 'metadata-only') {
+        if (!execution.reason.trim()) {
+            throw new Error('Metadata-only scan support requires a concrete reason');
+        }
+        return;
+    }
+    const validMethods = {
+        table: ['read', 'query'],
+        raster: ['getRaster'],
+        'point-cloud': ['scan']
+    };
+    if (!validMethods[queryType].includes(execution.method)) {
+        throw new Error(`Scan execution method "${execution.method}" is not valid for ${queryType} queries`);
+    }
+}
+function getNonEmptyMetadataValue(metadata, key) {
+    const value = metadata?.[key];
+    return value || undefined;
+}
+//# sourceMappingURL=scan-query-metadata.js.map

package/dist/loader-utils/lib/scan-utils/scan-query-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-query-metadata.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/scan-query-metadata.ts"],"names":[],"mappings":"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"}

package/dist/loader-utils/lib/scan-utils/table-query-explain.d.ts

@@ -0,0 +1,39 @@
+import { type ColumnarPredicate, type ColumnarPredicateProperty } from "./columnar-predicate.js";
+import { type TableQueryCapabilities, type TableQueryOptions, type TableQueryPlan, type TableQueryOperatorSupport } from "./table-query.js";
+/** A capability annotation for one operator in an explainable table query. */
+export type TableQueryExplainOperator = Readonly<{
+    /** Whether this operator is present in the requested query. */
+    enabled: boolean;
+    /** Physical implementation available to the backend. */
+    support: TableQueryOperatorSupport;
+}>;
+/** Serializable logical and physical capability information for one table query. */
+export type TableQueryExplain<PredicateT = ColumnarPredicate> = Readonly<{
+    /** Columns exposed by the source before planning. */
+    sourceColumns: readonly string[];
+    /** Columns returned by the query. */
+    outputColumns: readonly string[];
+    /** Columns that must be read to evaluate the query correctly. */
+    requiredColumns: readonly string[];
+    /** Columns referenced by the predicate, including hidden filter columns. */
+    predicateColumns: readonly string[];
+    /** Canonical logical scan plan. */
+    plan: TableQueryPlan<PredicateT>;
+    /** Backend capabilities used to annotate the logical plan. */
+    capabilities: TableQueryCapabilities;
+    /** Per-operator pushed-versus-residual diagnostics. */
+    operators: Readonly<{
+        projection: TableQueryExplainOperator;
+        predicate: TableQueryExplainOperator;
+        limit: TableQueryExplainOperator;
+    }>;
+}>;
+/**
+ * Creates a serializable explanation without executing a table scan.
+ *
+ * This deliberately reports both the backend-neutral plan and the backend's advertised
+ * implementation level. Executors can add source-specific details (for example row-group
+ * pruning) while retaining this stable shape.
+ */
+export declare function explainTableQuery<ValueT, PropertyT extends ColumnarPredicateProperty, PredicateT extends ColumnarPredicate<ValueT, PropertyT>>(sourceColumnNames: readonly string[], options: TableQueryOptions<PredicateT>, capabilities: TableQueryCapabilities): TableQueryExplain<PredicateT>;
+//# sourceMappingURL=table-query-explain.d.ts.map

package/dist/loader-utils/lib/scan-utils/table-query-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-query-explain.d.ts","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/table-query-explain.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC/B,gCAA6B;AAC9B,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,yBAAyB,EAC/B,yBAAsB;AAEvB,8EAA8E;AAC9E,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,OAAO,EAAE,yBAAyB,CAAC;CACpC,CAAC,CAAC;AAEH,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,CAAC,UAAU,GAAG,iBAAiB,IAAI,QAAQ,CAAC;IACvE,qDAAqD;IACrD,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,qCAAqC;IACrC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,iEAAiE;IACjE,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,4EAA4E;IAC5E,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mCAAmC;IACnC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,8DAA8D;IAC9D,YAAY,EAAE,sBAAsB,CAAC;IACrC,uDAAuD;IACvD,SAAS,EAAE,QAAQ,CAAC;QAClB,UAAU,EAAE,yBAAyB,CAAC;QACtC,SAAS,EAAE,yBAAyB,CAAC;QACrC,KAAK,EAAE,yBAAyB,CAAC;KAClC,CAAC,CAAC;CACJ,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EACN,SAAS,SAAS,yBAAyB,EAC3C,UAAU,SAAS,iBAAiB,CAAC,MAAM,EAAE,SAAS,CAAC,EAEvD,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,OAAO,EAAE,iBAAiB,CAAC,UAAU,CAAC,EACtC,YAAY,EAAE,sBAAsB,GACnC,iBAAiB,CAAC,UAAU,CAAC,CAkB/B"}

package/dist/loader-utils/lib/scan-utils/table-query-explain.js

@@ -0,0 +1,35 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { getColumnarPredicateColumns } from "./columnar-predicate.js";
+import { planTableQuery } from "./table-query.js";
+/**
+ * Creates a serializable explanation without executing a table scan.
+ *
+ * This deliberately reports both the backend-neutral plan and the backend's advertised
+ * implementation level. Executors can add source-specific details (for example row-group
+ * pruning) while retaining this stable shape.
+ */
+export function explainTableQuery(sourceColumnNames, options, capabilities) {
+    const plan = planTableQuery(sourceColumnNames, options);
+    const outputColumns = options.columns ? [...options.columns] : [...sourceColumnNames];
+    const predicateColumns = options.predicate ? getColumnarPredicateColumns(options.predicate) : [];
+    const requiredColumns = [...(plan[0].kind === 'scan' ? plan[0].columns : [])];
+    return Object.freeze({
+        sourceColumns: Object.freeze([...sourceColumnNames]),
+        outputColumns: Object.freeze(outputColumns),
+        requiredColumns: Object.freeze(requiredColumns),
+        predicateColumns: Object.freeze(predicateColumns),
+        plan,
+        capabilities: Object.freeze({ ...capabilities }),
+        operators: Object.freeze({
+            projection: createOperatorExplanation(options.columns !== undefined, capabilities.projection),
+            predicate: createOperatorExplanation(options.predicate !== undefined, capabilities.predicate),
+            limit: createOperatorExplanation(options.limit !== undefined, capabilities.limit)
+        })
+    });
+}
+function createOperatorExplanation(enabled, support) {
+    return Object.freeze({ enabled, support });
+}
+//# sourceMappingURL=table-query-explain.js.map

package/dist/loader-utils/lib/scan-utils/table-query-explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-query-explain.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/table-query-explain.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAEpC,OAAO,EACL,2BAA2B,EAG5B,gCAA6B;AAC9B,OAAO,EACL,cAAc,EAKf,yBAAsB;AAgCvB;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAK/B,iBAAoC,EACpC,OAAsC,EACtC,YAAoC;IAEpC,MAAM,IAAI,GAAG,cAAc,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC;IACtF,MAAM,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,MAAM,eAAe,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC;QACpD,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;QAC/C,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;QACjD,IAAI;QACJ,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAC,GAAG,YAAY,EAAC,CAAC;QAC9C,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;YACvB,UAAU,EAAE,yBAAyB,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,YAAY,CAAC,UAAU,CAAC;YAC7F,SAAS,EAAE,yBAAyB,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,YAAY,CAAC,SAAS,CAAC;YAC7F,KAAK,EAAE,yBAAyB,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC;SAClF,CAAC;KACH,CAAC,CAAC;AACL,CAAC;AAED,SAAS,yBAAyB,CAChC,OAAgB,EAChB,OAAkC;IAElC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAC,OAAO,EAAE,OAAO,EAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/loader-utils/lib/scan-utils/table-query.d.ts

@@ -0,0 +1,77 @@
+import { type ColumnarPredicate, type ColumnarPredicateProperty } from "./columnar-predicate.js";
+/** Immutable, backend-neutral request for a scan, filter, projection, and limit. */
+export type TableQueryOptions<PredicateT extends ColumnarPredicate<unknown, ColumnarPredicateProperty> = ColumnarPredicate> = Readonly<{
+    /** Portable predicate applied before projection. */
+    predicate?: PredicateT;
+    /** Output columns in caller-specified order. Defaults to every source column. */
+    columns?: readonly string[];
+    /** Maximum number of rows retained after filtering and projection. */
+    limit?: number;
+    /** Cancels discovery and batch production. */
+    signal?: AbortSignal;
+}>;
+/** Reads the minimum source columns required by the remaining table-query plan. */
+export type TableQueryScanStep = Readonly<{
+    /** Plan discriminator. */
+    kind: 'scan';
+    /** Source columns required for filtering and output. */
+    columns: readonly string[];
+}>;
+/** Applies a portable predicate while all predicate columns remain available. */
+export type TableQueryFilterStep<PredicateT = ColumnarPredicate> = Readonly<{
+    /** Plan discriminator. */
+    kind: 'filter';
+    /** Predicate evaluated using three-valued Boolean semantics. */
+    predicate: PredicateT;
+}>;
+/** Narrows the result to requested output columns. */
+export type TableQueryProjectStep = Readonly<{
+    /** Plan discriminator. */
+    kind: 'project';
+    /** Output columns in caller-specified order. */
+    columns: readonly string[];
+}>;
+/** Retains the first rows in source order after filtering and projection. */
+export type TableQueryLimitStep = Readonly<{
+    /** Plan discriminator. */
+    kind: 'limit';
+    /** Maximum number of retained rows. */
+    limit: number;
+}>;
+/** One immutable operation in a normalized table-query plan. */
+export type TableQueryPlanStep<PredicateT = ColumnarPredicate> = TableQueryScanStep | TableQueryFilterStep<PredicateT> | TableQueryProjectStep | TableQueryLimitStep;
+/** Immutable logical query plan shared by CPU, SQL, and GPU backends. */
+export type TableQueryPlan<PredicateT = ColumnarPredicate> = readonly TableQueryPlanStep<PredicateT>[];
+/** Capability levels for an individual portable table-query operator. */
+export type TableQueryOperatorSupport = 'unsupported' | 'residual' | 'pushdown' | 'pushdown+residual';
+/** Optimization and correctness capabilities advertised by a table-query backend. */
+export type TableQueryCapabilities = Readonly<{
+    /** Whether output projection can avoid reading unrequested columns. */
+    projection: TableQueryOperatorSupport;
+    /** Whether predicates are unsupported, residual, pushed down, or both pushed and residual. */
+    predicate: TableQueryOperatorSupport;
+    /** Whether limits are unsupported, applied after execution, or stop physical work early. */
+    limit: TableQueryOperatorSupport;
+    /** Whether the backend can stream bounded result batches. */
+    streaming: boolean;
+    /** Whether active and queued physical work observes cancellation. */
+    cancellation: boolean;
+    /** Whether scalar expressions can be evaluated before projection. */
+    expressions?: TableQueryOperatorSupport;
+    /** Whether output rows can be ordered before the global limit. */
+    orderBy?: TableQueryOperatorSupport;
+    /** Whether grouped aggregate output is supported. */
+    aggregates?: TableQueryOperatorSupport;
+}>;
+/**
+ * Produces the canonical scan, filter, project, and limit sequence for a table query.
+ *
+ * Predicate columns are retained by the scan even if callers omit them from the output projection.
+ * This makes SQL `WHERE` semantics independent of a backend's internal API call order.
+ */
+export declare function planTableQuery<ValueT, PropertyT extends ColumnarPredicateProperty, PredicateT extends ColumnarPredicate<ValueT, PropertyT>>(sourceColumnNames: readonly string[], options?: TableQueryOptions<PredicateT>): TableQueryPlan<PredicateT>;
+/** Validates a portable table query against the columns exposed by one source. */
+export declare function validateTableQueryOptions<ValueT, PropertyT extends ColumnarPredicateProperty, PredicateT extends ColumnarPredicate<ValueT, PropertyT>>(sourceColumnNames: readonly string[], options: TableQueryOptions<PredicateT>): void;
+/** Validates a portable table-query limit independently of source-schema validation. */
+export declare function validateTableQueryLimit(limit: number | undefined): void;
+//# sourceMappingURL=table-query.d.ts.map

package/dist/loader-utils/lib/scan-utils/table-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-query.d.ts","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/table-query.ts"],"names":[],"mappings":"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"}

package/dist/loader-utils/lib/scan-utils/table-query.js

@@ -0,0 +1,56 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { getColumnarPredicateColumns, validateColumnarPredicate } from "./columnar-predicate.js";
+/**
+ * Produces the canonical scan, filter, project, and limit sequence for a table query.
+ *
+ * Predicate columns are retained by the scan even if callers omit them from the output projection.
+ * This makes SQL `WHERE` semantics independent of a backend's internal API call order.
+ */
+export function planTableQuery(sourceColumnNames, options = {}) {
+    validateTableQueryOptions(sourceColumnNames, options);
+    const outputColumnNames = options.columns ? [...options.columns] : [...sourceColumnNames];
+    const predicateColumnNames = options.predicate
+        ? getColumnarPredicateColumns(options.predicate)
+        : [];
+    const requiredColumnNames = new Set([...outputColumnNames, ...predicateColumnNames]);
+    const scanColumnNames = sourceColumnNames.filter(columnName => requiredColumnNames.has(columnName));
+    const steps = [
+        Object.freeze({ kind: 'scan', columns: Object.freeze(scanColumnNames) })
+    ];
+    if (options.predicate) {
+        steps.push(Object.freeze({ kind: 'filter', predicate: options.predicate }));
+    }
+    steps.push(Object.freeze({ kind: 'project', columns: Object.freeze(outputColumnNames) }));
+    if (options.limit !== undefined) {
+        steps.push(Object.freeze({ kind: 'limit', limit: options.limit }));
+    }
+    return Object.freeze(steps);
+}
+/** Validates a portable table query against the columns exposed by one source. */
+export function validateTableQueryOptions(sourceColumnNames, options) {
+    const availableColumnNames = new Set(sourceColumnNames);
+    const outputColumnNames = options.columns ?? sourceColumnNames;
+    const seenColumnNames = new Set();
+    for (const columnName of outputColumnNames) {
+        if (!availableColumnNames.has(columnName)) {
+            throw new Error(`Table query column not found: ${columnName}`);
+        }
+        if (seenColumnNames.has(columnName)) {
+            throw new Error(`Table query column was selected more than once: ${columnName}`);
+        }
+        seenColumnNames.add(columnName);
+    }
+    validateTableQueryLimit(options.limit);
+    if (options.predicate) {
+        validateColumnarPredicate(options.predicate, availableColumnNames);
+    }
+}
+/** Validates a portable table-query limit independently of source-schema validation. */
+export function validateTableQueryLimit(limit) {
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
+        throw new Error('Table query limit must be a non-negative safe integer.');
+    }
+}
+//# sourceMappingURL=table-query.js.map

package/dist/loader-utils/lib/scan-utils/table-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-query.js","sourceRoot":"","sources":["../../../../src/loader-utils/lib/scan-utils/table-query.ts"],"names":[],"mappings":"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"}