Document get_shard_id_for_distribution_column (#296)

admin_guide/cluster_management.rst

@@ -145,3 +145,34 @@ The new shard(s) are created on the same node as the shard(s) from which the ten
     102240,
     'source_host', source_port,
     'dest_host', dest_port);
+
+Diagnostics
+###########
+
+.. _row_placements:
+
+Finding which shard contains data for a specific tenant
+-------------------------------------------------------
+
+The rows of a distributed table are grouped into shards, and each shard is placed on a worker node in the Citus cluster. In the multi-tenant Citus use case we can determine which worker node contains the rows for a specific tenant by putting together two pieces of information: the :ref:`shard id <get_shard_id>` associated with the tenant id, and the shard placements on workers. The two can be retrieved together in a single query. Suppose our multi-tenant application's tenants and are stores, and we want to find which worker node holds the data for Gap.com (id=4, suppose).
+
+To find the worker node holding the data for store id=4, ask for the placement of rows whose distribution column has value 4:
+
+.. code-block:: postgresql
+
+  SELECT *
+    FROM pg_dist_shard_placement
+   WHERE shardid = (
+     SELECT get_shard_id_for_distribution_column('stores', 4)
+   );
+
+The output contains the host and port of the worker database.
+
+::
+
+  ┌─────────┬────────────┬─────────────┬───────────┬──────────┬─────────────┐
+  │ shardid │ shardstate │ shardlength │ nodename  │ nodeport │ placementid │
+  ├─────────┼────────────┼─────────────┼───────────┼──────────┼─────────────┤
+  │  102009 │          1 │           0 │ localhost │     5433 │           2 │
+  └─────────┴────────────┴─────────────┴───────────┴──────────┴─────────────┘
+

faq/faq.rst

@@ -78,3 +78,8 @@ In which situations are uniqueness constraints supported on distributed tables?
 Citus is able to enforce a primary key or uniqueness constraint only when the constrained columns contain the distribution column. In particular this means that if a single column constitutes the primary key then it has to be the distribution column as well.
 
 This restriction allows Citus to localize a uniqueness check to a single shard and let PostgreSQL on the worker node do the check efficiently.
+
+Which shard contains data for a particular tenant?
+--------------------------------------------------
+
+Citus provides UDFs and metadata tables to determine the mapping of a distribution column value to a particular shard, and the shard placement on a worker node. See :ref:`row_placements` for more details.

reference/user_defined_functions.rst

@@ -426,6 +426,38 @@ The example below fetches and displays the table metadata for the github_events
              24180 | t                 | h           | repo_id  |                  2 |    1073741824 |                     2
     (1 row)
 
+.. _get_shard_id:
+
+get_shard_id_for_distribution_column
+$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
+
+Citus assigns every row of a distributed table to a shard based on the value of the row's distribution column and the table's method of distribution. In most cases the precise mapping is a low-level detail that the database administrator can ignore. However it can be useful to determine a row's shard, either for manual database maintenance tasks or just to satisfy curiosity. The :code:`get_shard_id_for_distribution_column` function provides this info for hash- and range-distributed tables as well as reference tables. It does not work for the append distribution.
+
+Arguments
+************************
+
+**table_name:** The distributed table.
+
+**distribution_value:** The value of the distribution column.
+
+Return Value
+******************************
+
+The shard id Citus associates with the distribution column value for the given table.
+
+Example
+***********************
+
+::
+
+  SELECT get_shard_id_for_distribution_column('my_table', 4);
+
+   get_shard_id_for_distribution_column
+  --------------------------------------
+                                 540007
+  (1 row)
+
+
 .. _cluster_management_functions:
 
 Cluster Management And Repair Functions