Update types in firestore.d.ts

types/firestore.d.ts

@@ -2035,23 +2035,26 @@ declare namespace FirebaseFirestore {
      * `vectorField` against the given `queryVector` and returns the top documents that are closest
      * to the `queryVector`.
      *
-     * Only documents whose `vectorField` field is a `VectorValue` of the same dimension as `queryVector`
+     * Only documents whose `vectorField` field is a {@link VectorValue} of the same dimension as `queryVector`
      * participate in the query, all other documents are ignored.
      *
      * @example
-     * ```typescript
+     * ```
      * // Returns the closest 10 documents whose Euclidean distance from their 'embedding' fields are closed to [41, 42].
      * const vectorQuery = col.findNearest('embedding', [41, 42], {limit: 10, distanceMeasure: 'EUCLIDEAN'});
      *
      * const querySnapshot = await aggregateQuery.get();
      * querySnapshot.forEach(...);
      * ```
      *
-     * @param vectorField The field path this vector query executes on.
-     * @param queryVector The vector value used to measure the distance from `vectorField` values in the documents.
-     * @param options Options control the vector query. `limit` specifies the upper bound of documents to return, must
-     * be a positive integer with a maximum value of 1000. `distanceMeasure` specifies what type of distance is
-     * calculated when performing the query.
+     * @param vectorField - A string or {@link FieldPath} specifying the vector field to search on.
+     * @param queryVector - The {@link VectorValue} used to measure the distance from `vectorField` values in the documents.
+     * @param options - Options control the vector query. `limit` specifies the upper bound of documents to return, must
+     * be a positive integer with a maximum value of 1000. `distanceMeasure` specifies what type of distance is calculated
+     * when performing the query.
+     *
+     * @deprecated Use the new {@link findNearest} implementation
+     * accepting a single `options` param.
      */
     findNearest(
       vectorField: string | FieldPath,
@@ -2062,6 +2065,31 @@ declare namespace FirebaseFirestore {
       }
     ): VectorQuery<AppModelType, DbModelType>;
 
+    /**
+     * Returns a query that can perform vector distance (similarity) search with given parameters.
+     *
+     * The returned query, when executed, performs a distance (similarity) search on the specified
+     * `vectorField` against the given `queryVector` and returns the top documents that are closest
+     * to the `queryVector`.
+     *
+     * Only documents whose `vectorField` field is a {@link VectorValue} of the same dimension as `queryVector`
+     * participate in the query, all other documents are ignored.
+     *
+     * @example
+     * ```
+     * // Returns the closest 10 documents whose Euclidean distance from their 'embedding' fields are closed to [41, 42].
+     * const vectorQuery = col.findNearest('embedding', [41, 42], 10, 'EUCLIDEAN', { distanceResultField: 'distance'});
+     *
+     * const querySnapshot = await aggregateQuery.get();
+     * querySnapshot.forEach(...);
+     * ```
+     * @param options - An argument specifying the behavior of the {@link VectorQuery} returned by this function.
+     * See {@link VectorQueryOptions}.
+     */
+    findNearest(
+      options: VectorQueryOptions
+    ): VectorQuery<AppModelType, DbModelType>;
+
     /**
      * Returns true if this `Query` is equal to the provided one.
      *
@@ -3192,6 +3220,50 @@ declare namespace FirebaseFirestore {
      */
     readonly snapshot: T | null;
   }
+
+  /**
+   * Specifies the behavior of the {@link VectorQuery} generated by a call to {@link Query.findNearest}.
+   */
+  export interface VectorQueryOptions {
+    /**
+     * A string or {@link FieldPath} specifying the vector field to search on.
+     */
+    vectorField: string | FieldPath;
+
+    /**
+     * The {@link VectorValue} used to measure the distance from `vectorField` values in the documents.
+     */
+    queryVector: VectorValue | Array<number>;
+
+    /**
+     * Specifies the upper bound of documents to return, must be a positive integer with a maximum value of 1000.
+     */
+    limit: number;
+
+    /**
+     * Specifies what type of distance is calculated when performing the query.
+     */
+    distanceMeasure: 'EUCLIDEAN' | 'COSINE' | 'DOT_PRODUCT';
+
+    /**
+     * Optionally specifies the name of a field that will be set on each returned DocumentSnapshot,
+     * which will contain the computed distance for the document.
+     */
+    distanceResultField?: string | FieldPath;
+
+    /**
+     * Specifies a threshold for which no less similar documents will be returned. The behavior
+     * of the specified `distanceMeasure` will affect the meaning of the distance threshold.
+     *
+     *  - For `distanceMeasure: "EUCLIDEAN"`, the meaning of `distanceThreshold` is:
+     *     SELECT docs WHERE euclidean_distance <= distanceThreshold
+     *  - For `distanceMeasure: "COSINE"`, the meaning of `distanceThreshold` is:
+     *     SELECT docs WHERE cosine_distance <= distanceThreshold
+     *  - For `distanceMeasure: "DOT_PRODUCT"`, the meaning of `distanceThreshold` is:
+     *     SELECT docs WHERE dot_product_distance >= distanceThreshold
+     */
+    distanceThreshold?: number;
+  }
 }
 
 declare module '@google-cloud/firestore' {