Behaviour of "SHOW RANGE FROM TABLE ... FOR ROW" needs clarification

[smcvey]

The SHOW RANGE FROM TABLE ... FOR ROW command is unique amongst all the SHOW RANGE[S] commands. It does not care whether or not the row actually exists, as it simply is calling on the algorithm that takes in a key and returns where the key WOULD be stored IF it existed.

This can cause confusion for users attempting to verify where their data is domiciled. Assume a simple REGIONAL BY ROW table like this:

  CREATE TABLE public.t (
      id UUID NOT NULL,
      crdb_region public.crdb_internal_region NOT VISIBLE NOT NULL DEFAULT default_to_database_primary_region(gateway_region())::public.crdb_internal_region,
      CONSTRAINT t_pkey PRIMARY KEY (id ASC)
  ) LOCALITY REGIONAL BY ROW;

If a user runs these two commands...

SHOW RANGE FROM TABLE <table> FOR ROW ('<region A>', '<UUID>');
SHOW RANGE FROM TABLE <table> FOR ROW ('<region B>', '<UUID>');

then two different ranges would be returned, one for each region - despite the fact the UUID (which has a unique constraint) can only ever possibly exist in one range at most.

The output of the commands makes it seem like the row is physically being stored in two different regions, when that's not the case.

The behaviour of the command is intended, so we need the documentation just to add some clarification.

Jira issue: DOC-14750