Search Operations

/**
 * Search for documents using query DSL
 * @param params - Search parameters with query, filters, aggregations
 * @returns Promise with search results including hits and aggregations
 */
function search<TDocument = unknown, TAggregations = Record<AggregateName, AggregationsAggregate>>(params: {
  /** Target indices (string, array, or pattern) */
  index?: Indices;
  /** Query definition using Elasticsearch Query DSL */
  query?: QueryDslQueryContainer;
  /** Aggregations to compute over matching documents */
  aggs?: Record<string, AggregationsAggregationContainer>;
  /** Sort order for results */
  sort?: SortCombinations[];
  /** Source field control */
  _source?: boolean | Fields;
  /** Exclude source fields */
  _source_excludes?: Fields;
  /** Include only specific source fields */
  _source_includes?: Fields;
  /** Starting offset for pagination */
  from?: number;
  /** Number of results to return */
  size?: number;
  /** Highlighting configuration */
  highlight?: SearchHighlight;
  /** Track total hits count */
  track_total_hits?: boolean | number;
  /** Minimum score threshold */
  min_score?: number;
  /** Post-filter for aggregations */
  post_filter?: QueryDslQueryContainer;
  /** Search timeout */
  timeout?: Duration;
  /** Query preference */
  preference?: string;
  /** Routing values */
  routing?: Routing;
  /** Search type */
  search_type?: SearchType;
  /** Request cache usage */
  request_cache?: boolean;
  /** Allow partial search results */
  allow_partial_search_results?: boolean;
  /** Scroll duration for pagination */
  scroll?: Duration;
  /** Stored fields to return */
  stored_fields?: Fields;
  /** Document value fields */
  docvalue_fields?: DocvalueField[];
  /** Explain scoring calculation */
  explain?: boolean;
  /** Script fields */
  script_fields?: Record<string, ScriptField>;
  /** Runtime mappings */
  runtime_mappings?: Record<string, RuntimeField>;
  /** Search profiling */
  profile?: boolean;
}): Promise<TransportResult<SearchResponse<TDocument, TAggregations>, unknown>>;

interface SearchResponse<TDocument = unknown, TAggregations = Record<AggregateName, AggregationsAggregate>> {
  took: number;
  timed_out: boolean;
  _shards: ShardStatistics;
  hits: SearchHitsMetadata<TDocument>;
  aggregations?: TAggregations;
  _scroll_id?: ScrollId;
  profile?: SearchProfile;
}

interface SearchHitsMetadata<TDocument = unknown> {
  total: SearchHitsTotal;
  max_score?: number;
  hits: SearchHit<TDocument>[];
}

interface SearchHit<TDocument = unknown> {
  _index: IndexName;
  _id: Id;
  _score?: number;
  _source?: TDocument;
  _type?: string;
  _routing?: Routing;
  highlight?: Record<string, string[]>;
  fields?: Record<string, any>;
  _explanation?: Explanation;
}

// Basic text search
const response = await client.search({
  index: "articles",
  query: {
    match: {
      title: "elasticsearch guide"
    }
  }
});

// Complex search with aggregations
const response = await client.search<Product>({
  index: "products",
  query: {
    bool: {
      must: [
        { match: { category: "electronics" } }
      ],
      filter: [
        { range: { price: { gte: 100, lte: 1000 } } }
      ]
    }
  },
  aggs: {
    price_histogram: {
      histogram: {
        field: "price",
        interval: 100
      }
    },
    brands: {
      terms: {
        field: "brand.keyword",
        size: 10
      }
    }
  },
  sort: [
    { price: "asc" },
    "_score"
  ],
  from: 0,
  size: 20
});

// Search with highlighting
const response = await client.search({
  index: "documents",
  query: {
    multi_match: {
      query: "elasticsearch tutorial",
      fields: ["title^2", "content"]
    }
  },
  highlight: {
    fields: {
      title: {},
      content: {
        fragment_size: 150,
        number_of_fragments: 3
      }
    }
  }
});

/**
 * Execute multiple search queries in a single request
 * @param params - Multi-search parameters
 * @returns Promise with array of search results
 */
function msearch<TDocument = unknown>(params: {
  /** Default index for searches without index specified */
  index?: Indices;
  /** Array of search request definitions */
  searches: MsearchMultisearchBody[];
  /** Maximum concurrent searches */
  max_concurrent_searches?: number;
  /** Search type */
  search_type?: SearchType;
  /** Rest total hits as integer */
  rest_total_hits_as_int?: boolean;
  /** Typed keys for aggregations */
  typed_keys?: boolean;
}): Promise<TransportResult<MsearchResponse<TDocument>, unknown>>;

interface MsearchMultisearchBody {
  /** Search header with index and options */
  header?: MsearchMultisearchHeader;
  /** Search body with query and parameters */
  body?: SearchRequest;
}

interface MsearchMultisearchHeader {
  index?: Indices;
  type?: string;
  preference?: string;
  routing?: Routing;
  allow_no_indices?: boolean;
  expand_wildcards?: ExpandWildcards;
  ignore_unavailable?: boolean;
}

interface MsearchResponse<TDocument = unknown> {
  took?: number;
  responses: Array<SearchResponse<TDocument> | ErrorCause>;
}

// Multiple searches in one request
const response = await client.msearch({
  searches: [
    // Search 1: Recent orders
    { header: { index: "orders" } },
    { 
      query: { range: { created_at: { gte: "now-1d" } } },
      size: 10
    },
    // Search 2: Popular products
    { header: { index: "products" } },
    {
      query: { match_all: {} },
      sort: [{ popularity_score: "desc" }],
      size: 5
    }
  ]
});

/**
 * Continue scrolling through search results
 * @param params - Scroll parameters
 * @returns Promise with next batch of results
 */
function scroll<TDocument = unknown>(params: {
  /** Scroll ID from previous search or scroll */
  scroll_id: ScrollId;
  /** Duration to keep scroll context alive */
  scroll?: Duration;
  /** Rest total hits as integer */
  rest_total_hits_as_int?: boolean;
}): Promise<TransportResult<ScrollResponse<TDocument>, unknown>>;

/**
 * Clear scroll contexts to free resources
 * @param params - Clear scroll parameters
 * @returns Promise with clear result
 */
function clearScroll(params: {
  /** Scroll IDs to clear */
  scroll_id: ScrollIds;
}): Promise<TransportResult<ClearScrollResponse, unknown>>;

interface ScrollResponse<TDocument = unknown> {
  _scroll_id?: ScrollId;
  took: number;
  timed_out: boolean;
  _shards: ShardStatistics;
  hits: SearchHitsMetadata<TDocument>;
}

type ScrollId = string;
type ScrollIds = string | string[];

// Start scroll search
let response = await client.search({
  index: "large-dataset",
  scroll: "1m",
  size: 1000,
  query: { match_all: {} }
});

// Continue scrolling
while (response.body.hits.hits.length > 0) {
  // Process current batch
  response.body.hits.hits.forEach(hit => {
    console.log(hit._source);
  });
  
  // Get next batch
  response = await client.scroll({
    scroll_id: response.body._scroll_id!,
    scroll: "1m"
  });
}

// Clear scroll when done
await client.clearScroll({
  scroll_id: response.body._scroll_id!
});

/**
 * Count documents matching a query
 * @param params - Count parameters
 * @returns Promise with count result
 */
function count(params?: {
  /** Target indices */
  index?: Indices;
  /** Query to count matches */
  query?: QueryDslQueryContainer;
  /** Default operator for query string query */
  default_operator?: DefaultOperator;
  /** Analyzer for query string */
  analyzer?: string;
  /** Minimum should match */
  minimum_should_match?: MinimumShouldMatch;
  /** Query preference */
  preference?: string;
  /** Routing values */
  routing?: Routing;
  /** Allow no indices */
  allow_no_indices?: boolean;
  /** Expand wildcards */
  expand_wildcards?: ExpandWildcards;
  /** Ignore unavailable indices */
  ignore_unavailable?: boolean;
  /** Terminate early with count threshold */
  terminate_after?: number;
}): Promise<TransportResult<CountResponse, unknown>>;

interface CountResponse {
  count: number;
  _shards: ShardStatistics;
}

// Count all documents
const count = await client.count({
  index: "products"
});

// Count with query
const activeUserCount = await client.count({
  index: "users",
  query: {
    term: { status: "active" }
  }
});

/**
 * Execute a search template
 * @param params - Search template parameters
 * @returns Promise with search results
 */
function searchTemplate<TDocument = unknown>(params: {
  /** Target indices */
  index?: Indices;
  /** Template ID */
  id?: Id;
  /** Inline template definition */
  source?: string;
  /** Template parameters */
  params?: Record<string, any>;
  /** Explain template rendering */
  explain?: boolean;
  /** Profile search execution */
  profile?: boolean;
  /** Template file */
  file?: string;
}): Promise<TransportResult<SearchTemplateResponse<TDocument>, unknown>>;

/**
 * Render a search template without executing
 * @param params - Render template parameters
 * @returns Promise with rendered template
 */
function renderSearchTemplate(params: {
  /** Template ID */
  id?: Id;
  /** Inline template source */
  source?: string;
  /** Template parameters */
  params?: Record<string, any>;
  /** Template file */
  file?: string;
}): Promise<TransportResult<RenderSearchTemplateResponse, unknown>>;

// Execute search template
const response = await client.searchTemplate({
  index: "products",
  source: {
    query: {
      match: {
        "{{field}}": "{{value}}"
      }
    },
    from: "{{from}}",
    size: "{{size}}"
  },
  params: {
    field: "category",
    value: "electronics",
    from: 0,
    size: 10
  }
});

/**
 * Get field capabilities across indices
 * @param params - Field capabilities parameters
 * @returns Promise with field information
 */
function fieldCaps(params?: {
  /** Target indices */
  index?: Indices;
  /** Fields to analyze */
  fields?: Fields;
  /** Include unmapped fields */
  include_unmapped?: boolean;
  /** Ignore unavailable indices */
  ignore_unavailable?: boolean;
  /** Allow no indices */
  allow_no_indices?: boolean;
  /** Expand wildcards */
  expand_wildcards?: ExpandWildcards;
}): Promise<TransportResult<FieldCapsResponse, unknown>>;

interface FieldCapsResponse {
  indices?: string[];
  fields: Record<string, Record<string, FieldCapsFieldCapability>>;
}

/**
 * Explain how a query matches a document
 * @param params - Explain parameters
 * @returns Promise with explanation
 */
function explain<TDocument = unknown>(params: {
  /** Target index */
  index: IndexName;
  /** Document ID */
  id: Id;
  /** Query to explain */
  query: QueryDslQueryContainer;
  /** Source field control */
  _source?: boolean | Fields;
  /** Routing value */
  routing?: Routing;
  /** Query preference */
  preference?: string;
  /** Analyzer for query string */
  analyzer?: string;
  /** Default operator */
  default_operator?: DefaultOperator;
}): Promise<TransportResult<ExplainResponse<TDocument>, unknown>>;

interface ExplainResponse<TDocument = unknown> {
  _index: IndexName;
  _id: Id;
  matched: boolean;
  explanation?: Explanation;
  get?: GetResponse<TDocument>;
}

interface Explanation {
  value: number;
  description: string;
  details?: Explanation[];
}

// Explain query match
const explanation = await client.explain({
  index: "articles",
  id: "article-123",
  query: {
    match: {
      title: "elasticsearch tutorial"
    }
  }
});

if (explanation.body.matched) {
  console.log("Score:", explanation.body.explanation?.value);
  console.log("Explanation:", explanation.body.explanation?.description);
}

/**
 * Perform k-nearest neighbor search
 * @param params - KNN search parameters
 * @returns Promise with nearest neighbor results
 */
function knnSearch<TDocument = unknown>(params: {
  /** Target indices */
  index: Indices;
  /** KNN configuration */
  knn: KnnQuery | KnnQuery[];
  /** Additional filter query */
  filter?: QueryDslQueryContainer[];
  /** Source field control */
  _source?: boolean | Fields;
  /** Stored fields */
  stored_fields?: Fields;
  /** Document value fields */
  docvalue_fields?: DocvalueField[];
  /** Routing values */
  routing?: Routing;
}): Promise<TransportResult<SearchResponse<TDocument>, unknown>>;

interface KnnQuery {
  /** Vector field name */
  field: string;
  /** Query vector */
  query_vector: number[];
  /** Number of nearest neighbors */
  k: number;
  /** Number of candidates */
  num_candidates?: number;
  /** Boost factor */
  boost?: number;
  /** Filter to apply before KNN search */
  filter?: QueryDslQueryContainer;
}

// Vector similarity search
const response = await client.knnSearch({
  index: "image-embeddings",
  knn: {
    field: "image_vector",
    query_vector: [0.1, 0.2, 0.3, /* ... 768 dimensions */],
    k: 10,
    num_candidates: 100
  }
});

type Indices = string | string[];
type Fields = string | string[];
type Duration = string;
type Routing = string;
type AggregateName = string;
type SearchType = 'dfs_query_then_fetch' | 'query_then_fetch';
type DefaultOperator = 'AND' | 'OR';
type MinimumShouldMatch = number | string;
type ExpandWildcards = 'all' | 'open' | 'closed' | 'hidden' | 'none';

interface QueryDslQueryContainer {
  match?: Record<string, QueryDslMatchQuery>;
  match_all?: QueryDslMatchAllQuery;
  term?: Record<string, QueryDslTermQuery>;
  terms?: Record<string, QueryDslTermsQuery>;
  range?: Record<string, QueryDslRangeQuery>;
  bool?: QueryDslBoolQuery;
  // ... many more query types
}

interface SearchHitsTotal {
  value: number;
  relation: 'eq' | 'gte';
}

interface ShardStatistics {
  total: number;
  successful: number;
  failed: number;
  skipped?: number;
}