docs: configuring enable_expand_roles setting (#1681)

Author: soyeric128

docs/en/sql-reference/20-sql-functions/17-table-functions/show-grants.md

@@ -3,7 +3,7 @@ title: SHOW_GRANTS
 ---
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced or updated: v1.2.487"/>
+<FunctionDescription description="Introduced or updated: v1.2.704"/>
 
 Lists privileges explicitly granted to a user, to a role, or on a specific object.
 
@@ -20,6 +20,75 @@ SHOW_GRANTS('table', '<table_name>', '<catalog_name>', '<db_name>')
 SHOW_GRANTS('database', '<db_name>', '<catalog_name>')
 ```
 
+## Configuring `enable_expand_roles` Setting
+
+The `enable_expand_roles` setting controls whether the SHOW_GRANTS function expands role inheritance when displaying privileges.
+
+- `enable_expand_roles=1` (default):
+
+    - SHOW_GRANTS recursively expands inherited privileges, meaning that if a role has been granted another role, it will display all the inherited privileges.
+    - Users will also see all privileges granted through their assigned roles.
+
+- `enable_expand_roles=0`:
+
+    - SHOW_GRANTS only displays privileges that are directly assigned to the specified role or user.
+    - However, the result will still include GRANT ROLE statements to indicate role inheritance.
+
+For example, role `a` has the `SELECT` privilege on `t1`, and role `b` has the `SELECT` privilege on `t2`:
+
+```sql
+SELECT grants FROM show_grants('role', 'a') ORDER BY object_id;
+
+┌──────────────────────────────────────────────────────┐
+│                        grants                        │
+├──────────────────────────────────────────────────────┤
+│ GRANT SELECT ON 'default'.'default'.'t1' TO ROLE `a` │
+└──────────────────────────────────────────────────────┘
+
+SELECT grants FROM show_grants('role', 'b') ORDER BY object_id;
+
+┌──────────────────────────────────────────────────────┐
+│                        grants                        │
+├──────────────────────────────────────────────────────┤
+│ GRANT SELECT ON 'default'.'default'.'t2' TO ROLE `b` │
+└──────────────────────────────────────────────────────┘
+```
+
+If you grant role `b` to role `a` and check the grants on role `a` again, you can see than the `SELECT` privilege on `t2` is now included in role `a`:
+
+```sql
+GRANT ROLE b TO ROLE a;
+```
+
+```sql
+SELECT grants FROM show_grants('role', 'a') ORDER BY object_id;
+
+┌──────────────────────────────────────────────────────┐
+│                        grants                        │
+├──────────────────────────────────────────────────────┤
+│ GRANT SELECT ON 'default'.'default'.'t1' TO ROLE `a` │
+│ GRANT SELECT ON 'default'.'default'.'t2' TO ROLE `a` │
+└──────────────────────────────────────────────────────┘
+```
+
+If you set `enable_expand_roles` to `0` and check the grants on role `a` again, the result will show the `GRANT ROLE` statement instead of listing the specific privileges inherited from role `b`:
+
+```sql
+SET enable_expand_roles=0;
+```
+
+```sql
+SELECT grants FROM show_grants('role', 'a') ORDER BY object_id;
+
+┌──────────────────────────────────────────────────────┐
+│                        grants                        │
+├──────────────────────────────────────────────────────┤
+│ GRANT SELECT ON 'default'.'default'.'t1' TO ROLE `a` │
+│ GRANT ROLE b to ROLE `a`                             │
+│ GRANT ROLE public to ROLE `a`                        │
+└──────────────────────────────────────────────────────┘
+```
+
 ## Examples
 
 This example illustrates how to list privileges granted to a user, a role, and on a specific object.