@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/search/types.ts

@@ -0,0 +1,1029 @@
+export const FIELD_TYPES = [
+  "TEXT",
+  "U64",
+  "I64",
+  "F64",
+  "BOOL",
+  "DATE",
+  "KEYWORD",
+  "FACET",
+  "HYBRID",
+] as const;
+export type FieldType = (typeof FIELD_TYPES)[number];
+
+export type TextField = {
+  type: "TEXT";
+  noTokenize?: boolean;
+  noStem?: boolean;
+  from?: string;
+};
+
+export type NumericField = {
+  type: "U64" | "I64" | "F64";
+  fast: true;
+  from?: string;
+};
+
+export type BoolField = {
+  type: "BOOL";
+  fast?: boolean;
+  from?: string;
+};
+
+export type DateField = {
+  type: "DATE";
+  fast?: boolean;
+  from?: string;
+};
+
+export type KeywordField = {
+  type: "KEYWORD";
+};
+
+export type FacetField = {
+  type: "FACET";
+};
+
+/**
+ * A TEXT field that also stores a vector embedding, so it can be searched by meaning with `$ann`.
+ *
+ * @see https://upstash.com/docs/redis/search/hybrid-search
+ */
+export type HybridField = {
+  type: "HYBRID";
+  noStem?: boolean;
+  from?: string;
+};
+
+export type DetailedField =
+  | TextField
+  | HybridField
+  | NumericField
+  | BoolField
+  | DateField
+  | KeywordField
+  | FacetField;
+export type NestedIndexSchema = {
+  [key: string]: FieldType | DetailedField | NestedIndexSchema;
+};
+
+export type FlatIndexSchema = {
+  [key: string]: FieldType | DetailedField;
+};
+
+export type SchemaPaths<T, Prefix extends string = ""> = {
+  [K in keyof T]: K extends string
+    ? T[K] extends FieldType | DetailedField
+      ? Prefix extends ""
+        ? K
+        : `${Prefix}${K}`
+      : T[K] extends object
+        ? SchemaPaths<T[K], `${Prefix}${K}.`>
+        : never
+    : never;
+}[keyof T];
+
+export type ExtractFieldType<T> = T extends FieldType
+  ? T
+  : T extends { type: infer U }
+    ? U extends FieldType
+      ? U
+      : never
+    : never;
+
+export type GetFieldAtPath<
+  TSchema,
+  Path extends string,
+> = Path extends `${infer First}.${infer Rest}`
+  ? First extends keyof TSchema
+    ? GetFieldAtPath<TSchema[First], Rest>
+    : never
+  : Path extends keyof TSchema
+    ? TSchema[Path]
+    : never;
+
+type FieldValueType<T extends FieldType> = T extends "TEXT" | "HYBRID"
+  ? string
+  : T extends "U64" | "I64" | "F64"
+    ? number
+    : T extends "BOOL"
+      ? boolean
+      : T extends "DATE"
+        ? string
+        : T extends "KEYWORD"
+          ? string
+          : T extends "FACET"
+            ? string
+            : never;
+
+type GetFieldValueType<TSchema, Path extends string> =
+  GetFieldAtPath<TSchema, Path> extends infer Field
+    ? Field extends FieldType | DetailedField
+      ? FieldValueType<ExtractFieldType<Field>>
+      : never
+    : never;
+
+// Helper type to check if a field has a 'from' property
+type HasFrom<T> = T extends { from: string } ? true : false;
+
+// Distributes field inference across unions so that
+// InferSchemaData<NestedIndexSchema | FlatIndexSchema> does not collapse to never
+type InferSchemaDataField<T> = T extends FieldType
+  ? FieldValueType<T>
+  : T extends DetailedField
+    ? FieldValueType<ExtractFieldType<T>>
+    : T extends NestedIndexSchema
+      ? InferSchemaData<T>
+      : unknown;
+
+type IsDefaultSchema<T> = [T] extends [NestedIndexSchema | FlatIndexSchema]
+  ? [NestedIndexSchema | FlatIndexSchema] extends [T]
+    ? true
+    : false
+  : false;
+
+type AsAnyIfUnknown<T> = unknown extends T ? any : T;
+
+export type InferSchemaData<TSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? any
+    : {
+        [K in keyof TSchema as TSchema[K] extends DetailedField
+          ? HasFrom<TSchema[K]> extends true
+            ? never
+            : K
+          : K]: AsAnyIfUnknown<InferSchemaDataField<TSchema[K]>>;
+      };
+
+// Query Options Types
+// These are the options that can be used for the query command
+// Short-circuit to permissive types when schema is the default (any) to avoid
+// excessively deep type instantiation.
+export type QueryOptions<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? {
+        filter?: Record<string, any>;
+        limit?: number;
+        offset?: number;
+        select?: Record<string, true>;
+        highlight?: {
+          fields: string[];
+          preTag?: string;
+          postTag?: string;
+        };
+        orderBy?: Record<string, "ASC" | "DESC">;
+        scoreFunc?: ScoreBy<string>;
+      }
+    : {
+        filter?: RootQueryFilter<TSchema> | Retriever<TSchema>;
+        /** Maximum number of results to return */
+        limit?: number;
+        /** Number of results to skip */
+        offset?: number;
+        select?: Partial<{ [K in SchemaPaths<TSchema>]: true }>; // {}
+        highlight?: {
+          fields: SchemaPaths<TSchema>[];
+          preTag?: string;
+          postTag?: string;
+        };
+      } & QueryOrderOption<TSchema>;
+
+type CombineMode = "multiply" | "sum";
+type ScoreMode = "multiply" | "sum" | "replace";
+type ScoreModifier =
+  | "none"
+  | "log"
+  | "log1p"
+  | "log2p"
+  | "ln"
+  | "ln1p"
+  | "ln2p"
+  | "square"
+  | "sqrt"
+  | "reciprocal";
+
+export type ScoreBy<TSchemaPaths extends string> =
+  | ScoreByField<false, TSchemaPaths>
+  | {
+      fields: ScoreByField<true, TSchemaPaths>[];
+      combineMode?: CombineMode;
+      scoreMode?: ScoreMode;
+    };
+
+type ScoreByField<TMultiple extends boolean, TSchemaPaths extends string> =
+  | {
+      field: TSchemaPaths;
+      modifier?: ScoreModifier;
+      factor?: number;
+      missing?: number;
+      scoreMode?: TMultiple extends true ? never : ScoreMode;
+    }
+  | TSchemaPaths;
+
+type QueryOrderOption<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  | {
+      orderBy?: {
+        [K in SchemaPaths<TSchema>]: { [P in K]: "ASC" | "DESC" };
+      }[SchemaPaths<TSchema>];
+    }
+  | {
+      scoreFunc?: ScoreBy<SchemaPaths<TSchema>>;
+    };
+
+/**
+ * Converts dot notation paths to nested object structure type
+ * e.g. "content.title" | "content.author" becomes { content: { title: ..., author: ... } }
+ */
+type PathToNestedObject<
+  TSchema,
+  Path extends string,
+  Value,
+> = Path extends `${infer First}.${infer Rest}`
+  ? { [K in First]: PathToNestedObject<TSchema, Rest, Value> }
+  : { [K in Path]: Value };
+
+/**
+ * Merges intersection of objects into a single object type with proper nesting
+ */
+type DeepMerge<T> = T extends object
+  ? {
+      [K in keyof T]: T[K] extends object ? DeepMerge<T[K]> : T[K];
+    }
+  : T;
+
+/**
+ * Build nested result type from selected paths
+ */
+type BuildNestedResult<TSchema, TFields> =
+  IsDefaultSchema<TSchema> extends true
+    ? DeepMerge<
+        UnionToIntersection<
+          {
+            [Path in keyof TFields & string]: PathToNestedObject<any, Path, any>;
+          }[keyof TFields & string]
+        >
+      >
+    : DeepMerge<
+        UnionToIntersection<
+          {
+            [Path in keyof TFields & SchemaPaths<TSchema>]: PathToNestedObject<
+              TSchema,
+              Path & string,
+              AsAnyIfUnknown<GetFieldValueType<TSchema, Path & string>>
+            >;
+          }[keyof TFields & SchemaPaths<TSchema>]
+        >
+      >;
+
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
+  k: infer I
+) => void
+  ? I
+  : never;
+
+export type QueryResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TOptions extends QueryOptions<TSchema> | undefined = undefined,
+> = TOptions extends { select: infer TFields }
+  ? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    {} extends TFields
+    ? { key: string; score: number }
+    : {
+        key: string;
+        score: number;
+        data: BuildNestedResult<TSchema, TFields>;
+      }
+  : {
+      key: string;
+      score: number;
+      data: InferSchemaData<TSchema>;
+    };
+
+export type PublicQueryResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TSelectFields extends SchemaPaths<TSchema>[] | undefined = undefined,
+> = QueryResult<
+  TSchema,
+  TSelectFields extends SchemaPaths<TSchema>[]
+    ? {
+        select: { [K in TSelectFields[number]]: true };
+      }
+    : undefined
+>;
+
+// Query Filter Types
+// These are the operations that can be used for each field type
+type StringOperationMap<T extends string> = {
+  $eq: T;
+  $in: T[];
+  $fuzzy: T | { value: T; distance?: number; transpositionCostOne?: boolean; prefix?: boolean };
+  $phrase:
+    | T
+    | { value: T }
+    | { value: T; slop: number; prefix?: never }
+    | { value: T; prefix: boolean; slop?: never };
+  $regex: T;
+  $smart: T;
+};
+
+type NumberOperationMap<T extends number> = {
+  $eq: T;
+  $in: T[];
+  $gt: T;
+  $gte: T;
+  $lt: T;
+  $lte: T;
+};
+
+type KeywordOperationMap<T extends string> = {
+  $eq: T;
+  $in: T[];
+  $gt: T;
+  $gte: T;
+  $lt: T;
+  $lte: T;
+};
+
+type BooleanOperationMap<T extends boolean> = {
+  $eq: T;
+  $in: T[];
+};
+
+type DateOperationMap<T extends string | Date> = {
+  $eq: T;
+  $in: T[];
+  $gt: T;
+  $gte: T;
+  $lte: T;
+  $lt: T;
+};
+
+type FacetOperationMap<T extends string> = {
+  $eq: T;
+  $in: T[];
+};
+
+// Create union types for each field type
+type StringOperations = {
+  [K in keyof StringOperationMap<string>]: { [P in K]: StringOperationMap<string>[K] } & {
+    $boost?: number;
+  };
+}[keyof StringOperationMap<string>];
+
+type NumberOperations = {
+  [K in keyof NumberOperationMap<number>]: { [P in K]: NumberOperationMap<number>[K] } & {
+    $boost?: number;
+  };
+}[keyof NumberOperationMap<number>];
+
+type BooleanOperations = {
+  [K in keyof BooleanOperationMap<boolean>]: { [P in K]: BooleanOperationMap<boolean>[K] } & {
+    $boost?: number;
+  };
+}[keyof BooleanOperationMap<boolean>];
+
+type DateOperations = {
+  [K in keyof DateOperationMap<string | Date>]: { [P in K]: DateOperationMap<string | Date>[K] } & {
+    $boost?: number;
+  };
+}[keyof DateOperationMap<string | Date>];
+
+type KeywordOperations = {
+  [K in keyof KeywordOperationMap<string>]: { [P in K]: KeywordOperationMap<string>[K] } & {
+    $boost?: number;
+  };
+}[keyof KeywordOperationMap<string>];
+
+type FacetOperations = {
+  [K in keyof FacetOperationMap<string>]: { [P in K]: FacetOperationMap<string>[K] } & {
+    $boost?: number;
+  };
+}[keyof FacetOperationMap<string>];
+
+// Create a union type for all operations for a given field type
+type OperationsForFieldType<T extends FieldType> = T extends "TEXT" | "HYBRID"
+  ? StringOperations
+  : T extends "U64" | "I64" | "F64"
+    ? NumberOperations
+    : T extends "BOOL"
+      ? BooleanOperations
+      : T extends "DATE"
+        ? DateOperations
+        : T extends "KEYWORD"
+          ? KeywordOperations
+          : T extends "FACET"
+            ? FacetOperations
+            : never;
+
+// Create a union type for all operations for a given path
+type PathOperations<TSchema, TPath extends string> =
+  GetFieldAtPath<TSchema, TPath> extends infer Field
+    ? Field extends FieldType | DetailedField
+      ? OperationsForFieldType<ExtractFieldType<Field>> | FieldValueType<ExtractFieldType<Field>>
+      : never
+    : never;
+
+// Create a type for a query leaf (only field paths, no boolean operators)
+type QueryLeaf<TSchema> = {
+  // allowed schema paths
+  [K in SchemaPaths<TSchema>]?: PathOperations<TSchema, K>;
+} & {
+  $and?: never;
+  $or?: never;
+  $must?: never;
+  $should?: never;
+  $mustNot?: never;
+  $boost?: number;
+};
+
+type BoolBase<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  [P in SchemaPaths<TSchema>]?: PathOperations<TSchema, P>;
+};
+
+// $and: all conditions must match
+type AndNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $and: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $or?: never;
+  $must?: never;
+  $should?: never;
+  $mustNot?: never;
+};
+
+// $or: at least one condition must match
+type OrNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $or: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $must?: never;
+  $should?: never;
+  $mustNot?: never;
+};
+
+// $must only
+type MustNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $must: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+  $should?: never;
+  $mustNot?: never;
+};
+
+// $should only
+type ShouldNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $should: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+  $must?: never;
+  $mustNot?: never;
+};
+
+// $must + $should combined
+type MustShouldNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $must: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $should: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $and?: never;
+  $or?: never;
+};
+
+// $mustNot only
+type NotNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+  $must?: never;
+  $should?: never;
+};
+
+type AndNotNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $and: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $or?: never;
+  $must?: never;
+  $should?: never;
+};
+
+type OrNotNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $or: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $must?: never;
+  $should?: never;
+};
+
+// $should + $mustNot combined
+type ShouldNotNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $should: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+  $must?: never;
+};
+
+type MustNotNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $must: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+  $should?: never;
+};
+
+// Full boolean node: $must + $should + $mustNot
+type BoolNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = BoolBase<TSchema> & {
+  $must: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $should: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $mustNot: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $or?: never;
+};
+
+// Create a type for a query filter
+// Short-circuit to Record<string, any> when schema is the default (any) to avoid
+// excessively deep type instantiation from the recursive filter union types.
+export type QueryFilter<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? Record<string, any>
+    :
+        | QueryLeaf<TSchema>
+        | AndNode<TSchema>
+        | OrNode<TSchema>
+        | MustNode<TSchema>
+        | ShouldNode<TSchema>
+        | MustShouldNode<TSchema>
+        | NotNode<TSchema>
+        | AndNotNode<TSchema>
+        | OrNotNode<TSchema>
+        | ShouldNotNode<TSchema>
+        | MustNotNode<TSchema>
+        | BoolNode<TSchema>;
+
+// Create a type for root-level queries (restricts $or from mixing with fields)
+export type RootQueryFilter<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? Record<string, any>
+    :
+        | QueryLeaf<TSchema>
+        | AndNode<TSchema>
+        | RootOrNode<TSchema>
+        | MustNode<TSchema>
+        | ShouldNode<TSchema>
+        | MustShouldNode<TSchema>
+        | AndNotNode<TSchema>
+        | ShouldNotNode<TSchema>
+        | BoolNode<TSchema>;
+
+// Restricted version of OrNode that doesn't allow field operations at root level
+type RootOrNode<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  [P in SchemaPaths<TSchema>]?: never; // No field operations at root level with $or
+} & {
+  $or: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+  $boost?: number;
+  $and?: never;
+  $must?: never;
+  $should?: never;
+  $mustNot?: QueryFilter<TSchema> | QueryFilter<TSchema>[];
+};
+
+// Retrievers
+// @see https://upstash.com/docs/redis/search/retrievers/overview
+
+/**
+ * Runs a semantic search on a HYBRID field.
+ *
+ * @see https://upstash.com/docs/redis/search/retrievers/ann
+ */
+export type AnnRetriever<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  $ann: {
+    /** The HYBRID field to search */
+    field: IsDefaultSchema<TSchema> extends true ? string : HybridPaths<TSchema>;
+    /** The text to search for. Cannot be empty. */
+    query: string;
+    /** Accuracy and speed trade-off. Defaults to `balanced`. */
+    profile?: "fast" | "balanced" | "precise";
+    /** Only documents that match this query are returned */
+    filter?: RootQueryFilter<TSchema>;
+    /** Scales how much the results add to the `$rrf` score. Valid only inside `$rrf`. */
+    weight?: number;
+  };
+};
+
+/**
+ * Runs one query. Use it inside `$rrf` to set the weight of a query.
+ *
+ * @see https://upstash.com/docs/redis/search/retrievers/standard
+ */
+export type StandardRetriever<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  $standard: {
+    query: RootQueryFilter<TSchema>;
+    /** Scales how much the query adds to the `$rrf` score. Valid only inside `$rrf`. */
+    weight?: number;
+  };
+};
+
+/**
+ * Merges the results of 2 to 10 retrievers with Reciprocal Rank Fusion.
+ *
+ * @see https://upstash.com/docs/redis/search/retrievers/rrf
+ */
+export type RrfRetriever<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TAllowAnn extends boolean = true,
+> = {
+  $rrf: {
+    /** 2 to 10 retrievers to merge */
+    retrievers: (
+      | RootQueryFilter<TSchema>
+      | StandardRetriever<TSchema>
+      | (TAllowAnn extends true ? AnnRetriever<TSchema> : never)
+    )[];
+    /** Higher values give lower-ranked results more influence. Defaults to `60`. */
+    rankConstant?: number;
+    /** The number of results each retriever contributes. Defaults to `LIMIT`. */
+    window?: number;
+  };
+};
+
+export type Retriever<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  | AnnRetriever<TSchema>
+  | StandardRetriever<TSchema>
+  | RrfRetriever<TSchema>;
+
+/**
+ * Retrievers accepted by `SEARCH.COUNT` and `SEARCH.AGGREGATE`, which do not support `$ann`.
+ */
+export type CountRetriever<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  | StandardRetriever<TSchema>
+  | RrfRetriever<TSchema, false>;
+
+// Helper type to extract only HYBRID field paths from schema
+export type HybridPaths<T, Prefix extends string = ""> = {
+  [K in keyof T]: K extends string
+    ? T[K] extends "HYBRID" | { type: "HYBRID" }
+      ? Prefix extends ""
+        ? K
+        : `${Prefix}${K}`
+      : T[K] extends FieldType | DetailedField
+        ? never
+        : T[K] extends object
+          ? HybridPaths<T[K], `${Prefix}${K}.`>
+          : never
+    : never;
+}[keyof T];
+
+export type DescribeFieldInfo = {
+  type: FieldType;
+  noTokenize?: boolean;
+  noStem?: boolean;
+  fast?: boolean;
+  from?: string;
+};
+
+export type IndexDescription<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  name: string;
+  dataType: "hash" | "string" | "json" | "stream";
+  /**
+   * Key prefixes tracked by the index. For a stream index, this holds the single stream key.
+   */
+  prefixes: string[];
+  language?: Language;
+  schema: IsDefaultSchema<TSchema> extends true
+    ? Record<string, DescribeFieldInfo>
+    : Record<SchemaPaths<TSchema>, DescribeFieldInfo>;
+};
+
+export type Language =
+  | "english"
+  | "arabic"
+  | "danish"
+  | "dutch"
+  | "finnish"
+  | "french"
+  | "german"
+  | "greek"
+  | "hungarian"
+  | "italian"
+  | "norwegian"
+  | "portuguese"
+  | "romanian"
+  | "russian"
+  | "spanish"
+  | "swedish"
+  | "tamil"
+  | "turkish";
+
+// Helper type to extract only FACET field paths from schema
+export type FacetPaths<T, Prefix extends string = ""> = {
+  [K in keyof T]: K extends string
+    ? T[K] extends "FACET" | { type: "FACET" }
+      ? Prefix extends ""
+        ? K
+        : `${Prefix}${K}`
+      : T[K] extends FieldType | DetailedField
+        ? never
+        : T[K] extends object
+          ? FacetPaths<T[K], `${Prefix}${K}.`>
+          : never
+    : never;
+}[keyof T];
+
+// Aggregate Types
+export type AggregateOptions<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? {
+        filter?: Record<string, any>;
+        aggregations: {
+          [key: string]: Record<string, any>;
+        };
+      }
+    : {
+        filter?: RootQueryFilter<TSchema> | CountRetriever<TSchema>;
+        aggregations: {
+          [key: string]: Aggregation<TSchema>;
+        };
+      };
+
+export type Aggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  IsDefaultSchema<TSchema> extends true
+    ? Record<string, any>
+    :
+        | TermsAggregation<TSchema>
+        | RangeAggregation<TSchema>
+        | HistogramAggregation<TSchema>
+        | StatsAggregation<TSchema>
+        | AvgAggregation<TSchema>
+        | SumAggregation<TSchema>
+        | MinAggregation<TSchema>
+        | MaxAggregation<TSchema>
+        | CountAggregation<TSchema>
+        | ExtendedStatsAggregation<TSchema>
+        | PercentilesAggregation<TSchema>
+        | CardinalityAggregation<TSchema>
+        | FacetAggregation<TSchema>;
+
+type BaseAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  $aggs?: {
+    [key: string]: Aggregation<TSchema>;
+  };
+};
+
+export type TermsAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $terms: {
+      field: SchemaPaths<TSchema>;
+      size?: number;
+    };
+  };
+
+export type RangeAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $range: {
+      field: SchemaPaths<TSchema>;
+      ranges: { from?: number; to?: number }[];
+    };
+  };
+
+export type HistogramAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $histogram: {
+      field: SchemaPaths<TSchema>;
+      interval: number;
+    };
+  };
+
+export type StatsAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $stats: {
+      field: SchemaPaths<TSchema>;
+      missing?: number;
+    };
+  };
+
+export type AvgAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $avg: {
+      field: SchemaPaths<TSchema>;
+      missing?: number;
+    };
+  };
+
+export type SumAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $sum: {
+      field: SchemaPaths<TSchema>;
+      missing?: number;
+    };
+  };
+
+export type MinAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $min: {
+      field: SchemaPaths<TSchema>;
+      missing?: number;
+    };
+  };
+
+export type MaxAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $max: {
+      field: SchemaPaths<TSchema>;
+      missing?: number;
+    };
+  };
+
+export type CountAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $count: {
+      field: SchemaPaths<TSchema>;
+    };
+  };
+
+export type ExtendedStatsAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $extendedStats: {
+      field: SchemaPaths<TSchema>;
+      sigma?: number;
+      missing?: number;
+    };
+  };
+
+export type PercentilesAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $percentiles: {
+      field: SchemaPaths<TSchema>;
+      percents?: number[];
+      keyed?: boolean;
+      missing?: number;
+    };
+  };
+
+export type CardinalityAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $cardinality: {
+      field: SchemaPaths<TSchema>;
+    };
+  };
+
+export type FacetAggregation<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  BaseAggregation<TSchema> & {
+    $facet: {
+      field: FacetPaths<TSchema>;
+      path: string;
+      depth?: number;
+      size?: number;
+      minDocCount?: number;
+      order?: { count: "desc" | "asc" };
+    };
+  };
+
+export type AggregateResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TOpts extends AggregateOptions<TSchema>,
+> =
+  IsDefaultSchema<TSchema> extends true
+    ? Record<string, any>
+    : BuildAggregateResult<
+        TSchema,
+        Extract<TOpts["aggregations"], { [key: string]: Aggregation<TSchema> }>
+      >;
+
+type BuildAggregateResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TAggs extends { [key: string]: Aggregation<TSchema> },
+> = {
+  [K in keyof TAggs]: TAggs[K] extends TermsAggregation<TSchema>
+    ? TermsResult<TSchema, TAggs[K]>
+    : TAggs[K] extends RangeAggregation<TSchema>
+      ? RangeResult<TSchema, TAggs[K]>
+      : TAggs[K] extends HistogramAggregation<TSchema>
+        ? HistogramResult<TSchema, TAggs[K]>
+        : TAggs[K] extends StatsAggregation<TSchema>
+          ? StatsResult
+          : TAggs[K] extends AvgAggregation<TSchema>
+            ? MetricValueResult
+            : TAggs[K] extends SumAggregation<TSchema>
+              ? MetricValueResult
+              : TAggs[K] extends MinAggregation<TSchema>
+                ? MetricValueResult
+                : TAggs[K] extends MaxAggregation<TSchema>
+                  ? MetricValueResult
+                  : TAggs[K] extends CountAggregation<TSchema>
+                    ? MetricValueResult
+                    : TAggs[K] extends CardinalityAggregation<TSchema>
+                      ? MetricValueResult
+                      : TAggs[K] extends ExtendedStatsAggregation<TSchema>
+                        ? ExtendedStatsResult<TAggs[K]>
+                        : TAggs[K] extends PercentilesAggregation<TSchema>
+                          ? PercentilesResult<TAggs[K]>
+                          : TAggs[K] extends FacetAggregation<TSchema>
+                            ? FacetResult
+                            : never;
+};
+
+type Bucket<T> = {
+  key: T;
+  docCount: number;
+  from?: number;
+  to?: number;
+};
+
+type TermsResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TAgg extends TermsAggregation<TSchema>,
+> = TAgg["$aggs"] extends { [key: string]: Aggregation<TSchema> }
+  ? {
+      buckets: (Bucket<GetFieldValueType<TSchema, TAgg["$terms"]["field"]>> &
+        BuildAggregateResult<TSchema, TAgg["$aggs"]>)[];
+      sumOtherDocCount: number;
+      docCountErrorUpperBound: number;
+    }
+  : {
+      buckets: Bucket<GetFieldValueType<TSchema, TAgg["$terms"]["field"]>>[];
+      sumOtherDocCount: number;
+      docCountErrorUpperBound: number;
+    };
+
+type RangeResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TAgg extends RangeAggregation<TSchema>,
+> = TAgg["$aggs"] extends { [key: string]: Aggregation<TSchema> }
+  ? {
+      buckets: (Bucket<string> & BuildAggregateResult<TSchema, TAgg["$aggs"]>)[];
+    }
+  : {
+      buckets: Bucket<string>[];
+    };
+
+type HistogramResult<
+  TSchema extends NestedIndexSchema | FlatIndexSchema,
+  TAgg extends HistogramAggregation<TSchema>,
+> = TAgg["$aggs"] extends { [key: string]: Aggregation<TSchema> }
+  ? {
+      buckets: (Bucket<number> & BuildAggregateResult<TSchema, TAgg["$aggs"]>)[];
+    }
+  : {
+      buckets: Bucket<number>[];
+    };
+
+type MetricValueResult = {
+  value: number;
+};
+
+type StatsResult = {
+  count: number;
+  min: number;
+  max: number;
+  sum: number;
+  avg: number;
+};
+
+type ExtendedStatsResult<_TAgg> = {
+  count: number;
+  min: number;
+  max: number;
+  avg: number;
+  sum: number;
+  sumOfSquares: number;
+  variance: number;
+  variancePopulation: number;
+  varianceSampling: number;
+  stdDeviation: number;
+  stdDeviationPopulation: number;
+  stdDeviationSampling: number;
+  stdDeviationBounds: {
+    upper: number;
+    lower: number;
+    upperSampling: number;
+    lowerSampling: number;
+    upperPopulation: number;
+    lowerPopulation: number;
+  };
+};
+
+type PercentilesResult<TAgg> = TAgg extends { $percentiles: { keyed: false } }
+  ? {
+      values: Array<{ key: number; value: number }>;
+    }
+  : {
+      values: { [key: string]: number };
+    };
+
+type FacetChildNode = {
+  path: string;
+  docCount: number;
+  sumOtherDocCount: number;
+  children?: FacetChildNode[];
+};
+
+type FacetResult = {
+  path: string;
+  sumOtherDocCount: number;
+  children: FacetChildNode[];
+};