document global keyspace flag

content/en/docs/16.0/reference/features/global-routing.md

@@ -4,12 +4,32 @@ weight: 23
 ---
 
 # Global Table Routing
-Vitess has an implicit feature of routing the queries to the appropriate keyspace based on the table specified in the `from` list.
-This differs from the standard mysql, in mysql unqualified tables will fail if the correct database is not set on the connection.
 
-This feature works only for unique table names provided in the [VSchema](https://vitess.io/docs/concepts/vschema/), and only when no default keyspace is set on the connection. One exception to the uniqueness rule is [Reference Tables](../../../user-guides/vschema-guide/advanced-vschema/#reference-tables) that share a name with an explicitly specified `source` table.
+Vitess has an implicit feature of routing the queries to the appropriate keyspace based on the table specified in the `from` list. This differs from the standard mysql, in mysql unqualified tables will fail if the correct database is not set on the connection.
+
+## Requirements
+
+Vitess will globally route queries for tables when:
+
+ * They are specified in the VSchema,
+ * And either:
+   * They have a globally unique name,
+   * Or they are [Reference Tables](../../../user-guides/vschema-guide/advanced-vschema/#reference-tables) with a `source`,
+ * And either:
+   * The connection does not use a default keyspace,
+   * Or the connection uses a Global Keyspace,
+   * Or the table is name is qualified with a Global Keyspace.
+
+## Global Keyspaces
+
+Global keyspaces are a feature that enables global routing to be requested by using a global keyspace name in the connection, or by qualifying a query by a global keyspace name.
+
+To enable this feature, set one or more [VTGate `--global-keyspace [global_ks]` flags](../../programs/vtgate/#options).
+
+## Examples
+
+Given keyspaces `ks`, `customer` and `commerce`:
 
-Example:
 ```sql
 mysql> show keyspaces;
 +----------+
@@ -22,7 +42,7 @@ mysql> show keyspaces;
 3 rows in set (0.00 sec)
 ```
 
-`ks` and `customer` are sharded keyspaces and `commerce` is an unsharded keyspace.
+`ks` and `customer` are sharded keyspaces, and `commerce` is an unsharded keyspace.
 
 Tables present in each of the keyspace.
 
@@ -57,6 +77,10 @@ mysql> show tables from commerce;
 3 rows in set (0.00 sec)
 ```
 
+<br/>
+
+#### Without a default keyspace
+
 Without a default keyspace we can route to unique tables like `corder`, `product` and `player` but cannot route to `customer`
 
 ```sql
@@ -94,7 +118,12 @@ mysql> show columns from customer;
 ERROR 1105 (HY000): ambiguous table reference: customer
 ```
 
-With the default keyspace set to `customer` we can only query tables in `commerce` i.e `customer` and `corder`.
+<br/>
+
+#### With a default keyspace
+
+With the default keyspace set to `customer` we can only query keyspace-unqualified tables in `commerce` i.e `customer` and `corder`.
+
 ```sql
 mysql> use customer
 Reading table information for completion of table and column names
@@ -125,7 +154,12 @@ mysql> show columns from product;
 ERROR 1105 (HY000): table product not found
 ```
 
-With a default keyspace set, the queries can be routed to other keyspaces by specifying the table qualifier.
+<br/>
+
+#### Queries qualified by a keyspace
+
+With a default keyspace set, queries can be routed to other keyspaces by qualifying the table name with the keyspace name.
+
 ```sql
 mysql> use customer
 Reading table information for completion of table and column names
@@ -151,3 +185,50 @@ mysql> show columns from commerce.product;
 +-------------+----------------+------+-----+---------+-------+
 3 rows in set (0.00 sec)
 ```
+
+<br/>
+
+#### With a default global keyspace
+
+Global routing may be requested by using a global keyspace on the connection. Vitess will behave the same way as if no default keyspace was set.
+
+```sql
+mysql> use global_ks;
+Reading table information for completion of table and column names
+You can turn off this feature to get a quicker startup with -A
+
+Database changed
+mysql> show columns from corder;
++-------------+----------------+------+-----+---------+-------+
+| Field       | Type           | Null | Key | Default | Extra |
++-------------+----------------+------+-----+---------+-------+
+| order_id    | bigint         | NO   | PRI | NULL    |       |
+| customer_id | bigint         | YES  |     | NULL    |       |
+| sku         | varbinary(128) | YES  |     | NULL    |       |
+| price       | bigint         | YES  |     | NULL    |       |
++-------------+----------------+------+-----+---------+-------+
+4 rows in set (0.01 sec)
+```
+
+<br/>
+
+#### Queries qualified by a global keyspace
+
+With a default keyspace set, global routing may be requested by qualifying a table with a global keyspace.
+
+```sql
+mysql> use customer
+Reading table information for completion of table and column names
+You can turn off this feature to get a quicker startup with -A
+
+Database changed
+mysql> show columns from global_ks.product;
++-------------+----------------+------+-----+---------+-------+
+| Field       | Type           | Null | Key | Default | Extra |
++-------------+----------------+------+-----+---------+-------+
+| sku         | varbinary(128) | NO   | PRI | NULL    |       |
+| description | varbinary(128) | YES  |     | NULL    |       |
+| price       | bigint         | YES  |     | NULL    |       |
++-------------+----------------+------+-----+---------+-------+
+3 rows in set (0.00 sec)
+```

content/en/docs/16.0/reference/programs/vtgate.md

@@ -59,6 +59,7 @@ The following global options apply to `vtgate`:
 | --enable_set_var | boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections. |
 | --gate_query_cache_size | int | gate server query cache size, maximum number of queries to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 10000) |
 | --gateway_initial_tablet_timeout | duration | At startup, the gateway will wait up to that duration to get one tablet per keyspace/shard/tablettype (default 30s) |
+| --global-keyspace | strings | Global routing behavior applies when no default keyspace is set on a connection, or when a global keyspace is used. Multiple global keyspaces may defined by specifying this flag multiple times. |
 | --grpc_auth_mode | string | Which auth plugin implementation to use (eg: static) |
 | --grpc_auth_mtls_allowed_substrings | string | List of substrings of at least one of the client certificate names (separated by colon). |
 | --grpc_auth_static_client_creds | string | when using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server |