REBALANCE_SHARDS

Rebalances shard assignments in a subcluster or across the entire cluster in Eon Mode. If the current session ends, the operation immediately aborts. The amount of time required to rebalance shards scales in a roughly linear fashion based on the number of objects in your database.

Run REBALANCE_SHARDS after you modify your cluster using ALTER NODE or when you add nodes to a subcluster.

Vertica automatically rebalances shards in a subcluster when you remove a node. You do not need to run REBALANCE_SHARDS manually in this case.

After you rebalance shards, you will no longer be able to restore objects from a backup taken before the rebalancing. (Full backups are always possible.) After you rebalance, make another full backup so you will be able to restore objects from it in the future.

Syntax

REBALANCE_SHARDS(['subcluster-name'])

Parameters

subcluster‑name The name of the subcluster where shards will be rebalanced. If you do not supply this parameter, all subclusters in the database rebalance their shards.

Privileges

Superuser

Examples

The following shows that the nodes in the in the newly-added analytics subcluster do not yet have shard subscriptions. It then calls REBALANCE_SHARDS to update the node's subscriptions:

=> SELECT subcluster_name, n.node_name, shard_name, subscription_state FROM 
   v_catalog.nodes n LEFT JOIN v_catalog.node_subscriptions ns ON (n.node_name 
   = ns.node_name) ORDER BY 1,2,3;
				
   subcluster_name    |      node_name       | shard_name  | subscription_state 
----------------------+----------------------+-------------+--------------------
 analytics_subcluster | v_verticadb_node0004 |             | 
 analytics_subcluster | v_verticadb_node0005 |             | 
 analytics_subcluster | v_verticadb_node0006 |             | 
 default_subcluster   | v_verticadb_node0001 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0001 | segment0001 | ACTIVE
 default_subcluster   | v_verticadb_node0001 | segment0003 | ACTIVE
 default_subcluster   | v_verticadb_node0002 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0002 | segment0001 | ACTIVE
 default_subcluster   | v_verticadb_node0002 | segment0002 | ACTIVE
 default_subcluster   | v_verticadb_node0003 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0003 | segment0002 | ACTIVE
 default_subcluster   | v_verticadb_node0003 | segment0003 | ACTIVE
(12 rows)
=> SELECT REBALANCE_SHARDS('analytics_subcluster');
 REBALANCE_SHARDS  
-------------------
 REBALANCED SHARDS
(1 row)

=> SELECT subcluster_name, n.node_name, shard_name, subscription_state FROM 
   v_catalog.nodes n LEFT JOIN v_catalog.node_subscriptions ns ON (n.node_name 
   = ns.node_name) ORDER BY 1,2,3;
				
   subcluster_name    |      node_name       | shard_name  | subscription_state 
----------------------+----------------------+-------------+--------------------
 analytics_subcluster | v_verticadb_node0004 | replica     | PASSIVE
 analytics_subcluster | v_verticadb_node0004 | segment0001 | PASSIVE
 analytics_subcluster | v_verticadb_node0004 | segment0003 | PASSIVE
 analytics_subcluster | v_verticadb_node0005 | replica     | PASSIVE
 analytics_subcluster | v_verticadb_node0005 | segment0001 | PASSIVE
 analytics_subcluster | v_verticadb_node0005 | segment0002 | PASSIVE
 analytics_subcluster | v_verticadb_node0006 | replica     | PASSIVE
 analytics_subcluster | v_verticadb_node0006 | segment0002 | PASSIVE
 analytics_subcluster | v_verticadb_node0006 | segment0003 | PASSIVE
 default_subcluster   | v_verticadb_node0001 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0001 | segment0001 | ACTIVE
 default_subcluster   | v_verticadb_node0001 | segment0003 | ACTIVE
 default_subcluster   | v_verticadb_node0002 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0002 | segment0001 | ACTIVE
 default_subcluster   | v_verticadb_node0002 | segment0002 | ACTIVE
 default_subcluster   | v_verticadb_node0003 | replica     | ACTIVE
 default_subcluster   | v_verticadb_node0003 | segment0002 | ACTIVE
 default_subcluster   | v_verticadb_node0003 | segment0003 | ACTIVE
(18 rows)

In the previous example, the state of the subscription for the new nodes is PASSIVE. This state means they are warming their depots to prepare for queries. This state eventually becomes ACTIVE, when the nodes have filled their depot with recently-used data. The amount of time this process takes depends on the size of the depot and how frequently data is being evicted from the depot.

See Also