Default shard

A distribution can have a default shard that acts as a catch-all fallback. When the router matches a query to a distribution with a default shard, it is guaranteed to find a route — even if the sharding key doesn’t fall within any explicitly defined key range.

The default shard is implemented as a special key range with the minimum possible value as its lower bound. This key range has a reserved ID: {DistributionId}.DEFAULT.

For example, if the distribution has column types [varchar, integer, uuid], the default key range lower bound is ["", -9223372036854775808, "00000000-0000-0000-0000-000000000000"].

How to Use It

Given a distribution with key range kr1 starting “From 0”, you can add a default shard:

ALTER DISTRIBUTION testWithDefault ADD DEFAULT SHARD sh2; -- Add default shard
        create default shard        
------------------------------------
 distribution id -> testWithDefault
 shard id        -> sh2
(2 rows)

SHOW key_ranges; -- Let's see the key ranges now
      key_range_id       | shard_id | distribution_id |     lower_bound      | locked
-------------------------+----------+-----------------+----------------------+--------
 kr18b713215             | sh1      | ds1             | 0                    | true
 testWithDefault.DEFAULT | sh2      | testWithDefault | -9223372036854775808 | false
(2 rows)

How It Works

The default shard is implemented as a special key range with ID {distribution_id}.DEFAULT that covers the minimum possible value for your column types:

Column Type	Default Lower Bound
integer	-9223372036854775808 (MinInt64)
uinteger	0
varchar	"" (empty string)
varchar hash	0
uuid	"00000000-0000-0000-0000-000000000000"

uuid column type does not support default shard. See issue #1666.

Routing Example

-- Setup: key ranges kr1: [-20, -10) → sh2, kr2: [-10, 0) → sh3, kr3: [0, ∞) → sh4
-- Default shard: sh1 (covers MinInt64 to -20)

INSERT INTO t(id) VALUES (-30);  -- → sh1 (default, below all explicit ranges)
INSERT INTO t(id) VALUES (-20);  -- → sh2 (kr1)
INSERT INTO t(id) VALUES (-10);  -- → sh3 (kr2)
INSERT INTO t(id) VALUES (0);    -- → sh4 (kr3)

Configuration

Set a default shard during distribution creation:

CREATE DISTRIBUTION ds1 COLUMN TYPES integer DEFAULT SHARD sh1;

Or add it to an existing distribution:

ALTER DISTRIBUTION ds1 ADD DEFAULT SHARD sh1;

Remove the default shard:

ALTER DISTRIBUTION ds1 DROP DEFAULT SHARD;