// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import * as NamespacesAPI from './namespaces';
import { APIPromise } from '../core/api-promise';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';
import { AggregateBy, Filter, GroupBy, RankBy, RerankBy } from './custom';
import { ClientPerformance } from '../internal/custom/performance';
import { NotFoundError } from '../error';

export class Namespace extends APIResource {
  /**
   * Creates an instant, copy-on-write clone of a namespace.
   */
  branchFrom(
    params: NamespaceBranchFromParams,
    options?: RequestOptions,
  ): APIPromise<NamespaceBranchFromResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params;
    return this._client.post(path`/v2/namespaces/${namespace}?stainless_overload=branchFrom`, {
      body: { branch_from_namespace: body },
      ...options,
    });
  }

  /**
   * Copy all documents from another namespace into this one.
   */
  copyFrom(params: NamespaceCopyFromParams, options?: RequestOptions): APIPromise<NamespaceCopyFromResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params;
    return this._client.post(path`/v2/namespaces/${namespace}?stainless_overload=copyFrom`, {
      body: { copy_from_namespace: body },
      ...options,
    });
  }

  /**
   * Delete namespace.
   */
  deleteAll(
    params: NamespaceDeleteAllParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceDeleteAllResponse> {
    const { namespace = this._client.defaultNamespace } = params ?? {};
    return this._client.delete(path`/v2/namespaces/${namespace}`, options);
  }

  /**
   * Explain a query plan.
   */
  explainQuery(
    params: NamespaceExplainQueryParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceExplainQueryResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params ?? {};
    return this._client.post(path`/v2/namespaces/${namespace}/explain_query`, { body, ...options });
  }

  /**
   * Signal turbopuffer to prepare for low-latency requests.
   */
  hintCacheWarm(
    params: NamespaceHintCacheWarmParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceHintCacheWarmResponse> {
    const { namespace = this._client.defaultNamespace } = params ?? {};
    return this._client.get(path`/v1/namespaces/${namespace}/hint_cache_warm`, options);
  }

  /**
   * Get metadata about a namespace.
   */
  metadata(
    params: NamespaceMetadataParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceMetadata> {
    const { namespace = this._client.defaultNamespace } = params ?? {};
    return this._client.get(path`/v2/namespaces/${namespace}/metadata`, options);
  }

  /**
   * Issue multiple concurrent queries filter or search documents.
   */
  multiQuery(
    params: NamespaceMultiQueryParams,
    options?: RequestOptions,
  ): APIPromise<NamespaceMultiQueryResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params;
    return this._client.post(path`/v2/namespaces/${namespace}/query?stainless_overload=multiQuery`, {
      body,
      ...options,
    });
  }

  /**
   * Query, filter, full-text search and vector search documents.
   */
  query(
    params: NamespaceQueryParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceQueryResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params ?? {};
    return this._client.post(path`/v2/namespaces/${namespace}/query`, { body, ...options });
  }

  /**
   * Evaluate recall.
   */
  recall(
    params: NamespaceRecallParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceRecallResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params ?? {};
    return this._client.post(path`/v1/namespaces/${namespace}/_debug/recall`, { body, ...options });
  }

  /**
   * Get namespace schema.
   */
  schema(
    params: NamespaceSchemaParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceSchemaResponse> {
    const { namespace = this._client.defaultNamespace } = params ?? {};
    return this._client.get(path`/v1/namespaces/${namespace}/schema`, options);
  }

  /**
   * Check whether the namespace exists.
   */
  async exists() {
    try {
      await this.schema();
      return true;
    } catch (e) {
      if (e instanceof NotFoundError) {
        return false;
      }
      throw e;
    }
  }

  /**
   * Update metadata configuration for a namespace.
   */
  updateMetadata(
    params: NamespaceUpdateMetadataParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceMetadata> {
    const { namespace = this._client.defaultNamespace, ...body } = params ?? {};
    return this._client.patch(path`/v1/namespaces/${namespace}/metadata`, { body, ...options });
  }

  /**
   * Update namespace schema.
   */
  updateSchema(
    params: NamespaceUpdateSchemaParams | null | undefined = undefined,
    options?: RequestOptions,
  ): APIPromise<NamespaceUpdateSchemaResponse> {
    const { namespace = this._client.defaultNamespace, schema } = params ?? {};
    return this._client.post(path`/v1/namespaces/${namespace}/schema`, { body: schema, ...options });
  }

  /**
   * Create, update, or delete documents.
   */
  write(
    params: NamespaceWriteParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<NamespaceWriteResponse> {
    const { namespace = this._client.defaultNamespace, ...body } = params ?? {};
    return this._client.post(path`/v2/namespaces/${namespace}`, { body, maxRetries: 6, ...options });
  }
}

/**
 * A single aggregation group.
 */
export type AggregationGroup = { [key: string]: unknown };

/**
 * Whether to automatically embed this string attribute into a vector attribute.
 * Can be a model name, a detailed configuration object, or `null` to remove an
 * existing embedding configuration.
 */
export type AttributeEmbed = string | AttributeEmbedConfig;

/**
 * Configuration options for automatic embedding.
 */
export interface AttributeEmbedConfig {
  /**
   * The model to use for embedding. See our documentation for a list of models
   * supported in each region.
   */
  model: string;

  /**
   * The name of an existing vector attribute to store embeddings in. If omitted,
   * turbopuffer will generate a computed vector attribute named
   * `$embed_<attribute>`.
   */
  attribute?: string;

  /**
   * The dimensionality to embed at. If not set, will pick the default for this
   * model. If you're storing embeddings in an existing attribute, this can be
   * omitted, and may not be set to a value other than the dimensions of that
   * attribute.
   */
  dims?: number;
}

/**
 * The schema for an attribute attached to a document.
 */
export type AttributeSchema = AttributeType | AttributeSchemaConfig;

/**
 * Detailed configuration for an attribute attached to a document.
 */
export interface AttributeSchemaConfig {
  /**
   * The data type of the attribute. Valid values: string, int, uint, float, uuid,
   * datetime, bool, []string, []int, []uint, []float, []uuid, []datetime, []bool,
   * [DIMS]f16, [DIMS]f32, {}f16.
   */
  type: AttributeType;

  /**
   * Whether to create an approximate nearest neighbor index for the attribute. Can
   * be a boolean or a detailed configuration object.
   */
  ann?: boolean | AttributeSchemaConfig.AnnConfig;

  /**
   * Whether to automatically embed this string attribute into a vector attribute.
   * Can be a model name, a detailed configuration object, or `null` to remove an
   * existing embedding configuration.
   */
  embed?: AttributeEmbed | null;

  /**
   * Whether or not the attributes can be used in filters.
   */
  filterable?: boolean;

  /**
   * Whether this attribute can be used as part of a BM25 full-text search. Requires
   * the `string` or `[]string` type, and by default, BM25-enabled attributes are not
   * filterable. You can override this by setting `filterable: true`.
   */
  full_text_search?: FullTextSearch;

  /**
   * Whether to enable Fuzzy filters on this attribute.
   */
  fuzzy?: boolean;

  /**
   * Whether to enable Glob filters on this attribute.
   */
  glob?: boolean;

  /**
   * Whether to enable Regex filters on this attribute.
   */
  regex?: boolean;

  /**
   * Whether to create a sparse kNN index for the attribute. Requires the `{}f16`
   * type.
   */
  sparse_knn?: AttributeSchemaConfig.SparseKnn;
}

export namespace AttributeSchemaConfig {
  /**
   * Configuration options for ANN (Approximate Nearest Neighbor) indexing.
   */
  export interface AnnConfig {
    /**
     * A function used to calculate vector similarity.
     */
    distance_metric?: NamespacesAPI.DistanceMetric;

    /**
     * Opt in to late-interaction (MUVERA) indexing. Only valid on fixed-dim `[][N]f32`
     * vector array attributes, and is required to enable an ANN index on such
     * attributes. Defaults to `false`.
     */
    late_interaction?: boolean;
  }

  /**
   * Whether to create a sparse kNN index for the attribute. Requires the `{}f16`
   * type.
   */
  export interface SparseKnn {
    /**
     * A function used to calculate sparse vector similarity.
     */
    distance_metric: NamespacesAPI.SparseDistanceMetric;
  }
}

/**
 * The data type of the attribute. Valid values: string, int, uint, float, uuid,
 * datetime, bool, []string, []int, []uint, []float, []uuid, []datetime, []bool,
 * [DIMS]f16, [DIMS]f32, {}f16.
 */
export type AttributeType = string;

/**
 * Additional (optional) parameters for a single BM25 query clause.
 */
export interface Bm25ClauseParams {
  /**
   * Whether to treat the last token in the query input as a literal prefix.
   */
  last_as_prefix?: boolean;
}

/**
 * The namespace to create an instant, copy-on-write clone of.
 */
export type BranchFromNamespaceParams = string | BranchFromNamespaceParams.BranchFromNamespaceConfig;

export namespace BranchFromNamespaceParams {
  export interface BranchFromNamespaceConfig {
    /**
     * The namespace to create an instant, copy-on-write clone of.
     */
    source_namespace: string;
  }
}

/**
 * A list of documents in columnar format. Each key is a column name, mapped to an
 * array of values for that column.
 */
export interface Columns {
  /**
   * The IDs of the documents.
   */
  id: Array<ID>;

  /**
   * The vector embeddings of the documents.
   */
  vector?: Array<Vector> | Array<number> | string;

  [k: string]: Array<unknown> | Array<ID> | Array<Vector> | Array<number> | string | undefined;
}

/**
 * Additional (optional) parameters for the ContainsAllTokens filter.
 */
export interface ContainsAllTokensFilterParams {
  /**
   * Whether to treat the last token in the query input as a literal prefix.
   */
  last_as_prefix?: boolean;
}

/**
 * Additional (optional) parameters for the ContainsAnyToken filter.
 */
export interface ContainsAnyTokenFilterParams {
  /**
   * Whether to treat the last token in the query input as a literal prefix.
   */
  last_as_prefix?: boolean;
}

/**
 * The namespace to copy documents from.
 */
export type CopyFromNamespaceParams = string | CopyFromNamespaceParams.CopyFromNamespaceConfig;

export namespace CopyFromNamespaceParams {
  export interface CopyFromNamespaceConfig {
    /**
     * The namespace to copy documents from.
     */
    source_namespace: string;

    /**
     * (Optional) An API key for the organization containing the source namespace
     */
    source_api_key?: string;

    /**
     * (Optional) The region of the source namespace.
     */
    source_region?: string;
  }
}

/**
 * Additional parameters for the Decay operator.
 */
export interface DecayParams {
  /**
   * An exponent that helps further control the shape of the Decay function.
   */
  exponent?: number;

  /**
   * The midpoint of the Decay operator.
   */
  midpoint?: unknown;
}

/**
 * A function used to calculate vector similarity.
 *
 * - `cosine_distance` - Defined as `1 - cosine_similarity` and ranges from 0 to 2.
 *   Lower is better.
 * - `euclidean_squared` - Defined as `sum((x - y)^2)`. Lower is better.
 */
export type DistanceMetric = 'cosine_distance' | 'euclidean_squared';

/**
 * Additional (optional) parameters for the Embed expression.
 */
export interface EmbedParams {
  /**
   * The model to use for embedding, overriding the model configured for the
   * attribute.
   */
  model?: string;
}

/**
 * The encryption configuration for a namespace.
 */
export type Encryption = Encryption.CustomerManaged | Encryption.Default;

export namespace Encryption {
  /**
   * Encrypt the namespace with a customer-managed encryption key (CMEK).
   */
  export interface CustomerManaged {
    /**
     * The identifier of the CMEK key to use for encryption. For GCP, the
     * fully-qualified resource name of the key. For AWS, the ARN of the key.
     */
    key_name: string;

    mode: 'customer-managed';
  }

  /**
   * Use the default server-side encryption (SSE).
   */
  export interface Default {
    mode: 'default';
  }
}

/**
 * Whether this attribute can be used as part of a BM25 full-text search. Requires
 * the `string` or `[]string` type, and by default, BM25-enabled attributes are not
 * filterable. You can override this by setting `filterable: true`.
 */
export type FullTextSearch = boolean | FullTextSearchConfig;

/**
 * Configuration options for full-text search.
 */
export interface FullTextSearchConfig {
  /**
   * Whether to convert each non-ASCII character in a token to its ASCII equivalent,
   * if one exists (e.g., à -> a). Defaults to `false` (i.e., no folding).
   */
  ascii_folding?: boolean;

  /**
   * The `b` document length normalization parameter for BM25. Defaults to `0.75`.
   */
  b?: number;

  /**
   * Whether searching is case-sensitive. Defaults to `false` (i.e.
   * case-insensitive).
   */
  case_sensitive?: boolean;

  /**
   * The `k1` term saturation parameter for BM25. Defaults to `1.2`.
   */
  k1?: number;

  /**
   * Describes the language of a text attribute. Defaults to `english`.
   */
  language?: Language;

  /**
   * Maximum length of a token in bytes. Tokens larger than this value during
   * tokenization will be filtered out. Has to be between `1` and `254` (inclusive).
   * Defaults to `39`.
   */
  max_token_length?: number;

  /**
   * Removes common words from the text based on language. Defaults to `true` (i.e.
   * remove common words).
   */
  remove_stopwords?: boolean;

  /**
   * Language-specific stemming for the text. Defaults to `false` (i.e., do not
   * stem).
   */
  stemming?: boolean;

  /**
   * The tokenizer to use for full-text search on an attribute. Defaults to
   * `word_v4`.
   */
  tokenizer?: Tokenizer;
}

/**
 * An edit distance threshold for the Fuzzy filter.
 */
export interface FuzzyMaxEditDistance {
  /**
   * The maximum edit distance to allow.
   */
  distance: number;

  /**
   * Minimum number of characters in a query where this distance applies. Must be at
   * least 3 · (distance + 1).
   */
  min_query_chars: number;
}

/**
 * Additional parameters for the Fuzzy filter.
 */
export interface FuzzyParams {
  /**
   * Maximum edit distance allowed at each query length. Queries shorter than the
   * first threshold return no matches.
   */
  max_edit_distance: Array<FuzzyMaxEditDistance>;

  /**
   * Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e.
   * case-sensitive).
   */
  case_sensitive?: boolean;
}

/**
 * An identifier for a document.
 */
export type ID = string | number;

/**
 * Whether to include attributes in the response.
 */
export type IncludeAttributes = boolean | Array<string>;

/**
 * Describes the language of a text attribute. Defaults to `english`.
 */
export type Language =
  | 'arabic'
  | 'danish'
  | 'dutch'
  | 'english'
  | 'finnish'
  | 'french'
  | 'german'
  | 'greek'
  | 'hungarian'
  | 'italian'
  | 'norwegian'
  | 'portuguese'
  | 'romanian'
  | 'russian'
  | 'spanish'
  | 'swedish'
  | 'tamil'
  | 'turkish';

/**
 * Limits the documents returned by a query.
 */
export interface Limit {
  /**
   * Limits the total number of documents returned.
   */
  total: number;

  /**
   * Limits the number of documents with the same value for a set of attributes (the
   * "limit key") that can appear in the results.
   */
  per?: Limit.Per;
}

export namespace Limit {
  /**
   * Limits the number of documents with the same value for a set of attributes (the
   * "limit key") that can appear in the results.
   */
  export interface Per {
    /**
     * The attributes to include in the limit key.
     */
    attributes: Array<string>;

    /**
     * The maximum number of documents to return for each value of the limit key.
     */
    limit: number;
  }
}

/**
 * Metadata about a namespace.
 */
export interface NamespaceMetadata {
  /**
   * The approximate number of logical bytes in the namespace.
   */
  approx_logical_bytes: number;

  /**
   * The approximate number of rows in the namespace.
   */
  approx_row_count: number;

  /**
   * The timestamp when the namespace was created.
   */
  created_at: string;

  /**
   * The encryption configuration for a namespace.
   */
  encryption: Encryption;

  index: NamespaceMetadata.IndexUpToDate | NamespaceMetadata.IndexUpdating;

  /**
   * The schema of the namespace.
   */
  schema: { [key: string]: AttributeSchemaConfig };

  /**
   * The timestamp when the namespace was last modified by a write operation.
   */
  updated_at: string;

  /**
   * Configuration for namespace pinning, along with the current status of the pinned
   * namespace.
   */
  pinning?: NamespaceMetadata.Pinning;

  /**
   * Configuration for namespace sharding, which partitions a namespace's documents
   * across multiple internal shards to scale indexing and query throughput beyond a
   * single machine. Sharding can only be configured on a namespace's inaugural
   * write, and cannot be added to or changed on an existing namespace.
   */
  sharding?: ShardingConfig;
}

export namespace NamespaceMetadata {
  export interface IndexUpToDate {
    status: 'up-to-date';
  }

  export interface IndexUpdating {
    status: 'updating';

    /**
     * The number of bytes in the namespace that are in the write-ahead log but have
     * not yet been indexed.
     */
    unindexed_bytes: number;
  }

  /**
   * Configuration for namespace pinning, along with the current status of the pinned
   * namespace.
   */
  export interface Pinning extends NamespacesAPI.PinningConfig {
    /**
     * Operational status for a pinned namespace.
     */
    status?: Pinning.Status;
  }

  export namespace Pinning {
    /**
     * Operational status for a pinned namespace.
     */
    export interface Status {
      /**
       * The number of replicas that are warm and serving traffic.
       */
      ready_replicas: number;

      /**
       * The timestamp of the latest pinning status snapshot.
       */
      updated_at: string;

      /**
       * Aggregate utilization for the pinned namespace, reported as a value between 0.0
       * and 1.0.
       */
      utilization: number;
    }
  }
}

/**
 * Request to update namespace metadata configuration.
 */
export interface NamespaceMetadataPatch {
  /**
   * Configuration for namespace pinning.
   *
   * - Missing field: no change to pinning configuration
   * - `null` or `false`: explicitly remove pinning
   * - `true`: enable pinning with default configuration
   * - Object: set pinning configuration
   */
  pinning?: boolean | PinningConfig | null;
}

/**
 * Configuration for namespace pinning.
 */
export interface PinningConfig {
  /**
   * The number of read replicas to provision. Defaults to 1 if not specified.
   */
  replicas?: number;
}

/**
 * The billing information for a query.
 */
export interface QueryBilling {
  /**
   * The number of billable logical bytes queried from the namespace.
   */
  billable_logical_bytes_queried: number;

  /**
   * The number of billable logical bytes returned from the query.
   */
  billable_logical_bytes_returned: number;
}

/**
 * The performance information for a query.
 */
export interface QueryPerformance {
  /**
   * the approximate number of documents in the namespace.
   */
  approx_namespace_size: number;

  /**
   * The ratio of cache hits to total cache lookups.
   */
  cache_hit_ratio: number;

  /**
   * A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
   */
  cache_temperature: string;

  /**
   * The number of unindexed documents processed by the query.
   */
  exhaustive_search_count: number;

  /**
   * Request time measured on the server, excluding time spent waiting due to the
   * namespace concurrency limit.
   */
  query_execution_ms: number;

  /**
   * Request time measured on the server, including time spent waiting for other
   * queries to complete if the namespace was at its concurrency limit.
   */
  server_total_ms: number;
}

/**
 * A single document, in a row-based format.
 */
export interface Row {
  /**
   * An identifier for a document.
   */
  id: ID;

  /**
   * A vector embedding associated with a document.
   */
  vector?: Vector;

  /**
   * The ranking function's score for the document: distance from the query
   * vector for ANN, BM25 score for BM25, omitted when ordering by an attribute.
   */
  $dist?: number;

  [k: string]: unknown;
}

/**
 * Configuration options for RRF.
 */
export interface RrfParams {
  /**
   * RRF rank constant (`k`). Must be greater than zero. Defaults to `60`.
   */
  rank_constant?: number;
}

/**
 * Additional parameters for the Saturate operator.
 */
export interface SaturateParams {
  /**
   * An exponent that helps further control the shape of the Saturate function.
   */
  exponent?: number;

  /**
   * The midpoint of the Saturate operator.
   */
  midpoint?: unknown;
}

/**
 * Configuration for namespace sharding, which partitions a namespace's documents
 * across multiple internal shards to scale indexing and query throughput beyond a
 * single machine. Sharding can only be configured on a namespace's inaugural
 * write, and cannot be added to or changed on an existing namespace.
 */
export interface ShardingConfig {
  /**
   * The number of shards to partition the namespace into.
   */
  num_shards: number;
}

/**
 * A function used to calculate sparse vector similarity.
 */
export type SparseDistanceMetric = 'dot_product';

/**
 * The tokenizer to use for full-text search on an attribute. Defaults to
 * `word_v4`.
 */
export type Tokenizer = 'pre_tokenized_array' | 'word_v0' | 'word_v1' | 'word_v2' | 'word_v3' | 'word_v4';

/**
 * A vector embedding associated with a document.
 */
export type Vector = Array<number> | string;

/**
 * The encoding to use for vectors in the response.
 */
export type VectorEncoding = 'float' | 'base64';

/**
 * The billing information for a write request.
 */
export interface WriteBilling {
  /**
   * The number of billable logical bytes written to the namespace.
   */
  billable_logical_bytes_written: number;

  /**
   * The billing information for a query.
   */
  query?: QueryBilling;
}

/**
 * The performance information for a write request.
 */
export interface WritePerformance {
  /**
   * Request time measured on the server, in milliseconds.
   */
  server_total_ms: number;
}

/**
 * The response to a successful write request.
 */
export interface NamespaceBranchFromResponse {
  /**
   * The billing information for a write request.
   */
  billing: WriteBilling;

  /**
   * A message describing the result of the write request.
   */
  message: string;

  /**
   * The number of rows affected by the write request.
   */
  rows_affected: number;

  /**
   * The status of the request.
   */
  status: 'OK';

  /**
   * The IDs of documents that were deleted. Only included when `return_affected_ids`
   * is true and at least one document was deleted.
   */
  deleted_ids?: Array<ID>;

  /**
   * The IDs of documents that were patched. Only included when `return_affected_ids`
   * is true and at least one document was patched.
   */
  patched_ids?: Array<ID>;

  /**
   * The performance information for a write request.
   */
  performance?: WritePerformance;

  /**
   * The number of rows deleted by the write request.
   */
  rows_deleted?: number;

  /**
   * The number of rows patched by the write request.
   */
  rows_patched?: number;

  /**
   * Whether more documents match the filter for partial operations.
   */
  rows_remaining?: boolean;

  /**
   * The number of rows upserted by the write request.
   */
  rows_upserted?: number;

  /**
   * The IDs of documents that were upserted. Only included when
   * `return_affected_ids` is true and at least one document was upserted.
   */
  upserted_ids?: Array<ID>;
}

/**
 * The response to a successful write request.
 */
export interface NamespaceCopyFromResponse {
  /**
   * The billing information for a write request.
   */
  billing: WriteBilling;

  /**
   * A message describing the result of the write request.
   */
  message: string;

  /**
   * The number of rows affected by the write request.
   */
  rows_affected: number;

  /**
   * The status of the request.
   */
  status: 'OK';

  /**
   * The IDs of documents that were deleted. Only included when `return_affected_ids`
   * is true and at least one document was deleted.
   */
  deleted_ids?: Array<ID>;

  /**
   * The IDs of documents that were patched. Only included when `return_affected_ids`
   * is true and at least one document was patched.
   */
  patched_ids?: Array<ID>;

  /**
   * The performance information for a write request.
   */
  performance?: WritePerformance;

  /**
   * The number of rows deleted by the write request.
   */
  rows_deleted?: number;

  /**
   * The number of rows patched by the write request.
   */
  rows_patched?: number;

  /**
   * Whether more documents match the filter for partial operations.
   */
  rows_remaining?: boolean;

  /**
   * The number of rows upserted by the write request.
   */
  rows_upserted?: number;

  /**
   * The IDs of documents that were upserted. Only included when
   * `return_affected_ids` is true and at least one document was upserted.
   */
  upserted_ids?: Array<ID>;
}

/**
 * The response to a successful namespace deletion request.
 */
export interface NamespaceDeleteAllResponse {
  /**
   * The status of the request.
   */
  status: 'OK';
}

/**
 * The response to a successful query explain.
 */
export interface NamespaceExplainQueryResponse {
  /**
   * The textual representation of the query plan.
   */
  plan_text?: string;
}

/**
 * The response to a successful cache warm request.
 */
export interface NamespaceHintCacheWarmResponse {
  /**
   * The status of the request.
   */
  status: 'ACCEPTED';

  message?: string;
}

/**
 * The result of a multi-query.
 */
export interface NamespaceMultiQueryResponse {
  /**
   * The billing information for a query.
   */
  billing: QueryBilling;

  /**
   * The performance information for a query.
   */
  performance: QueryPerformance;

  results: Array<NamespaceMultiQueryResponse.Result>;
}

export namespace NamespaceMultiQueryResponse {
  export interface Result {
    aggregation_groups?: Array<NamespacesAPI.AggregationGroup>;

    aggregations?: { [key: string]: unknown };

    rows?: Array<NamespacesAPI.Row>;
  }
}

/**
 * The result of a query.
 */
export interface NamespaceQueryResponse {
  /**
   * The billing information for a query.
   */
  billing: QueryBilling;

  /**
   * The performance information for a query.
   */
  performance: QueryPerformance & ClientPerformance;

  aggregation_groups?: Array<AggregationGroup>;

  aggregations?: { [key: string]: unknown };

  rows?: Array<Row>;
}

/**
 * The response to a successful cache warm request.
 */
export interface NamespaceRecallResponse {
  /**
   * The average number of documents retrieved by the approximate nearest neighbor
   * searches.
   */
  avg_ann_count: number;

  /**
   * The average number of documents retrieved by the exhaustive searches.
   */
  avg_exhaustive_count: number;

  /**
   * The average recall of the queries.
   */
  avg_recall: number;

  /**
   * Ground truth data including query vectors and true nearest neighbors. Only
   * included when include_ground_truth is true.
   */
  ground_truth?: Array<NamespaceRecallResponse.GroundTruth>;
}

export namespace NamespaceRecallResponse {
  export interface GroundTruth {
    /**
     * The true nearest neighbors with their distances and vectors.
     */
    nearest_neighbors: Array<NamespacesAPI.Row>;

    /**
     * The query vector used for this search.
     */
    query_vector: Array<number>;
  }
}

/**
 * The response to a successful namespace schema request.
 */
export type NamespaceSchemaResponse = { [key: string]: AttributeSchemaConfig };

/**
 * The updated schema for the namespace.
 */
export type NamespaceUpdateSchemaResponse = { [key: string]: AttributeSchemaConfig };

/**
 * The response to a successful write request.
 */
export interface NamespaceWriteResponse {
  /**
   * The billing information for a write request.
   */
  billing: WriteBilling;

  /**
   * A message describing the result of the write request.
   */
  message: string;

  /**
   * The number of rows affected by the write request.
   */
  rows_affected: number;

  /**
   * The status of the request.
   */
  status: 'OK';

  /**
   * The IDs of documents that were deleted. Only included when `return_affected_ids`
   * is true and at least one document was deleted.
   */
  deleted_ids?: Array<ID>;

  /**
   * The IDs of documents that were patched. Only included when `return_affected_ids`
   * is true and at least one document was patched.
   */
  patched_ids?: Array<ID>;

  /**
   * The performance information for a write request.
   */
  performance?: WritePerformance;

  /**
   * The number of rows deleted by the write request.
   */
  rows_deleted?: number;

  /**
   * The number of rows patched by the write request.
   */
  rows_patched?: number;

  /**
   * Whether more documents match the filter for partial operations.
   */
  rows_remaining?: boolean;

  /**
   * The number of rows upserted by the write request.
   */
  rows_upserted?: number;

  /**
   * The IDs of documents that were upserted. Only included when
   * `return_affected_ids` is true and at least one document was upserted.
   */
  upserted_ids?: Array<ID>;
}

export interface NamespaceBranchFromParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: The namespace to create an instant, copy-on-write clone of.
   */
  source_namespace: string;
}

export interface NamespaceCopyFromParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: The namespace to copy documents from.
   */
  source_namespace: string;

  /**
   * Body param: (Optional) The encryption configuration for the destination
   * namespace.
   */
  dest_encryption?: Encryption;

  /**
   * Body param: (Optional) An API key for the organization containing the source
   * namespace
   */
  source_api_key?: string;

  /**
   * Body param: (Optional) The region of the source namespace.
   */
  source_region?: string;
}

export interface NamespaceDeleteAllParams {
  /**
   * The name of the namespace.
   */
  namespace?: string;
}

export interface NamespaceExplainQueryParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: Aggregations to compute over all documents in the namespace that
   * match the filters.
   */
  aggregate_by?: Record<string, AggregateBy>;

  /**
   * Body param: The consistency level for a query.
   */
  consistency?: NamespaceExplainQueryParams.Consistency;

  /**
   * Body param: A function used to calculate vector similarity.
   */
  distance_metric?: DistanceMetric;

  /**
   * Body param: List of attribute names to exclude from the response. All other
   * attributes will be included in the response.
   */
  exclude_attributes?: Array<string>;

  /**
   * Body param: Exact filters for attributes to refine search results for. Think of
   * it as a SQL WHERE clause.
   */
  filters?: Filter;

  /**
   * Body param: Groups documents by the specified attributes (the "group key")
   * before computing aggregates. Aggregates are computed separately for each group.
   */
  group_by?: Array<GroupBy>;

  /**
   * Body param: Whether to include attributes in the response.
   */
  include_attributes?: IncludeAttributes;

  /**
   * Body param: Limits the documents returned by a query.
   */
  limit?: number | Limit;

  /**
   * Body param: How to rank the documents in the namespace.
   */
  rank_by?: RankBy;

  /**
   * Body param: The number of results to return.
   */
  top_k?: number;

  /**
   * Body param: The encoding to use for vectors in the response.
   */
  vector_encoding?: VectorEncoding;
}

export namespace NamespaceExplainQueryParams {
  /**
   * The consistency level for a query.
   */
  export interface Consistency {
    /**
     * The query's consistency level.
     *
     * - `strong` - Strong consistency. Requires a round-trip to object storage to
     *   fetch the latest writes.
     * - `eventual` - Eventual consistency. Does not require a round-trip to object
     *   storage, but may not see the latest writes.
     */
    level?: 'strong' | 'eventual';
  }
}

export interface NamespaceHintCacheWarmParams {
  /**
   * The name of the namespace.
   */
  namespace?: string;
}

export interface NamespaceMetadataParams {
  /**
   * The name of the namespace.
   */
  namespace?: string;
}

export interface NamespaceMultiQueryParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param
   */
  queries: Array<NamespaceMultiQueryParams.Query>;

  /**
   * Body param: The consistency level for a query.
   */
  consistency?: NamespaceMultiQueryParams.Consistency;

  /**
   * Body param: How to combine the rows returned by each sub-query into a single
   * ranked list.
   */
  rerank_by?: RerankBy;

  /**
   * Body param: The encoding to use for vectors in the response.
   */
  vector_encoding?: VectorEncoding;
}

export namespace NamespaceMultiQueryParams {
  /**
   * Query, filter, full-text search and vector search documents.
   */
  export interface Query {
    /**
     * Aggregations to compute over all documents in the namespace that match the
     * filters.
     */
    aggregate_by?: Record<string, AggregateBy>;

    /**
     * A function used to calculate vector similarity.
     */
    distance_metric?: NamespacesAPI.DistanceMetric;

    /**
     * List of attribute names to exclude from the response. All other attributes will
     * be included in the response.
     */
    exclude_attributes?: Array<string>;

    /**
     * Exact filters for attributes to refine search results for. Think of it as a SQL
     * WHERE clause.
     */
    filters?: Filter;

    /**
     * Groups documents by the specified attributes (the "group key") before computing
     * aggregates. Aggregates are computed separately for each group.
     */
    group_by?: Array<GroupBy>;

    /**
     * Whether to include attributes in the response.
     */
    include_attributes?: NamespacesAPI.IncludeAttributes;

    /**
     * Limits the documents returned by a query.
     */
    limit?: number | NamespacesAPI.Limit;

    /**
     * How to rank the documents in the namespace.
     */
    rank_by?: RankBy;

    /**
     * The number of results to return.
     */
    top_k?: number;
  }

  /**
   * The consistency level for a query.
   */
  export interface Consistency {
    /**
     * The query's consistency level.
     *
     * - `strong` - Strong consistency. Requires a round-trip to object storage to
     *   fetch the latest writes.
     * - `eventual` - Eventual consistency. Does not require a round-trip to object
     *   storage, but may not see the latest writes.
     */
    level?: 'strong' | 'eventual';
  }
}

export interface NamespaceQueryParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: Aggregations to compute over all documents in the namespace that
   * match the filters.
   */
  aggregate_by?: Record<string, AggregateBy>;

  /**
   * Body param: The consistency level for a query.
   */
  consistency?: NamespaceQueryParams.Consistency;

  /**
   * Body param: A function used to calculate vector similarity.
   */
  distance_metric?: DistanceMetric;

  /**
   * Body param: List of attribute names to exclude from the response. All other
   * attributes will be included in the response.
   */
  exclude_attributes?: Array<string>;

  /**
   * Body param: Exact filters for attributes to refine search results for. Think of
   * it as a SQL WHERE clause.
   */
  filters?: Filter;

  /**
   * Body param: Groups documents by the specified attributes (the "group key")
   * before computing aggregates. Aggregates are computed separately for each group.
   */
  group_by?: Array<GroupBy>;

  /**
   * Body param: Whether to include attributes in the response.
   */
  include_attributes?: IncludeAttributes;

  /**
   * Body param: Limits the documents returned by a query.
   */
  limit?: number | Limit;

  /**
   * Body param: How to rank the documents in the namespace.
   */
  rank_by?: RankBy;

  /**
   * Body param: The number of results to return.
   */
  top_k?: number;

  /**
   * Body param: The encoding to use for vectors in the response.
   */
  vector_encoding?: VectorEncoding;
}

export namespace NamespaceQueryParams {
  /**
   * The consistency level for a query.
   */
  export interface Consistency {
    /**
     * The query's consistency level.
     *
     * - `strong` - Strong consistency. Requires a round-trip to object storage to
     *   fetch the latest writes.
     * - `eventual` - Eventual consistency. Does not require a round-trip to object
     *   storage, but may not see the latest writes.
     */
    level?: 'strong' | 'eventual';
  }
}

export interface NamespaceRecallParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: Filter by attributes. Same syntax as the query endpoint.
   */
  filters?: unknown;

  /**
   * Body param: Include ground truth data (query vectors and true nearest neighbors)
   * in the response.
   */
  include_ground_truth?: boolean;

  /**
   * Body param: The number of searches to run.
   */
  num?: number;

  /**
   * Body param: The ranking function to evaluate recall for. If provided, `num` must
   * be either null or 1.
   */
  rank_by?: unknown;

  /**
   * Body param: Search for `top_k` nearest neighbors.
   */
  top_k?: number;
}

export interface NamespaceSchemaParams {
  /**
   * The name of the namespace.
   */
  namespace?: string;
}

export interface NamespaceUpdateMetadataParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: Configuration for namespace pinning.
   *
   * - Missing field: no change to pinning configuration
   * - `null` or `false`: explicitly remove pinning
   * - `true`: enable pinning with default configuration
   * - Object: set pinning configuration
   */
  pinning?: boolean | PinningConfig | null;
}

export interface NamespaceUpdateSchemaParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: The desired schema for the namespace.
   */
  schema?: { [key: string]: AttributeSchema };
}

export interface NamespaceWriteParams {
  /**
   * Path param: The name of the namespace.
   */
  namespace?: string;

  /**
   * Body param: The namespace to create an instant, copy-on-write clone of.
   */
  branch_from_namespace?: BranchFromNamespaceParams;

  /**
   * Body param: The namespace to copy documents from.
   */
  copy_from_namespace?: CopyFromNamespaceParams;

  /**
   * Body param: The filter specifying which documents to delete.
   */
  delete_by_filter?: Filter;

  /**
   * Body param: Allow partial completion when filter matches too many documents.
   */
  delete_by_filter_allow_partial?: boolean;

  /**
   * Body param: A condition evaluated against the current value of each document
   * targeted by a delete write. Only documents that pass the condition are deleted.
   */
  delete_condition?: Filter;

  /**
   * Body param
   */
  deletes?: Array<ID>;

  /**
   * Body param: Disables write throttling (HTTP 429 responses) during high-volume
   * ingestion.
   */
  disable_backpressure?: boolean;

  /**
   * Body param: A function used to calculate vector similarity.
   */
  distance_metric?: DistanceMetric;

  /**
   * Body param: The encryption configuration for a namespace.
   */
  encryption?: Encryption;

  /**
   * Body param: The patch and filter specifying which documents to patch.
   */
  patch_by_filter?: NamespaceWriteParams.PatchByFilter;

  /**
   * Body param: Allow partial completion when filter matches too many documents.
   */
  patch_by_filter_allow_partial?: boolean;

  /**
   * Body param: A list of documents in columnar format. Each key is a column name,
   * mapped to an array of values for that column.
   */
  patch_columns?: Columns;

  /**
   * Body param: A condition evaluated against the current value of each document
   * targeted by a patch write. Only documents that pass the condition are patched.
   */
  patch_condition?: Filter;

  /**
   * Body param
   */
  patch_rows?: Array<Row>;

  /**
   * Body param: If true, return the IDs of affected rows (deleted, patched,
   * upserted) in the response. For filtered and conditional writes, only IDs for
   * writes that succeeded will be included.
   */
  return_affected_ids?: boolean;

  /**
   * Body param: The schema of the attributes attached to the documents.
   */
  schema?: { [key: string]: AttributeSchema };

  /**
   * Body param: Configuration for namespace sharding, which partitions a namespace's
   * documents across multiple internal shards to scale indexing and query throughput
   * beyond a single machine. Sharding can only be configured on a namespace's
   * inaugural write, and cannot be added to or changed on an existing namespace.
   */
  sharding?: ShardingConfig;

  /**
   * Body param: A list of documents in columnar format. Each key is a column name,
   * mapped to an array of values for that column.
   */
  upsert_columns?: Columns;

  /**
   * Body param: A condition evaluated against the current value of each document
   * targeted by an upsert write. Only documents that pass the condition are
   * upserted.
   */
  upsert_condition?: Filter;

  /**
   * Body param
   */
  upsert_rows?: Array<Row>;
}

export namespace NamespaceWriteParams {
  /**
   * The patch and filter specifying which documents to patch.
   */
  export interface PatchByFilter {
    /**
     * Filter by attributes. Same syntax as the query endpoint.
     */
    filters: Filter;

    patch: { [key: string]: unknown };
  }
}

export declare namespace Namespaces {
  export {
    type AggregationGroup as AggregationGroup,
    type AttributeEmbed as AttributeEmbed,
    type AttributeEmbedConfig as AttributeEmbedConfig,
    type AttributeSchema as AttributeSchema,
    type AttributeSchemaConfig as AttributeSchemaConfig,
    type AttributeType as AttributeType,
    type Bm25ClauseParams as Bm25ClauseParams,
    type BranchFromNamespaceParams as BranchFromNamespaceParams,
    type Columns as Columns,
    type ContainsAllTokensFilterParams as ContainsAllTokensFilterParams,
    type ContainsAnyTokenFilterParams as ContainsAnyTokenFilterParams,
    type CopyFromNamespaceParams as CopyFromNamespaceParams,
    type DecayParams as DecayParams,
    type DistanceMetric as DistanceMetric,
    type EmbedParams as EmbedParams,
    type Encryption as Encryption,
    type FullTextSearch as FullTextSearch,
    type FullTextSearchConfig as FullTextSearchConfig,
    type FuzzyMaxEditDistance as FuzzyMaxEditDistance,
    type FuzzyParams as FuzzyParams,
    type ID as ID,
    type IncludeAttributes as IncludeAttributes,
    type Language as Language,
    type Limit as Limit,
    type NamespaceMetadata as NamespaceMetadata,
    type NamespaceMetadataPatch as NamespaceMetadataPatch,
    type PinningConfig as PinningConfig,
    type QueryBilling as QueryBilling,
    type QueryPerformance as QueryPerformance,
    type Row as Row,
    type RrfParams as RrfParams,
    type SaturateParams as SaturateParams,
    type ShardingConfig as ShardingConfig,
    type SparseDistanceMetric as SparseDistanceMetric,
    type Tokenizer as Tokenizer,
    type Vector as Vector,
    type VectorEncoding as VectorEncoding,
    type WriteBilling as WriteBilling,
    type WritePerformance as WritePerformance,
    type NamespaceBranchFromResponse as NamespaceBranchFromResponse,
    type NamespaceCopyFromResponse as NamespaceCopyFromResponse,
    type NamespaceDeleteAllResponse as NamespaceDeleteAllResponse,
    type NamespaceExplainQueryResponse as NamespaceExplainQueryResponse,
    type NamespaceHintCacheWarmResponse as NamespaceHintCacheWarmResponse,
    type NamespaceMultiQueryResponse as NamespaceMultiQueryResponse,
    type NamespaceQueryResponse as NamespaceQueryResponse,
    type NamespaceRecallResponse as NamespaceRecallResponse,
    type NamespaceSchemaResponse as NamespaceSchemaResponse,
    type NamespaceUpdateSchemaResponse as NamespaceUpdateSchemaResponse,
    type NamespaceWriteResponse as NamespaceWriteResponse,
    type NamespaceBranchFromParams as NamespaceBranchFromParams,
    type NamespaceCopyFromParams as NamespaceCopyFromParams,
    type NamespaceDeleteAllParams as NamespaceDeleteAllParams,
    type NamespaceExplainQueryParams as NamespaceExplainQueryParams,
    type NamespaceHintCacheWarmParams as NamespaceHintCacheWarmParams,
    type NamespaceMetadataParams as NamespaceMetadataParams,
    type NamespaceMultiQueryParams as NamespaceMultiQueryParams,
    type NamespaceQueryParams as NamespaceQueryParams,
    type NamespaceRecallParams as NamespaceRecallParams,
    type NamespaceSchemaParams as NamespaceSchemaParams,
    type NamespaceUpdateMetadataParams as NamespaceUpdateMetadataParams,
    type NamespaceUpdateSchemaParams as NamespaceUpdateSchemaParams,
    type NamespaceWriteParams as NamespaceWriteParams,
  };
}