@milaboratories/pl-model-common 1.24.1 → 1.24.2

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

@@ -0,0 +1,110 @@
+import type { PObjectId } from '../../../pool';
+import type {
+  ExprAxisRef,
+  ExprColumnRef,
+  ExprNumericBinary,
+  ExprConstant,
+  ExprIsIn,
+  ExprLogicalUnary,
+  ExprLogicalVariadic,
+  ExprStringContains,
+  ExprStringContainsFuzzy,
+  ExprStringEquals,
+  ExprStringRegex,
+  ExprNumericUnary,
+  QueryAxisSelector,
+  QueryColumn, QuerySparseToDenseColumn,
+  QueryFilter,
+  QueryInlineColumn,
+  QueryJoinEntry,
+  QueryOuterJoin,
+  QuerySliceAxes,
+  QuerySort,
+  QuerySymmetricJoin,
+  TypeSpec,
+  InferBooleanExpressionUnion,
+} from './query_common';
+
+/**
+ * Column identifier with type specification.
+ *
+ * Pairs a column ID with its full type specification (axes and column types).
+ * Used in data layer to carry type information alongside column references.
+ */
+type ColumnIdAndTypeSpec = {
+  /** Unique identifier of the column */
+  id: PObjectId;
+  /** Type specification defining axes and column types */
+  typeSpec: TypeSpec;
+};
+
+/**
+ * Join entry for data layer queries.
+ *
+ * Extends the base join entry with axes mapping information.
+ * The mapping specifies how axes from this entry align with the joined result.
+ *
+ * @example
+ * // Join entry with axes mapping [0, 2] means:
+ * // - This entry's axis 0 maps to result axis 0
+ * // - This entry's axis 1 maps to result axis 2
+ * { entry: queryData, axesMapping: [0, 2] }
+ */
+export interface QueryJoinEntryData extends QueryJoinEntry<QueryData> {
+  /** Maps this entry's axes to the result axes by index */
+  axesMapping: number[];
+}
+
+/** @see QueryColumn */
+export type QueryColumnData = QueryColumn;
+/** @see QueryInlineColumn */
+export type QueryInlineColumnData = QueryInlineColumn<ColumnIdAndTypeSpec>;
+/** @see QuerySparseToDenseColumn */
+export type QuerySparseToDenseColumnData = QuerySparseToDenseColumn<ColumnIdAndTypeSpec>;
+/** @see QuerySymmetricJoin */
+export type QuerySymmetricJoinData = QuerySymmetricJoin<QueryJoinEntryData>;
+/** @see QueryOuterJoin */
+export type QueryOuterJoinData = QueryOuterJoin<QueryJoinEntryData>;
+/** @see QuerySliceAxes */
+export type QuerySliceAxesData = QuerySliceAxes<QueryData, QueryAxisSelector<number>>;
+/** @see QuerySort */
+export type QuerySortData = QuerySort<QueryData, QueryExpressionData>;
+/** @see QueryFilter */
+export type QueryFilterData = QueryFilter<QueryData, QueryBooleanExpressionData>;
+
+/**
+ * Union of all data layer query types.
+ *
+ * The data layer operates with numeric indices for axes and columns,
+ * making it suitable for runtime query execution and optimization.
+ *
+ * Includes:
+ * - Leaf nodes: column, inlineColumn, sparseToDenseColumn
+ * - Join operations: innerJoin, fullJoin, outerJoin
+ * - Transformations: sliceAxes, sort, filter
+ */
+export type QueryData =
+  | QueryColumnData
+  | QueryInlineColumnData
+  | QuerySparseToDenseColumnData
+  | QuerySymmetricJoinData
+  | QueryOuterJoinData
+  | QuerySliceAxesData
+  | QuerySortData
+  | QueryFilterData;
+
+/** @see ExprAxisRef */
+export type ExprAxisRefData = ExprAxisRef<number>;
+/** @see ExprColumnRef */
+export type ExprColumnRefData = ExprColumnRef<number>;
+
+export type QueryExpressionData =
+  | ExprColumnRefData | ExprAxisRefData | ExprConstant
+  | ExprNumericBinary<QueryExpressionData> | ExprNumericUnary<QueryExpressionData>
+  | ExprStringEquals<QueryExpressionData> | ExprStringContains<QueryExpressionData>
+  | ExprStringRegex<QueryExpressionData> | ExprStringContainsFuzzy<QueryExpressionData>
+  | ExprLogicalUnary<QueryExpressionData> | ExprLogicalVariadic<QueryExpressionData>
+  | ExprIsIn<QueryExpressionData, string> | ExprIsIn<QueryExpressionData, number>
+  ;
+
+export type QueryBooleanExpressionData = InferBooleanExpressionUnion<QueryExpressionData>;

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

@@ -0,0 +1,118 @@
+import type { PObjectId } from '../../../pool';
+import type {
+  ExprAxisRef,
+  ExprColumnRef,
+  ExprNumericBinary,
+  ExprConstant,
+  ExprIsIn,
+  ExprLogicalUnary,
+  ExprLogicalVariadic,
+  ExprStringContains,
+  ExprStringContainsFuzzy,
+  ExprStringEquals,
+  ExprStringRegex,
+  ExprNumericUnary,
+  QueryAxisSelector,
+  QueryColumn, QuerySparseToDenseColumn,
+  QueryFilter,
+  QueryInlineColumn,
+  QueryJoinEntry,
+  QueryOuterJoin,
+  QuerySliceAxes,
+  QuerySort,
+  QuerySymmetricJoin,
+  InferBooleanExpressionUnion,
+} from './query_common';
+import type { Domain, PColumnIdAndSpec, PColumnSpec, SingleAxisSelector } from '../spec';
+
+/**
+ * Column identifier with specification.
+ *
+ * Pairs a column ID with its full PColumnSpec.
+ * Used in spec layer to carry column specification alongside references.
+ */
+type ColumnIdAndSpec = {
+  /** Unique identifier of the column */
+  id: PObjectId;
+  /** Full column specification including axes and value type */
+  spec: PColumnSpec;
+};
+
+/**
+ * Join entry for spec layer queries.
+ *
+ * Extends the base join entry with axis qualifications.
+ * Qualifications specify additional domain constraints for each axis,
+ * enabling more precise control over how columns are joined.
+ *
+ * @example
+ * // Join entry with axis qualifications
+ * {
+ *   entry: querySpec,
+ *   qualifications: [
+ *     { axis: { name: 'sample' }, additionalDomains: { ... } }
+ *   ]
+ * }
+ */
+export type QueryJoinEntrySpec = QueryJoinEntry<QuerySpec> & {
+  /** Axis qualifications with additional domain constraints */
+  qualifications: {
+    /** Axis selector identifying which axis to qualify */
+    axis: SingleAxisSelector;
+    /** Additional domain constraints for this axis */
+    additionalDomains: Domain;
+  }[];
+};
+
+/** @see QueryColumn */
+export type QueryColumnSpec = QueryColumn;
+/** @see QueryInlineColumn */
+export type QueryInlineColumnSpec = QueryInlineColumn<ColumnIdAndSpec>;
+/** @see QuerySparseToDenseColumn */
+export type QuerySparseToDenseColumnSpec = QuerySparseToDenseColumn<PColumnIdAndSpec>;
+/** @see QuerySymmetricJoin */
+export type QuerySymmetricJoinSpec = QuerySymmetricJoin<QueryJoinEntrySpec>;
+/** @see QueryOuterJoin */
+export type QueryOuterJoinSpec = QueryOuterJoin<QueryJoinEntrySpec>;
+/** @see QuerySliceAxes */
+export type QuerySliceAxesSpec = QuerySliceAxes<QuerySpec, QueryAxisSelector<SingleAxisSelector>>;
+/** @see QuerySort */
+export type QuerySortSpec = QuerySort<QuerySpec, QueryExpressionSpec>;
+/** @see QueryFilter */
+export type QueryFilterSpec = QueryFilter<QuerySpec, QueryBooleanExpressionSpec>;
+
+/**
+ * Union of all spec layer query types.
+ *
+ * The spec layer operates with named selectors and column IDs,
+ * making it suitable for user-facing query construction and validation.
+ *
+ * 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;
+
+/** @see ExprAxisRef */
+export type ExprAxisRefSpec = ExprAxisRef<SingleAxisSelector>;
+/** @see ExprColumnRef */
+export type ExprColumnRefSpec = ExprColumnRef<PObjectId>;
+
+export type QueryExpressionSpec =
+  | ExprColumnRefSpec | ExprAxisRefSpec | ExprConstant
+  | ExprNumericBinary<QueryExpressionSpec> | ExprNumericUnary<QueryExpressionSpec>
+  | ExprStringEquals<QueryExpressionSpec> | ExprStringContains<QueryExpressionSpec>
+  | ExprStringRegex<QueryExpressionSpec> | ExprStringContainsFuzzy<QueryExpressionSpec>
+  | ExprLogicalUnary<QueryExpressionSpec> | ExprLogicalVariadic<QueryExpressionSpec>
+  | ExprIsIn<QueryExpressionSpec, string> | ExprIsIn<QueryExpressionSpec, number>;
+
+export type QueryBooleanExpressionSpec = InferBooleanExpressionUnion<QueryExpressionSpec>;

package/src/drivers/pframe/spec/selectors.ts

@@ -1,5 +1,5 @@
 import { isPColumnSpec, type PObjectSpec } from '../../../pool';
-import type { AxisId, PColumnSpec, ValueType } from './spec';
+import type { AxisId, AxisValueType, Domain, PColumnSpec, ValueType } from './spec';
 import { getAxisId } from './spec';
 
 /**
@@ -37,6 +37,18 @@ export interface AxisSelector {
   domain?: Record<string, string>;
 }
 
+/** Single axis selector */
+export interface SingleAxisSelector {
+  /** Axis name (required) */
+  name: string;
+  /** Axis type (optional) */
+  type?: AxisValueType;
+  /** Domain requirements (optional) */
+  domain?: Domain;
+  /** Parent axes requirements (optional) */
+  parentAxes?: SingleAxisSelector[];
+}
+
 /**
  * Reference to an axis by its numerical index within the anchor column's axes array
  * Format: [anchorId, axisIndex]

package/src/drivers/pframe/spec/spec.ts

@@ -20,6 +20,9 @@ export const ValueType = {
   Bytes: 'Bytes',
 } as const;
 
+export type AxisValueType = Extract<ValueType, 'Int' | 'Long' | 'String'>;
+export type ColumnValueType = ValueType;
+
 /** PFrame columns and axes within them may store one of these types. */
 export type ValueType = (typeof ValueType)[keyof typeof ValueType];