@dxos/echo-pipeline 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/query/plan.ts

@@ -3,8 +3,8 @@
 //
 
 import type { QueryAST } from '@dxos/echo-protocol';
-import type { EscapedPropPath } from '@dxos/indexing';
-import type { DXN, ObjectId, SpaceId } from '@dxos/keys';
+import type { EscapedPropPath } from '@dxos/index-core';
+import type { DXN, ObjectId } from '@dxos/keys';
 
 export namespace QueryPlan {
   export type TextSearchKind = 'full-text' | 'vector' | 'hybrid';
@@ -32,7 +32,9 @@ export namespace QueryPlan {
     | FilterDeletedStep
     | TraverseStep
     | UnionStep
-    | SetDifferenceStep;
+    | SetDifferenceStep
+    | OrderStep
+    | LimitStep;
 
   /**
    * Clear the current working set.
@@ -43,20 +45,34 @@ export namespace QueryPlan {
 
   /**
    * Select objects based on id, typename, or other predicates.
-   * Specifies the spaces to select from.
+   * Specifies the spaces and/or queues to select from.
+   * The results from spaces and queues are unioned together.
    */
   export type SelectStep = {
     _tag: 'SelectStep';
 
-    spaces: readonly SpaceId[];
+    /**
+     * What to select from the scope.
+     */
     selector: Selector;
+
+    /**
+     * Where to select from.
+     */
+    scope: QueryAST.Scope;
+
+    /**
+     * Optional limit on the number of results to select.
+     * When set, the index scan can be optimized to stop early.
+     */
+    limit?: number;
   };
 
   /**
    * Specifier to scan the database for objects.
    * Optimized to utilize database indexes.
    */
-  export type Selector = WildcardSelector | IdSelector | TypeSelector | TextSelector;
+  export type Selector = WildcardSelector | IdSelector | TypeSelector | TextSelector | TimestampSelector;
 
   export type WildcardSelector = {
     _tag: 'WildcardSelector';
@@ -90,6 +106,24 @@ export namespace QueryPlan {
 
     text: string;
     searchKind: TextSearchKind;
+
+    /**
+     * Optionally select only objects of the given typenames.
+     */
+    typename: DXN.String[] | null;
+  };
+
+  /**
+   * Select objects by timestamp range (createdAt / updatedAt).
+   * Uses the ObjectMetaIndex timestamp columns.
+   */
+  export type TimestampSelector = {
+    _tag: 'TimestampSelector';
+
+    updatedAfter?: number;
+    updatedBefore?: number;
+    createdAfter?: number;
+    createdBefore?: number;
   };
 
   /**
@@ -140,7 +174,7 @@ export namespace QueryPlan {
   /**
    * Describes a traversal of the object graph.
    */
-  export type Traversal = ReferenceTraversal | RelationTraversal;
+  export type Traversal = ReferenceTraversal | RelationTraversal | HierarchyTraversal;
 
   /**
    * Traverse a reference connection.
@@ -150,8 +184,9 @@ export namespace QueryPlan {
 
     /**
      * Property path where the reference is located.
+     * If null, matches references from any property (only valid for incoming direction).
      */
-    property: EscapedPropPath;
+    property: EscapedPropPath | null;
 
     /**
      * outgoing: the reference points from the anchor object to the target.
@@ -173,6 +208,19 @@ export namespace QueryPlan {
     direction: 'source-to-relation' | 'relation-to-source' | 'target-to-relation' | 'relation-to-target';
   };
 
+  /**
+   * Traverse parent-child hierarchy.
+   */
+  export type HierarchyTraversal = {
+    _tag: 'HierarchyTraversal';
+
+    /**
+     * to-parent: traverse from child to parent.
+     * to-children: traverse from parent to children.
+     */
+    direction: 'to-parent' | 'to-children';
+  };
+
   /**
    * Combine results from multiple plans.
    * Each of the plans starts with a copy of the current working set.
@@ -193,4 +241,30 @@ export namespace QueryPlan {
     source: Plan;
     exclude: Plan;
   };
+
+  /**
+   * Order the results of the plan.
+   */
+  export type OrderStep = {
+    _tag: 'OrderStep';
+
+    // Defaults to natural order if empty.
+    order: readonly QueryAST.Order[];
+
+    /**
+     * Optional limit on the number of results to return after ordering.
+     * When set, the sorting can be optimized to only track the top N elements.
+     */
+    // TODO(dmaretskyi): Remove. This doesn't belong here.
+    limit?: number;
+  };
+
+  /**
+   * Limit the number of results.
+   */
+  export type LimitStep = {
+    _tag: 'LimitStep';
+
+    limit: number;
+  };
 }