WIP: query profiling

dev/src/reference.ts

@@ -2204,6 +2204,48 @@ export class Query<T = firestore.DocumentData> implements firestore.Query<T> {
     return this._get();
   }
 
+  /**
+   * Performs the planning stage of this query, without actually executing the
+   * query. Returns a Promise that will be resolved with the result of the
+   * query planning information.
+   *
+   * Note: the information included in the output of this function is subject
+   * to change.
+   *
+   * @return A Promise that will be resolved with the results of the query
+   * planning information.
+   */
+  plan(): Promise<Record<string, unknown>> {
+    return Promise.resolve({foo: 'bar'});
+  }
+
+  /**
+   * Plans and executes this query. Returns a Promise that will be resolved
+   * with the planning information, statistics from the query execution, and
+   * the query results.
+   *
+   * Note: the information included in the output of this function is subject
+   * to change.
+   *
+   * @return A Promise that will be resolved with the planning information,
+   * statistics from the query execution, and the query results.
+   */
+  profile(): Promise<firestore.QueryProfileInfo<QuerySnapshot<T>>> {
+    const mock = {
+      plan: {foo: 'bar'},
+      stats: {cpu: '3ms'},
+      snapshot: new QuerySnapshot(
+        this,
+        new Timestamp(0, 0),
+        0,
+        () => [],
+        () => []
+      ),
+    };
+
+    return Promise.resolve(mock);
+  }
+
   /**
    * Internal get() method that accepts an optional transaction id.
    *
@@ -3277,6 +3319,23 @@ export class AggregateQuery<T extends firestore.AggregateSpec>
     }
     return deepEqual(this._aggregates, other._aggregates);
   }
+
+  plan(): Promise<Record<string, unknown>> {
+    return Promise.resolve({foo: 'bar'});
+  }
+
+  profile(): Promise<firestore.QueryProfileInfo<AggregateQuerySnapshot<T>>> {
+    const mock = {
+      plan: {foo: 'bar'},
+      stats: {cpu: '3ms'},
+      snapshot: new AggregateQuerySnapshot(
+        this,
+        new Timestamp(0, 0),
+        this.decodeResult({})
+      ),
+    };
+    return Promise.resolve(mock);
+  }
 }
 
 /**

dev/system-test/firestore.ts

@@ -127,16 +127,40 @@
       });
   });
 
+  it.only('can plan a query', async () => {
+    const plan = await randomCol.where('a', '>', 10).plan();
+    console.log(plan);
+  });
+
+  it.only('can profile a query', async () => {
+    const profile = await randomCol.where('a', '>', 10).profile();
+    console.log(profile.plan);
+    console.log(profile.stats);
+    console.log(profile.snapshot.size);
+  });
+
+  it.only('can plan an aggregate query', async () => {
+    const plan = await randomCol.where('a', '>', 10).count().plan();
+    console.log(plan);
+  });
+
+  it.only('can profile an aggregate query', async () => {
+    const profile = await randomCol.where('a', '>', 10).count().profile();
+    console.log(profile.plan);
+    console.log(profile.stats);
+    console.log(profile.snapshot.data());
+  });
+
   it('getAll() supports array destructuring', () => {
     const ref1 = randomCol.doc('doc1');
     const ref2 = randomCol.doc('doc2');
     return Promise.all([ref1.set({foo: 'a'}), ref2.set({foo: 'a'})])
       .then(() => {
         return firestore.getAll(...[ref1, ref2]);
       })
       .then(docs => {
         expect(docs.length).to.equal(2);
       });
   });
 
   it('getAll() supports field mask', () => {

types/firestore.d.ts

@@ -1702,6 +1702,32 @@ declare namespace FirebaseFirestore {
      */
     get(): Promise<QuerySnapshot<T>>;
 
+    /**
+     * Performs the planning stage of this query, without actually executing the
+     * query. Returns a Promise that will be resolved with the result of the
+     * query planning information.
+     *
+     * Note: the information included in the output of this function is subject
+     * to change.
+     *
+     * @return A Promise that will be resolved with the results of the query
+     * planning information.
+     */
+    plan(): Promise<Record<string, unknown>>;
+
+    /**
+     * Plans and executes this query. Returns a Promise that will be resolved
+     * with the planning information, statistics from the query execution, and
+     * the query results.
+     *
+     * Note: the information included in the output of this function is subject
+     * to change.
+     *
+     * @return A Promise that will be resolved with the planning information,
+     * statistics from the query execution, and the query results.
+     */
+    profile(): Promise<QueryProfileInfo<QuerySnapshot<T>>>;
+
     /*
      * Executes the query and returns the results as Node Stream.
      *
@@ -2108,6 +2134,32 @@ declare namespace FirebaseFirestore {
      */
     get(): Promise<AggregateQuerySnapshot<T>>;
 
+    /**
+     * Performs the planning stage of this query, without actually executing the
+     * query. Returns a Promise that will be resolved with the result of the
+     * query planning information.
+     *
+     * Note: the information included in the output of this function is subject
+     * to change.
+     *
+     * @return A Promise that will be resolved with the results of the query
+     * planning information.
+     */
+    plan(): Promise<Record<string, unknown>>;
+
+    /**
+     * Plans and executes this query. Returns a Promise that will be resolved
+     * with the planning information, statistics from the query execution, and
+     * the query results.
+     *
+     * Note: the information included in the output of this function is subject
+     * to change.
+     *
+     * @return A Promise that will be resolved with the planning information,
+     * statistics from the query execution, and the query results.
+     */
+    profile(): Promise<QueryProfileInfo<AggregateQuerySnapshot<T>>>;
+
     /**
      * Compares this object with the given object for equality.
      *
@@ -2539,6 +2591,26 @@ declare namespace FirebaseFirestore {
      */
     static and(...filters: Filter[]): Filter;
   }
+
+  /** A QueryProfileInfo contains information about planning, execution, and results of a query. */
+  export interface QueryProfileInfo<T> {
+    /**
+     * A Map that contains information about the query plan.
+     * Contents are subject to change.
+     */
+    readonly plan: Record<string, unknown>;
+
+    /**
+     * A Map that contains statistics about the execution of the query.
+     * Contents are subject to change.
+     */
+    readonly stats: Record<string, unknown>;
+
+    /**
+     * The snapshot that contains the results of executing the query.
+     */
+    readonly snapshot: T;
+  }
 }
 
 declare module '@google-cloud/firestore' {