@milaboratories/pl-model-common 1.24.6 → 1.24.8

package/src/drivers/pframe/filter_spec.ts

@@ -0,0 +1,51 @@
+import type { SUniversalPColumnId } from "./spec/ids";
+
+export type FilterSpecNode<Leaf, CommonNode = {}, CommonLeaf = {}> =
+  | (CommonLeaf & Leaf)
+  | (CommonNode & { type: "not"; filter: FilterSpecNode<Leaf, CommonNode, CommonLeaf> })
+  | (CommonNode & { type: "or"; filters: FilterSpecNode<Leaf, CommonNode, CommonLeaf>[] })
+  | (CommonNode & { type: "and"; filters: FilterSpecNode<Leaf, CommonNode, CommonLeaf>[] });
+
+export type FilterSpecLeaf<T = SUniversalPColumnId> =
+  | { type: undefined }
+  | { type: "isNA"; column: T }
+  | { type: "isNotNA"; column: T }
+  | { type: "ifNa"; column: T; replacement: string }
+  | { type: "patternEquals"; column: T; value: string }
+  | { type: "patternNotEquals"; column: T; value: string }
+  | { type: "patternContainSubsequence"; column: T; value: string }
+  | { type: "patternNotContainSubsequence"; column: T; value: string }
+  | { type: "patternMatchesRegularExpression"; column: T; value: string }
+  | {
+      type: "patternFuzzyContainSubsequence";
+      column: T;
+      value: string;
+      maxEdits?: number;
+      substitutionsOnly?: boolean;
+      wildcard?: string;
+    }
+  | { type: "inSet"; column: T; value: string[] }
+  | { type: "notInSet"; column: T; value: string[] }
+  | { type: "topN"; column: T; n: number }
+  | { type: "bottomN"; column: T; n: number }
+  | { type: "equal"; column: T; x: number }
+  | { type: "notEqual"; column: T; x: number }
+  | { type: "lessThan"; column: T; x: number }
+  | { type: "greaterThan"; column: T; x: number }
+  | { type: "lessThanOrEqual"; column: T; x: number }
+  | { type: "greaterThanOrEqual"; column: T; x: number }
+  | { type: "equalToColumn"; column: T; rhs: T }
+  | { type: "lessThanColumn"; column: T; rhs: T; minDiff?: number }
+  | { type: "greaterThanColumn"; column: T; rhs: T; minDiff?: number }
+  | { type: "lessThanColumnOrEqual"; column: T; rhs: T; minDiff?: number }
+  | { type: "greaterThanColumnOrEqual"; column: T; rhs: T; minDiff?: number };
+
+export type FilterSpec<
+  Leaf extends FilterSpecLeaf<unknown> = FilterSpecLeaf<SUniversalPColumnId>,
+  CommonNode = {},
+  CommonLeaf = CommonNode,
+> = FilterSpecNode<Leaf, CommonNode, CommonLeaf>;
+
+export type FilterSpecType = Exclude<FilterSpec, { type: undefined }>["type"];
+
+export type FilterSpecOfType<T extends FilterSpecType> = Extract<FilterSpec, { type: T }>;

package/src/drivers/pframe/index.ts

@@ -1,5 +1,6 @@
 export * from "./column_filter";
 export * from "./data_info";
+export * from "./filter_spec";
 export * from "./data_types";
 export * from "./find_columns";
 export * from "./pframe";

package/src/drivers/pframe/query/index.ts

@@ -1,2 +1,3 @@
 export * from "./query_spec";
 export * from "./query_data";
+export * from "./utils";

package/src/drivers/pframe/query/query_common.ts

@@ -117,6 +117,54 @@ export type ExprConstant = {
   value: string | number | boolean;
 };
 
+/**
+ * Null check expression.
+ *
+ * Tests if an expression evaluates to null.
+ * **Input**: Any expression.
+ * **Output**: Boolean (true if input is null, false otherwise).
+ *
+ * @template I - The expression type (for recursion)
+ *
+ * @example
+ * // Check if column value is null
+ * { type: 'isNull', input: columnRef }
+ *
+ * // Combine with NOT to check for non-null
+ * { type: 'not', input: { type: 'isNull', input: columnRef } }
+ */
+export interface ExprIsNull<I> {
+  type: "isNull";
+  /** Input expression to check for null */
+  input: I;
+}
+
+/**
+ * Null coalescing expression.
+ *
+ * Returns the input value if it is not null, otherwise returns the replacement value.
+ * Equivalent to SQL's `IFNULL(input, replacement)` or `COALESCE(input, replacement)`.
+ * **Input**: Any expression.
+ * **Output**: Same type as input/replacement.
+ * **Null handling**: If input is null, returns replacement; otherwise returns input.
+ *
+ * @template I - The expression type (for recursion)
+ *
+ * @example
+ * // Replace null values with 0
+ * { type: 'ifNull', input: columnRef, replacement: { type: 'constant', value: 0 } }
+ *
+ * // Replace null strings with 'unknown'
+ * { type: 'ifNull', input: nameColumn, replacement: { type: 'constant', value: 'unknown' } }
+ */
+export interface ExprIfNull<I> {
+  type: "ifNull";
+  /** Value to check for null */
+  input: I;
+  /** Replacement value if input is null */
+  replacement: I;
+}
+
 // ============ Generic Expression Interfaces ============
 // I = expression type (recursive), S = selector type
 
@@ -479,6 +527,7 @@ export type InferBooleanExpressionUnion<E> = [
   E extends ExprStringContains<unknown> ? Extract<E, { type: "stringContains" }> : never,
   E extends ExprStringContainsFuzzy<unknown> ? Extract<E, { type: "stringContainsFuzzy" }> : never,
   E extends ExprStringRegex<unknown> ? Extract<E, { type: "stringRegex" }> : never,
+  E extends ExprIsNull<unknown> ? Extract<E, { type: "isNull" }> : never,
   E extends ExprLogicalUnary<unknown> ? Extract<E, { type: "not" }> : never,
   E extends ExprLogicalVariadic<unknown> ? Extract<E, { type: "and" | "or" }> : never,
   E extends ExprIsIn<unknown, string | number> ? Extract<E, { type: "isIn" }> : never,
@@ -702,12 +751,14 @@ export interface QueryFilter<Q, E> {
  *
  * @example
  * // Reference column by ID
- * { type: 'column', columnId: 'col_abc123' }
+ * { type: 'column', column: 'col_abc123' }
+ *
+ * @template C - Column reference type (e.g., PObjectId for spec, full PColumn for rich queries)
  */
-export interface QueryColumn {
+export interface QueryColumn<C = PObjectId> {
   type: "column";
-  /** Unique identifier of the column to reference */
-  columnId: PObjectId;
+  /** Column reference (ID or full column object depending on context) */
+  column: C;
 }
 
 /**
@@ -751,21 +802,22 @@ export interface QueryInlineColumn<T> {
  * - Expands it across specified axes indices
  * - Result has Cartesian product of original axes × new axes
  *
+ * @template C - Column reference type
  * @template SO - Spec override type
  *
  * @example
  * // Expand column across axes at indices 0 and 2
  * {
  *   type: 'sparseToDenseColumn',
- *   columnId: 'col_abc123',
+ *   column: 'col_abc123',
  *   axesIndices: [0, 2],
  *   specOverride: { ... } // optional spec modifications
  * }
  */
-export interface QuerySparseToDenseColumn<SO> {
+export interface QuerySparseToDenseColumn<C, SO> {
   type: "sparseToDenseColumn";
-  /** ID of the column to cross-join */
-  columnId: PObjectId;
+  /** Column reference (ID or full column object depending on context) */
+  column: C;
   /** Optional override for the column specification */
   specOverride?: SO;
   /** Indices of axes to expand across */

package/src/drivers/pframe/query/query_data.ts

@@ -3,8 +3,11 @@ import type {
   ExprAxisRef,
   ExprColumnRef,
   ExprNumericBinary,
+  ExprNumericComparison,
   ExprConstant,
   ExprIsIn,
+  ExprIsNull,
+  ExprIfNull,
   ExprLogicalUnary,
   ExprLogicalVariadic,
   ExprStringContains,
@@ -51,27 +54,27 @@ type ColumnIdAndTypeSpec = {
  * // - This entry's axis 1 maps to result axis 2
  * { entry: queryData, axesMapping: [0, 2] }
  */
-export interface QueryJoinEntryData extends QueryJoinEntry<QueryData> {
+export interface DataQueryJoinEntry extends QueryJoinEntry<DataQuery> {
   /** Maps this entry's axes to the result axes by index */
   axesMapping: number[];
 }
 
 /** @see QueryColumn */
-export type QueryColumnData = QueryColumn;
+export type DataQueryColumn = QueryColumn;
 /** @see QueryInlineColumn */
-export type QueryInlineColumnData = QueryInlineColumn<ColumnIdAndTypeSpec>;
+export type DataQueryInlineColumn = QueryInlineColumn<ColumnIdAndTypeSpec>;
 /** @see QuerySparseToDenseColumn */
-export type QuerySparseToDenseColumnData = QuerySparseToDenseColumn<ColumnIdAndTypeSpec>;
+export type DataQuerySparseToDenseColumn = QuerySparseToDenseColumn<PObjectId, ColumnIdAndTypeSpec>;
 /** @see QuerySymmetricJoin */
-export type QuerySymmetricJoinData = QuerySymmetricJoin<QueryJoinEntryData>;
+export type DataQuerySymmetricJoin = QuerySymmetricJoin<DataQueryJoinEntry>;
 /** @see QueryOuterJoin */
-export type QueryOuterJoinData = QueryOuterJoin<QueryJoinEntryData>;
+export type DataQueryOuterJoin = QueryOuterJoin<DataQueryJoinEntry>;
 /** @see QuerySliceAxes */
-export type QuerySliceAxesData = QuerySliceAxes<QueryData, QueryAxisSelector<number>>;
+export type DataQuerySliceAxes = QuerySliceAxes<DataQuery, QueryAxisSelector<number>>;
 /** @see QuerySort */
-export type QuerySortData = QuerySort<QueryData, QueryExpressionData>;
+export type DataQuerySort = QuerySort<DataQuery, DataQueryExpression>;
 /** @see QueryFilter */
-export type QueryFilterData = QueryFilter<QueryData, QueryBooleanExpressionData>;
+export type DataQueryFilter = QueryFilter<DataQuery, DataQueryBooleanExpression>;
 
 /**
  * Union of all data layer query types.
@@ -84,34 +87,37 @@ export type QueryFilterData = QueryFilter<QueryData, QueryBooleanExpressionData>
  * - Join operations: innerJoin, fullJoin, outerJoin
  * - Transformations: sliceAxes, sort, filter
  */
-export type QueryData =
-  | QueryColumnData
-  | QueryInlineColumnData
-  | QuerySparseToDenseColumnData
-  | QuerySymmetricJoinData
-  | QueryOuterJoinData
-  | QuerySliceAxesData
-  | QuerySortData
-  | QueryFilterData;
+export type DataQuery =
+  | DataQueryColumn
+  | DataQueryInlineColumn
+  | DataQuerySparseToDenseColumn
+  | DataQuerySymmetricJoin
+  | DataQueryOuterJoin
+  | DataQuerySliceAxes
+  | DataQuerySort
+  | DataQueryFilter;
 
 /** @see ExprAxisRef */
-export type ExprAxisRefData = ExprAxisRef<number>;
+export type DataExprAxisRef = ExprAxisRef<number>;
 /** @see ExprColumnRef */
-export type ExprColumnRefData = ExprColumnRef<number>;
+export type DataExprColumnRef = ExprColumnRef<number>;
 
-export type QueryExpressionData =
-  | ExprColumnRefData
-  | ExprAxisRefData
+export type DataQueryExpression =
+  | DataExprColumnRef
+  | DataExprAxisRef
   | ExprConstant
-  | ExprNumericBinary<QueryExpressionData>
-  | ExprNumericUnary<QueryExpressionData>
-  | ExprStringEquals<QueryExpressionData>
-  | ExprStringContains<QueryExpressionData>
-  | ExprStringRegex<QueryExpressionData>
-  | ExprStringContainsFuzzy<QueryExpressionData>
-  | ExprLogicalUnary<QueryExpressionData>
-  | ExprLogicalVariadic<QueryExpressionData>
-  | ExprIsIn<QueryExpressionData, string>
-  | ExprIsIn<QueryExpressionData, number>;
+  | ExprNumericBinary<DataQueryExpression>
+  | ExprNumericComparison<DataQueryExpression>
+  | ExprNumericUnary<DataQueryExpression>
+  | ExprStringEquals<DataQueryExpression>
+  | ExprStringContains<DataQueryExpression>
+  | ExprStringRegex<DataQueryExpression>
+  | ExprStringContainsFuzzy<DataQueryExpression>
+  | ExprIsNull<DataQueryExpression>
+  | ExprIfNull<DataQueryExpression>
+  | ExprLogicalUnary<DataQueryExpression>
+  | ExprLogicalVariadic<DataQueryExpression>
+  | ExprIsIn<DataQueryExpression, string>
+  | ExprIsIn<DataQueryExpression, number>;
 
-export type QueryBooleanExpressionData = InferBooleanExpressionUnion<QueryExpressionData>;
+export type DataQueryBooleanExpression = InferBooleanExpressionUnion<DataQueryExpression>;

package/src/drivers/pframe/query/query_spec.ts

@@ -3,8 +3,11 @@ import type {
   ExprAxisRef,
   ExprColumnRef,
   ExprNumericBinary,
+  ExprNumericComparison,
   ExprConstant,
   ExprIsIn,
+  ExprIsNull,
+  ExprIfNull,
   ExprLogicalUnary,
   ExprLogicalVariadic,
   ExprStringContains,
@@ -55,7 +58,7 @@ type ColumnIdAndSpec = {
  *   ]
  * }
  */
-export type QueryJoinEntrySpec = QueryJoinEntry<QuerySpec> & {
+export type SpecQueryJoinEntry<C = PObjectId> = QueryJoinEntry<SpecQuery<C>> & {
   /** Axis qualifications with additional domain constraints */
   qualifications: {
     /** Axis selector identifying which axis to qualify */
@@ -66,21 +69,27 @@ export type QueryJoinEntrySpec = QueryJoinEntry<QuerySpec> & {
 };
 
 /** @see QueryColumn */
-export type QueryColumnSpec = QueryColumn;
+export type SpecQueryColumn<C = PObjectId> = QueryColumn<C>;
 /** @see QueryInlineColumn */
-export type QueryInlineColumnSpec = QueryInlineColumn<ColumnIdAndSpec>;
+export type SpecQueryInlineColumn = QueryInlineColumn<ColumnIdAndSpec>;
 /** @see QuerySparseToDenseColumn */
-export type QuerySparseToDenseColumnSpec = QuerySparseToDenseColumn<PColumnIdAndSpec>;
+export type SpecQuerySparseToDenseColumn<C = PObjectId> = QuerySparseToDenseColumn<
+  C,
+  PColumnIdAndSpec
+>;
 /** @see QuerySymmetricJoin */
-export type QuerySymmetricJoinSpec = QuerySymmetricJoin<QueryJoinEntrySpec>;
+export type SpecQuerySymmetricJoin<C = PObjectId> = QuerySymmetricJoin<SpecQueryJoinEntry<C>>;
 /** @see QueryOuterJoin */
-export type QueryOuterJoinSpec = QueryOuterJoin<QueryJoinEntrySpec>;
+export type SpecQueryOuterJoin<C = PObjectId> = QueryOuterJoin<SpecQueryJoinEntry<C>>;
 /** @see QuerySliceAxes */
-export type QuerySliceAxesSpec = QuerySliceAxes<QuerySpec, QueryAxisSelector<SingleAxisSelector>>;
+export type SpecQuerySliceAxes<C = PObjectId> = QuerySliceAxes<
+  SpecQuery<C>,
+  QueryAxisSelector<SingleAxisSelector>
+>;
 /** @see QuerySort */
-export type QuerySortSpec = QuerySort<QuerySpec, QueryExpressionSpec>;
+export type SpecQuerySort<C = PObjectId> = QuerySort<SpecQuery<C>, SpecQueryExpression>;
 /** @see QueryFilter */
-export type QueryFilterSpec = QueryFilter<QuerySpec, QueryBooleanExpressionSpec>;
+export type SpecQueryFilter<C = PObjectId> = QueryFilter<SpecQuery<C>, SpecQueryBooleanExpression>;
 
 /**
  * Union of all spec layer query types.
@@ -88,39 +97,46 @@ export type QueryFilterSpec = QueryFilter<QuerySpec, QueryBooleanExpressionSpec>
  * The spec layer operates with named selectors and column IDs,
  * making it suitable for user-facing query construction and validation.
  *
+ * @template C - Column reference type. Defaults to PObjectId (ID-only).
+ *   Can be parameterized with richer types (e.g., PColumn<Data>) to carry
+ *   full column data directly in the query tree.
+ *
  * Includes:
  * - Leaf nodes: column, inlineColumn, sparseToDenseColumn
  * - Join operations: innerJoin, fullJoin, outerJoin
  * - Transformations: sliceAxes, sort, filter
  */
-export type QuerySpec =
-  | QueryColumnSpec
-  | QueryInlineColumnSpec
-  | QuerySparseToDenseColumnSpec
-  | QuerySymmetricJoinSpec
-  | QueryOuterJoinSpec
-  | QuerySliceAxesSpec
-  | QuerySortSpec
-  | QueryFilterSpec;
+export type SpecQuery<C = PObjectId> =
+  | SpecQueryColumn<C>
+  | SpecQueryInlineColumn
+  | SpecQuerySparseToDenseColumn<C>
+  | SpecQuerySymmetricJoin<C>
+  | SpecQueryOuterJoin<C>
+  | SpecQuerySliceAxes<C>
+  | SpecQuerySort<C>
+  | SpecQueryFilter<C>;
 
 /** @see ExprAxisRef */
-export type ExprAxisRefSpec = ExprAxisRef<SingleAxisSelector>;
+export type SpecExprAxisRef = ExprAxisRef<SingleAxisSelector>;
 /** @see ExprColumnRef */
-export type ExprColumnRefSpec = ExprColumnRef<PObjectId>;
+export type SpecExprColumnRef = ExprColumnRef<PObjectId>;
 
-export type QueryExpressionSpec =
-  | ExprColumnRefSpec
-  | ExprAxisRefSpec
+export type SpecQueryExpression =
+  | SpecExprColumnRef
+  | SpecExprAxisRef
   | ExprConstant
-  | ExprNumericBinary<QueryExpressionSpec>
-  | ExprNumericUnary<QueryExpressionSpec>
-  | ExprStringEquals<QueryExpressionSpec>
-  | ExprStringContains<QueryExpressionSpec>
-  | ExprStringRegex<QueryExpressionSpec>
-  | ExprStringContainsFuzzy<QueryExpressionSpec>
-  | ExprLogicalUnary<QueryExpressionSpec>
-  | ExprLogicalVariadic<QueryExpressionSpec>
-  | ExprIsIn<QueryExpressionSpec, string>
-  | ExprIsIn<QueryExpressionSpec, number>;
+  | ExprNumericBinary<SpecQueryExpression>
+  | ExprNumericComparison<SpecQueryExpression>
+  | ExprNumericUnary<SpecQueryExpression>
+  | ExprStringEquals<SpecQueryExpression>
+  | ExprStringContains<SpecQueryExpression>
+  | ExprStringRegex<SpecQueryExpression>
+  | ExprStringContainsFuzzy<SpecQueryExpression>
+  | ExprIsNull<SpecQueryExpression>
+  | ExprIfNull<SpecQueryExpression>
+  | ExprLogicalUnary<SpecQueryExpression>
+  | ExprLogicalVariadic<SpecQueryExpression>
+  | ExprIsIn<SpecQueryExpression, string>
+  | ExprIsIn<SpecQueryExpression, number>;
 
-export type QueryBooleanExpressionSpec = InferBooleanExpressionUnion<QueryExpressionSpec>;
+export type SpecQueryBooleanExpression = InferBooleanExpressionUnion<SpecQueryExpression>;

package/src/drivers/pframe/query/utils.ts

@@ -0,0 +1,205 @@
+import { canonicalizeJson } from "../../../json";
+import { assertNever } from "../../../util";
+import type {
+  SpecQueryBooleanExpression,
+  SpecQueryExpression,
+  SpecQuery,
+  SpecQueryJoinEntry,
+} from "./query_spec";
+
+const booleanTypesSet = new Set<SpecQueryBooleanExpression["type"]>([
+  "numericComparison",
+  "stringEquals",
+  "stringContains",
+  "stringContainsFuzzy",
+  "stringRegex",
+  "isNull",
+  "not",
+  "and",
+  "or",
+  "isIn",
+]);
+
+export function isBooleanExpression(expr: SpecQueryExpression): expr is SpecQueryBooleanExpression {
+  return booleanTypesSet.has(
+    // @ts-expect-error -- TypeScript doesn't understand the discriminated union here, but we do at runtime
+    expr.type,
+  );
+}
+
+/** Collects all column references from a SpecQuery tree. */
+export function collectQueryColumns<C>(query: SpecQuery<C>): C[] {
+  const result: C[] = [];
+  collectQueryColumnsImpl(query, result);
+  return result;
+}
+
+function collectQueryColumnsImpl<C>(query: SpecQuery<C>, result: C[]): void {
+  switch (query.type) {
+    case "column":
+      result.push(query.column);
+      break;
+    case "sparseToDenseColumn":
+      result.push(query.column);
+      break;
+    case "inlineColumn":
+      break;
+    case "innerJoin":
+    case "fullJoin":
+      for (const e of query.entries) collectQueryColumnsImpl(e.entry, result);
+      break;
+    case "outerJoin":
+      collectQueryColumnsImpl(query.primary.entry, result);
+      for (const e of query.secondary) collectQueryColumnsImpl(e.entry, result);
+      break;
+    case "filter":
+    case "sort":
+    case "sliceAxes":
+      collectQueryColumnsImpl(query.input, result);
+      break;
+    default:
+      assertNever(query);
+  }
+}
+
+export function sortQuerySpec(query: SpecQuery): SpecQuery {
+  switch (query.type) {
+    case "column":
+    case "inlineColumn":
+      return query;
+    case "sparseToDenseColumn": {
+      const sortedAxesIndices = query.axesIndices.toSorted((lhs, rhs) => lhs - rhs);
+      return {
+        ...query,
+        axesIndices: sortedAxesIndices,
+      };
+    }
+    case "innerJoin":
+    case "fullJoin": {
+      const sortedEntries = query.entries.map(sortQueryJoinEntrySpec);
+      sortedEntries.sort(cmpQueryJoinEntrySpec);
+      return {
+        ...query,
+        entries: sortedEntries,
+      };
+    }
+    case "outerJoin": {
+      const sortedSecondary = query.secondary.map(sortQueryJoinEntrySpec);
+      sortedSecondary.sort(cmpQueryJoinEntrySpec);
+      return {
+        ...query,
+        primary: sortQueryJoinEntrySpec(query.primary),
+        secondary: sortedSecondary,
+      };
+    }
+    case "sliceAxes": {
+      const sortedAxisFilters = query.axisFilters.toSorted((lhs, rhs) => {
+        const lhsKey = canonicalizeJson(lhs.axisSelector);
+        const rhsKey = canonicalizeJson(rhs.axisSelector);
+        return lhsKey < rhsKey ? -1 : lhsKey === rhsKey ? 0 : 1;
+      });
+      return {
+        ...query,
+        input: sortQuerySpec(query.input),
+        axisFilters: sortedAxisFilters,
+      };
+    }
+    case "sort":
+      return {
+        ...query,
+        input: sortQuerySpec(query.input),
+      };
+    case "filter":
+      return {
+        ...query,
+        input: sortQuerySpec(query.input),
+      };
+    default:
+      assertNever(query);
+  }
+}
+
+function sortQueryJoinEntrySpec(entry: SpecQueryJoinEntry): SpecQueryJoinEntry {
+  const sortedQualifications = entry.qualifications.toSorted((lhs, rhs) => {
+    const lhsKey = canonicalizeJson(lhs.axis);
+    const rhsKey = canonicalizeJson(rhs.axis);
+    return lhsKey < rhsKey ? -1 : lhsKey === rhsKey ? 0 : 1;
+  });
+  return {
+    entry: sortQuerySpec(entry.entry),
+    qualifications: sortedQualifications,
+  };
+}
+
+function cmpQuerySpec(lhs: SpecQuery, rhs: SpecQuery): number {
+  if (lhs.type !== rhs.type) {
+    return lhs.type < rhs.type ? -1 : 1;
+  }
+  switch (lhs.type) {
+    case "column":
+      return lhs.column < (rhs as typeof lhs).column
+        ? -1
+        : lhs.column === (rhs as typeof lhs).column
+          ? 0
+          : 1;
+    case "inlineColumn":
+      return lhs.spec.id < (rhs as typeof lhs).spec.id
+        ? -1
+        : lhs.spec.id === (rhs as typeof lhs).spec.id
+          ? 0
+          : 1;
+    case "sparseToDenseColumn":
+      return lhs.column < (rhs as typeof lhs).column
+        ? -1
+        : lhs.column === (rhs as typeof lhs).column
+          ? 0
+          : 1;
+    case "innerJoin":
+    case "fullJoin": {
+      const rhsJoin = rhs as typeof lhs;
+      if (lhs.entries.length !== rhsJoin.entries.length) {
+        return lhs.entries.length - rhsJoin.entries.length;
+      }
+      for (let i = 0; i < lhs.entries.length; i++) {
+        const cmp = cmpQueryJoinEntrySpec(lhs.entries[i], rhsJoin.entries[i]);
+        if (cmp !== 0) return cmp;
+      }
+      return 0;
+    }
+    case "outerJoin": {
+      const rhsOuter = rhs as typeof lhs;
+      const cmp = cmpQueryJoinEntrySpec(lhs.primary, rhsOuter.primary);
+      if (cmp !== 0) return cmp;
+      if (lhs.secondary.length !== rhsOuter.secondary.length) {
+        return lhs.secondary.length - rhsOuter.secondary.length;
+      }
+      for (let i = 0; i < lhs.secondary.length; i++) {
+        const cmp = cmpQueryJoinEntrySpec(lhs.secondary[i], rhsOuter.secondary[i]);
+        if (cmp !== 0) return cmp;
+      }
+      return 0;
+    }
+    case "sliceAxes":
+      return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
+    case "sort":
+      return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
+    case "filter":
+      return cmpQuerySpec(lhs.input, (rhs as typeof lhs).input);
+    default:
+      assertNever(lhs);
+  }
+}
+
+function cmpQueryJoinEntrySpec(lhs: SpecQueryJoinEntry, rhs: SpecQueryJoinEntry): number {
+  const cmp = cmpQuerySpec(lhs.entry, rhs.entry);
+  if (cmp !== 0) return cmp;
+  if (lhs.qualifications.length !== rhs.qualifications.length) {
+    return lhs.qualifications.length - rhs.qualifications.length;
+  }
+  for (let i = 0; i < lhs.qualifications.length; i++) {
+    const lhsQ = canonicalizeJson(lhs.qualifications[i]);
+    const rhsQ = canonicalizeJson(rhs.qualifications[i]);
+    if (lhsQ !== rhsQ) return lhsQ < rhsQ ? -1 : 1;
+  }
+  return 0;
+}