Package org.opensearch.cluster.routing

Class RoutingNodes

java.lang.Object
org.opensearch.cluster.routing.RoutingNodes
All Implemented Interfaces:
Iterable<RoutingNode>
@PublicApi(since="1.0.0") public class RoutingNodes extends Object implements Iterable<RoutingNode>
RoutingNodes represents a copy the routing information contained in the cluster state. It can be either initialized as mutable or immutable (see RoutingNodes(ClusterState, boolean)), allowing or disallowing changes to its elements.

The main methods used to update routing entries are:

Opensearch.api:

  • Constructor Details

    • RoutingNodes

      public RoutingNodes(ClusterState clusterState)

    • RoutingNodes

      public RoutingNodes(ClusterState clusterState, boolean readOnly)

  • Method Details

    • getIncomingRecoveries

      public int getIncomingRecoveries(String nodeId)

    • getInitialPrimariesIncomingRecoveries

      public int getInitialPrimariesIncomingRecoveries(String nodeId)

    • getOutgoingRecoveries

      public int getOutgoingRecoveries(String nodeId)

    • getInitialIncomingRecoveries

      public int getInitialIncomingRecoveries(String nodeId)
      Recoveries started on node as a result of new index creation.

    • getInitialOutgoingRecoveries

      public int getInitialOutgoingRecoveries(String nodeId)
      Recoveries started from node as a result of new index creation.

    • iterator

      public Iterator<RoutingNode> iterator()
      Specified by:
      iterator in interface Iterable<RoutingNode>

    • mutableIterator

      public Iterator<RoutingNode> mutableIterator()

    • unassigned

      public RoutingNodes.UnassignedShards unassigned()

    • node

      public RoutingNode node(String nodeId)

    • stream

      public Stream<RoutingNode> stream()

    • nodesPerAttributesCounts

      public Set<String> nodesPerAttributesCounts(String attributeName)

    • hasUnassignedPrimaries

      public boolean hasUnassignedPrimaries()
      Returns true iff this RoutingNodes instance has any unassigned primaries even if the primaries are marked as temporarily ignored.

    • hasUnassignedShards

      public boolean hasUnassignedShards()
      Returns true iff this RoutingNodes instance has any unassigned shards even if the shards are marked as temporarily ignored.
      See Also:

    • hasInactivePrimaries

      public boolean hasInactivePrimaries()

    • hasInactiveShards

      public boolean hasInactiveShards()

    • getRelocatingShardCount

      public int getRelocatingShardCount()

    • assignedShards

      public List<ShardRouting> assignedShards(org.opensearch.core.index.shard.ShardId shardId)
      Returns all shards that are not in the state UNASSIGNED with the same shard ID as the given shard.

    • getByAllocationId

      @Nullable public ShardRouting getByAllocationId(org.opensearch.core.index.shard.ShardId shardId, String allocationId)

    • activePrimary

      public ShardRouting activePrimary(org.opensearch.core.index.shard.ShardId shardId)
      Returns the active primary shard for the given shard id or null if no primary is found or the primary is not active.

    • activeReplicaWithHighestVersion

      public ShardRouting activeReplicaWithHighestVersion(org.opensearch.core.index.shard.ShardId shardId)
      Returns one active replica shard for the given shard id or null if no active replica is found.

      Since replicas could possibly be on nodes with an older version of OpenSearch than the primary is, this will return replicas on the highest version of OpenSearch when document replication is enabled.

    • activeReplicaWithOldestVersion

      public ShardRouting activeReplicaWithOldestVersion(org.opensearch.core.index.shard.ShardId shardId)
      Returns one active replica shard for the given shard id or null if no active replica is found.

      Since replicas could possibly be on nodes with a higher version of OpenSearch than the primary is, this will return replicas on the oldest version of OpenSearch when segment replication is enabled to allow for replica to read segments from primary.

    • activeReplicaOnRemoteNode

      public ShardRouting activeReplicaOnRemoteNode(org.opensearch.core.index.shard.ShardId shardId)
      Returns one active replica shard on a remote node for the given shard id or null if no such replica is found.

      Since we aim to continue moving forward during remote store migration, replicas already migrated to remote nodes are preferred for primary promotion

    • allReplicasActive

      public boolean allReplicasActive(org.opensearch.core.index.shard.ShardId shardId, Metadata metadata)
      Returns true iff all replicas are active for the given shard routing. Otherwise false

    • shards

      public List<ShardRouting> shards(Predicate<ShardRouting> predicate)

    • shardsWithState

      public List<ShardRouting> shardsWithState(ShardRoutingState... state)

    • shardsWithState

      public List<ShardRouting> shardsWithState(String index, ShardRoutingState... state)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • initializeShard

      public ShardRouting initializeShard(ShardRouting unassignedShard, String nodeId, @Nullable String existingAllocationId, long expectedSize, RoutingChangesObserver routingChangesObserver)
      Moves a shard from unassigned to initialize state
      Parameters:
      existingAllocationId - allocation id to use. If null, a fresh allocation id is generated.
      Returns:
      the initialized shard

    • relocateShard

      public org.opensearch.common.collect.Tuple<ShardRouting,ShardRouting> relocateShard(ShardRouting startedShard, String nodeId, long expectedShardSize, RoutingChangesObserver changes)
      Relocate a shard to another node, adding the target initializing shard as well as assigning it.
      Returns:
      pair of source relocating and target initializing shards.

    • startShard

      public ShardRouting startShard(org.apache.logging.log4j.Logger logger, ShardRouting initializingShard, RoutingChangesObserver routingChangesObserver)
      Applies the relevant logic to start an initializing shard.

      Moves the initializing shard to started. If the shard is a relocation target, also removes the relocation source.

      If the started shard is a primary relocation target, this also reinitializes currently initializing replicas as their recovery source changes

      Returns:
      the started shard

    • failShard

      public void failShard(org.apache.logging.log4j.Logger logger, ShardRouting failedShard, UnassignedInfo unassignedInfo, IndexMetadata indexMetadata, RoutingChangesObserver routingChangesObserver)
      Applies the relevant logic to handle a cancelled or failed shard.

      Moves the shard to unassigned or completely removes the shard (if relocation target).

      - If shard is a primary, this also fails initializing replicas. - If shard is an active primary, this also promotes an active replica to primary (if such a replica exists). - If shard is a relocating primary, this also removes the primary relocation target shard. - If shard is a relocating replica, this promotes the replica relocation target to a full initializing replica, removing the relocation source information. This is possible as peer recovery is always done from the primary. - If shard is a (primary or replica) relocation target, this also clears the relocation information on the source shard.

    • size

      public int size()
      Returns the number of routing nodes

    • assertShardStats

      public static boolean assertShardStats(RoutingNodes routingNodes)
      Calculates RoutingNodes statistics by iterating over all ShardRoutings in the cluster to ensure the book-keeping is correct. For performance reasons, this should only be called from asserts
      Returns:
      this method always returns true or throws an assertion error. If assertion are not enabled this method does nothing.

    • nodeInterleavedShardIterator

      public Iterator<ShardRouting> nodeInterleavedShardIterator(ShardMovementStrategy shardMovementStrategy)
      Creates an iterator over shards interleaving between nodes: The iterator returns the first shard from the first node, then the first shard of the second node, etc. until one shard from each node has been returned. The iterator then resumes on the first node by returning the second shard and continues until all shards from all the nodes have been returned.
      Parameters:
      shardMovementStrategy - if ShardMovementStrategy.PRIMARY_FIRST, all primary shards are iterated over before iterating replica for any node if ShardMovementStrategy.REPLICA_FIRST, all replica shards are iterated over before iterating primary for any node if ShardMovementStrategy.NO_PREFERENCE, order of replica and primary shards doesn't matter in iteration
      Returns:
      iterator of shard routings