Cluster Operations

/**
 * Get cluster health information
 * @param params - Health check parameters
 * @returns Promise with cluster health status
 */
function health(params?: {
  /** Target indices for health check */
  index?: Indices;
  /** Detail level: cluster, indices, or shards */
  level?: Level;
  /** Wait for specific status */
  wait_for_status?: HealthStatus;
  /** Wait for active shards */
  wait_for_active_shards?: WaitForActiveShards;
  /** Wait for nodes count */
  wait_for_nodes?: string;
  /** Request timeout */
  timeout?: Duration;
  /** Master node timeout */
  master_timeout?: Duration;
  /** Local operation */
  local?: boolean;
  /** Wait for no relocating shards */
  wait_for_no_relocating_shards?: boolean;
  /** Wait for no initializing shards */
  wait_for_no_initializing_shards?: boolean;
  /** Wait for events priority */
  wait_for_events?: WaitForEvents;
}): Promise<TransportResult<ClusterHealthResponse, unknown>>;

interface ClusterHealthResponse {
  cluster_name: string;
  status: HealthStatus;
  timed_out: boolean;
  number_of_nodes: number;
  number_of_data_nodes: number;
  active_primary_shards: number;
  active_shards: number;
  relocating_shards: number;
  initializing_shards: number;
  unassigned_shards: number;
  delayed_unassigned_shards: number;
  number_of_pending_tasks: number;
  number_of_in_flight_fetch: number;
  task_max_waiting_in_queue_millis: number;
  active_shards_percent_as_number: number;
  indices?: Record<IndexName, ClusterIndicesHealth>;
}

type HealthStatus = 'green' | 'yellow' | 'red';
type Level = 'cluster' | 'indices' | 'shards';
type WaitForEvents = 'immediate' | 'urgent' | 'high' | 'normal' | 'low' | 'languid';

// Basic cluster health check
const health = await client.cluster.health();
console.log(`Cluster status: ${health.body.status}`);
console.log(`Active shards: ${health.body.active_shards}`);

// Wait for yellow status
const health = await client.cluster.health({
  wait_for_status: 'yellow',
  timeout: '30s'
});

// Health check for specific indices
const health = await client.cluster.health({
  index: ['important-index-*'],
  level: 'indices'
});

/**
 * Get cluster statistics
 * @param params - Statistics parameters
 * @returns Promise with cluster statistics
 */
function stats(params?: {
  /** Node IDs to include */
  node_id?: NodeIds;
  /** Flat settings format */
  flat_settings?: boolean;
  /** Request timeout */
  timeout?: Duration;
}): Promise<TransportResult<ClusterStatsResponse, unknown>>;

interface ClusterStatsResponse {
  timestamp: number;
  cluster_name: string;
  cluster_uuid: string;
  status: HealthStatus;
  indices: ClusterIndicesStats;
  nodes: ClusterNodesStats;
}

interface ClusterIndicesStats {
  count: number;
  shards: ClusterIndicesShards;
  docs: ClusterIndicesDocs;
  store: ClusterIndicesStore;
  fielddata: ClusterIndicesFielddata;
  query_cache: ClusterIndicesQueryCache;
  completion: ClusterIndicesCompletion;
  segments: ClusterIndicesSegments;
  mappings: ClusterIndicesMappings;
  analysis: ClusterIndicesAnalysis;
}

// Get full cluster statistics
const stats = await client.cluster.stats();
console.log(`Total indices: ${stats.body.indices.count}`);
console.log(`Total documents: ${stats.body.indices.docs.count}`);
console.log(`Storage size: ${stats.body.indices.store.size_in_bytes} bytes`);

// Get stats for specific nodes
const stats = await client.cluster.stats({
  node_id: ['node1', 'node2']
});

/**
 * Update cluster settings
 * @param params - Settings update parameters
 * @returns Promise with settings update result
 */
function putSettings(params: {
  /** Persistent settings (survive cluster restart) */
  persistent?: Record<string, any>;
  /** Transient settings (reset on cluster restart) */
  transient?: Record<string, any>;
  /** Flat settings format */
  flat_settings?: boolean;
  /** Master node timeout */
  master_timeout?: Duration;
  /** Request timeout */
  timeout?: Duration;
}): Promise<TransportResult<ClusterPutSettingsResponse, unknown>>;

/**
 * Get cluster settings
 * @param params - Settings retrieval parameters
 * @returns Promise with current cluster settings
 */
function getSettings(params?: {
  /** Flat settings format */
  flat_settings?: boolean;
  /** Include default settings */
  include_defaults?: boolean;
  /** Master node timeout */
  master_timeout?: Duration;
  /** Request timeout */
  timeout?: Duration;
}): Promise<TransportResult<ClusterGetSettingsResponse, unknown>>;

interface ClusterPutSettingsResponse {
  acknowledged: boolean;
  persistent: Record<string, any>;
  transient: Record<string, any>;
}

// Update cluster settings
await client.cluster.putSettings({
  persistent: {
    "indices.recovery.max_bytes_per_sec": "50mb",
    "cluster.routing.allocation.disk.watermark.low": "85%",
    "cluster.routing.allocation.disk.watermark.high": "90%"
  },
  transient: {
    "logger.org.elasticsearch.discovery": "DEBUG"
  }
});

// Get current settings
const settings = await client.cluster.getSettings({
  include_defaults: true,
  flat_settings: true
});

/**
 * Get cluster state information
 * @param params - State retrieval parameters
 * @returns Promise with cluster state
 */
function state(params?: {
  /** State metrics to include */
  metric?: Metrics;
  /** Target indices */
  index?: Indices;
  /** Allow no indices */
  allow_no_indices?: boolean;
  /** Expand wildcards */
  expand_wildcards?: ExpandWildcards;
  /** Flat settings format */
  flat_settings?: boolean;
  /** Ignore unavailable indices */
  ignore_unavailable?: boolean;
  /** Local operation */
  local?: boolean;
  /** Master node timeout */
  master_timeout?: Duration;
  /** Wait for metadata version */
  wait_for_metadata_version?: VersionNumber;
  /** Wait for timeout */
  wait_for_timeout?: Duration;
}): Promise<TransportResult<ClusterStateResponse, unknown>>;

type Metrics = '_all' | 'blocks' | 'metadata' | 'nodes' | 'routing_table' | 'routing_nodes' | 'master_node' | 'version';

interface ClusterStateResponse {
  cluster_name: string;
  cluster_uuid: string;
  version: number;
  state_uuid: string;
  master_node?: string;
  blocks?: ClusterBlocks;
  nodes?: Record<string, ClusterStateNode>;
  metadata?: ClusterStateMetadata;
  routing_table?: ClusterStateRoutingTable;
  routing_nodes?: ClusterStateRoutingNodes;
}

// Get basic cluster state
const state = await client.cluster.state({
  metric: ['master_node', 'nodes']
});

// Get routing information for specific indices
const state = await client.cluster.state({
  metric: ['routing_table'],
  index: ['my-index-*']
});

/**
 * Explain shard allocation decisions
 * @param params - Allocation explanation parameters
 * @returns Promise with allocation explanation
 */
function allocationExplain(params?: {
  /** Current shard allocation to explain */
  current_node?: string;
  /** Index name */
  index?: IndexName;
  /** Primary shard flag */
  primary?: boolean;
  /** Shard number */
  shard?: number;
  /** Include disk information */
  include_disk_info?: boolean;
  /** Include cluster-wide allocation decisions */
  include_yes_decisions?: boolean;
}): Promise<TransportResult<ClusterAllocationExplainResponse, unknown>>;

interface ClusterAllocationExplainResponse {
  index: IndexName;
  shard: number;
  primary: boolean;
  current_state: string;
  current_node?: ClusterAllocationExplainCurrentNode;
  unassigned_info?: ClusterAllocationExplainUnassignedInformation;
  can_allocate?: Decision;
  can_remain_on_current_node?: Decision;
  can_rebalance_cluster?: Decision;
  can_rebalance_to_other_node?: Decision;
  rebalance_explanation?: string;
  node_allocation_decisions?: ClusterAllocationExplainNodeAllocationDecision[];
}

type Decision = 'yes' | 'no' | 'worse_balance' | 'throttled' | 'awaiting_info' | 'allocation_delayed' | 'no_valid_shard_copy' | 'no_attempt';

// Explain why a shard is unassigned
const explanation = await client.cluster.allocationExplain({
  index: "my-index",
  shard: 0,
  primary: true,
  include_disk_info: true
});

console.log("Allocation decision:", explanation.body.can_allocate);

/**
 * Manually reroute shards
 * @param params - Rerouting parameters
 * @returns Promise with rerouting result
 */
function reroute(params?: {
  /** Rerouting commands */
  commands?: ClusterRerouteCommand[];
  /** Dry run mode */
  dry_run?: boolean;
  /** Explain decisions */
  explain?: boolean;
  /** Master node timeout */
  master_timeout?: Duration;
  /** Metric to return */
  metric?: Metrics;
  /** Retry failed allocations */
  retry_failed?: boolean;
  /** Request timeout */
  timeout?: Duration;
}): Promise<TransportResult<ClusterRerouteResponse, unknown>>;

interface ClusterRerouteCommand {
  /** Move shard command */
  move?: ClusterRerouteCommandMoveAction;
  /** Cancel allocation command */
  cancel?: ClusterRerouteCommandCancelAction;
  /** Allocate empty primary command */
  allocate_empty_primary?: ClusterRerouteCommandAllocateAction;
  /** Allocate stale primary command */
  allocate_stale_primary?: ClusterRerouteCommandAllocateAction;
  /** Allocate replica command */
  allocate_replica?: ClusterRerouteCommandAllocateAction;
}

// Move a shard to a different node
await client.cluster.reroute({
  commands: [
    {
      move: {
        index: "my-index",
        shard: 0,
        from_node: "node-1",
        to_node: "node-2"
      }
    }
  ]
});

// Retry failed allocations
await client.cluster.reroute({
  retry_failed: true
});

/**
 * Get pending cluster tasks
 * @param params - Pending tasks parameters
 * @returns Promise with pending tasks information
 */
function pendingTasks(params?: {
  /** Local operation */
  local?: boolean;
  /** Master node timeout */
  master_timeout?: Duration;
}): Promise<TransportResult<ClusterPendingTasksResponse, unknown>>;

interface ClusterPendingTasksResponse {
  tasks: ClusterStateTask[];
}

interface ClusterStateTask {
  insert_order: number;
  priority: string;
  source: string;
  executing: boolean;
  time_in_queue: string;
  time_in_queue_millis: number;
}

// Get pending tasks
const tasks = await client.cluster.pendingTasks();
console.log(`${tasks.body.tasks.length} pending tasks`);

tasks.body.tasks.forEach(task => {
  console.log(`Task: ${task.source}, waiting ${task.time_in_queue}`);
});

type Indices = string | string[];
type IndexName = string;
type NodeIds = string | string[];
type Duration = string;
type VersionNumber = number;
type WaitForActiveShards = number | 'all';
type ExpandWildcards = 'all' | 'open' | 'closed' | 'hidden' | 'none';

interface ClusterIndicesHealth {
  status: HealthStatus;
  number_of_shards: number;
  number_of_replicas: number;
  active_primary_shards: number;
  active_shards: number;
  relocating_shards: number;
  initializing_shards: number;
  unassigned_shards: number;
}

interface ClusterNodesStats {
  count: ClusterNodesCounts;
  versions: string[];
  os: ClusterOperatingSystemStats;
  process: ClusterProcessStats;
  jvm: ClusterJvmStats;
  fs: ClusterFileSystemStats;
  plugins: PluginStats[];
  network_types: ClusterNetworkTypes;
}