PGD: document new function "bdr.galloc_chunk_info()" (WIP)

This function removes the need to query galloc sequences allocated
on the local node by referencing hidden rows by their CTID, which is
really not something we want end users to be doing.

DOCS-1258.

Author: ibarwick

product_docs/docs/pgd/5.7/reference/sequences.mdx

@@ -220,6 +220,25 @@ bdr.timestamp_to_timeshard(ts timestamptz)
 
 -   `ts` — Timestamp to use for the `timeshard` sequence generation.
 
+### `bdr.galloc_chunk_info`
+
+This function retrieves the ranges allocated to a galloc sequence on the local
+node.
+
+An empty result set will be returned if the sequence has not yet been accessed
+on the local node.
+
+An ERROR will be raised if the provided sequence name is not a galloc sequence.
+
+#### Synopsis
+
+```sql
+bdr.galloc_chunk_info(seqname regclass)
+```
+#### Parameters
+
+-   `seqname` - the name of the galloc sequence to query
+
 #### Notes
 
 This function executes only on the local node.

product_docs/docs/pgd/5.7/sequences.mdx

@@ -332,48 +332,30 @@ SELECT * FROM bdr.sequence_alloc
 (1 row)
 ```
 
-To see the ranges currently assigned to a given sequence on each node, use
-these queries:
+To see the ranges currently assigned to a given sequence on each node, execute the function
+[`bdr.galloc_chunk_info`](reference/sequences/#bdrgalloc_chunk_info).
 
-* Node `Node1` is using range from `333` to `2000333`.
+* Node `Node1` is using range from `334` to `2000333`.
 
 ```sql
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,2)'; -- first range
- range_start | range_end
+SELECT * FROM bdr.galloc_chunk_info('categories_category_seq');
+ chunk_start | chunk_end
 -------------+-----------
          334 |   1000333
-(1 row)
-
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,3)'; -- second range
- range_start | range_end
--------------+-----------
      1000334 |   2000333
-(1 row)
+(2 rows)
 ```
 
 * Node `Node2` is using range from `2000334` to `4000333`.
 
 ```sql
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,2)'; -- first range
- range_start | range_end
+SELECT * FROM bdr.galloc_chunk_info('categories_category_seq');
+ chunk_start | chunk_end
 -------------+-----------
      2000334 |   3000333
-(1 row)
-
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,3)'; -- second range
- range_start | range_end
--------------+-----------
      3000334 |   4000333
 ```
 
-!!! NOTE 
-    You can't combine it to a single query (like `WHERE ctid IN ('(0,2)', '(0,3)')`),
-    as that still shows only the first range.
-
 When a node finishes a chunk, it asks a consensus for a new one and gets the
 first available. In the example, it's from 4000334 to 5000333. This is
 the new reserved chunk and starts to consume the old reserved chunk.