docs: Update sql syntax and options table (part 2) #30425

kay-kim · 2024-11-11T17:39:02Z

No description provided.

kay-kim · 2024-11-12T16:26:43Z

doc/user/content/sql/show-materialized-views.md

-_cluster&lowbar;name_ | The cluster to show materialized views from. If omitted, materialized views from all clusters are shown.
+Option                      | Description
+----------------------------|------------
+**FROM** <schema_name>      | The schema to show materialized views from. Defaults to first resolvable schema in the search path. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).


Per your suggestion from #30398 (comment)
-- Doing them in batches allowed me to do a sweep and I realized I might be letting the tail wag the dog in that what might turn out to be smaller exceptions shouldn't rule the majority. Even if decent number of exceptions, eh ... as long as we're consistent with those, we could just have 2 models.

kay-kim · 2024-11-12T17:01:08Z

doc/user/content/sql/show-materialized-views.md

@@ -11,12 +11,14 @@ in Materialize.

 ## Syntax

-{{< diagram "show-materialized-views.svg" >}}
+```mzsql


https://preview.materialize.com/materialize/30425/sql/show-materialized-views/

morsapaes · 2024-11-13T10:46:05Z

doc/user/content/sql/show-privileges.md

+**ON** <object_type>         | Specifies an object type to show privileges for a particular object type. Valid values are: <div style="display: flex;"> <ul style="margin-right: 20px;"> <li><strong>TABLES</strong></li> <li><strong>TYPES</strong></li> <li><strong>SECRETS</strong></li> <li><strong>CONNECTION</strong></li> </ul> <ul> <li><strong>DATABASES</strong></li> <li><strong>SCHEMAS</strong></li> <li><strong>CLUSTERS</strong></li> <li><strong>SYSTEM</strong></li> </ul> </div>Omit to show privileges for all object types.
+**FOR** <role_name>          | Specifies a role for which to show the membership. Omit to show role membership for all roles.


Suggested change

**ON** <object_type> | Specifies an object type to show privileges for a particular object type. Valid values are: <div style="display: flex;"> <ul style="margin-right: 20px;"> <li>TABLES</li> <li>TYPES</li> <li>SECRETS</li> <li>CONNECTION</li> </ul> <ul> <li>DATABASES</li> <li>SCHEMAS</li> <li>CLUSTERS</li> <li>SYSTEM</li> </ul> </div>Omit to show privileges for all object types.

**FOR** <role_name> | Specifies a role for which to show the membership. Omit to show role membership for all roles.

**ON** <object_type> | The object type to show privileges for. Accepted object types: <div style="display: flex;"> <ul style="margin-right: 20px;"> <li>TABLES</li> <li>TYPES</li> <li>SECRETS</li> <li>CONNECTION</li> </ul> <ul> <li>DATABASES</li> <li>SCHEMAS</li> <li>CLUSTERS</li> <li>SYSTEM</li> </ul> </div>If omitted, privileges for all object types are shown.

**FOR** <role_name> | The role for which to show role membership. If omitted, role membership for all roles is shown.

For consistency with other SHOW pages.

(also commented below because scrolling is hard ... but I overcame that inertia to copy+paste here😄)
As for the two outliers in this batch, just an oversight on my part. Am using Cursor, and sometimes, I think I'd already accepted the suggestion and don't actually tab to accept the suggestion (whereas other times, I think I didn't accept the suggestion and accidentally just add a tab).

morsapaes · 2024-11-13T10:49:15Z

doc/user/content/sql/show-role-membership.md

-_role_name_                                         | Only shows role memberships granted directly or indirectly to _role_name_.
+Option                     | Description
+---------------------------|------------
+**FOR** <role_name>        | Specifies a role for which to show the membership. Omit to show role membership for all roles.


Suggested change

**FOR** <role_name> | Specifies a role for which to show the membership. Omit to show role membership for all roles.

**FOR** <role_name> | The role for which to show the membership. If omitted, role membership for all roles is shown.

morsapaes · 2024-11-13T10:57:09Z

doc/user/content/sql/show-roles.md

+**LIKE** \<pattern\>       | Specifies the pattern to show only the roles whose name matches the pattern.
+**WHERE** <condition(s)>   | Specifies the condition(s) to show only the roles that meet the condition(s).


Suggested change

**LIKE** \<pattern\> | Specifies the pattern to show only the roles whose name matches the pattern.

**WHERE** <condition(s)> | Specifies the condition(s) to show only the roles that meet the condition(s).

**LIKE** \<pattern\> | The pattern to match roles against. If specified, only roles that match the specified pattern will be shown.

**WHERE** <condition(s)> | The condition(s) to match roles against. If specified, only roles that meet the specified condition(s) will be shown.

Writing "If specified" here made me realize that it doesn't make much sense that we mostly use "If omitted" elsewhere for clauses that are...optional. It'd be nice to change those occurrences to instead describe what happens if you actually use the optional clause.

💯 -- Will add a patch for that.

morsapaes · 2024-11-13T10:59:20Z

doc/user/content/sql/show-schemas.md

-_database&lowbar;name_ | The database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).
+Option                        | Description
+------------------------------|------------
+**FROM** <database_name>      | Specifies the database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).


Suggested change

**FROM** <database_name> | Specifies the database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).

**FROM** <database_name> | The database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).

morsapaes · 2024-11-13T10:59:42Z

doc/user/content/sql/show-secrets.md

-_schema&lowbar;name_ | The schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).
+Option                        | Description
+------------------------------|------------
+**FROM** <schema_name>        | Specifies the schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).


Suggested change

**FROM** <schema_name> | Specifies the schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).

**FROM** <schema_name> | The schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).

Same though here, but...it seems like we sometimes use these optional clauses to clarify the default behavior, which shouldn't be the case. Also valid e.g., in SHOW SCHEMAS [ FROM \<database\>].

morsapaes · 2024-11-13T11:09:59Z

doc/user/content/sql/show-sinks.md

-_cluster&lowbar;name_ | The cluster to show sinks from. If omitted, sinks from all clusters are shown. For available clusters, see [`SHOW CLUSTERS`](../show-clusters).
+Option                        | Description
+------------------------------|------------
+**FROM** <schema_name>        | Specifies the schema to show sinks from. Defaults to first resolvable schema in the search path. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).


Suggested change

**FROM** <schema_name> | Specifies the schema to show sinks from. Defaults to first resolvable schema in the search path. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).

**FROM** <schema_name> | The schema to show sinks from. Defaults to first resolvable schema in the search path. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).

I was mindlessly removing the "Specifies" because...less words > more words? Will stop here just in case you have a strong preference for including it, though.

So, I think technically, "Specifies ..." is more accurate since "The schema to show sinks from" would actually describe <schema_name>. Whether I have a strong preference ... eh. Given that I know I'll do additional passes through all these files in the future, only a mild preference ... more so in that in later passes (which could even be as I work on next batch of these), it's much easier to remove text than add.

As for the two outliers in this batch, just an oversight on my part. Am using Cursor, and sometimes, I think I'd already accepted the suggestion and don't actually tab to accept the suggestion (whereas other times, I think I didn't accept the suggestion and accidentally just add a tab).

Oh ... Let me try in the next patch with "Specifies" -> "If specified, shows ..."

kay-kim · 2024-11-13T16:48:56Z

doc/user/content/sql/show-materialized-views.md

-_cluster&lowbar;name_ | The cluster to show materialized views from. If omitted, materialized views from all clusters are shown.
+Option                      | Description
+----------------------------|------------
+**FROM** <schema_name>      | If specified, only show materialized views from the specified schema. Defaults to first resolvable schema in the search path. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).


It is a little repetitious with the 2 "specified" ... but eh.
I tried other variations like "If included, ... the specified schema" or "If specified, ... the given schema." or "If specified ... <schema_name>" but I think specified works better than those. Maybe during other batches/sweeps, something better will pop into mind.

docs: Update sql syntax and options table (part 2)

f5fc19f

kay-kim requested a review from a team as a code owner November 11, 2024 17:39

docs: Update sql syntax and options table (part 3)

647e892

kay-kim commented Nov 12, 2024

View reviewed changes

morsapaes requested changes Nov 13, 2024

View reviewed changes

updates per feedback

5ad9ff4

kay-kim force-pushed the docs-sql-syntax-options-part2 branch from 384b6a6 to 5ad9ff4 Compare November 13, 2024 16:45

kay-kim commented Nov 13, 2024

View reviewed changes

kay-kim requested a review from morsapaes November 13, 2024 16:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Update sql syntax and options table (part 2) #30425

docs: Update sql syntax and options table (part 2) #30425

kay-kim commented Nov 11, 2024

kay-kim Nov 12, 2024

kay-kim Nov 12, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

kay-kim Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

kay-kim Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

morsapaes Nov 13, 2024

kay-kim Nov 13, 2024

kay-kim Nov 13, 2024

kay-kim Nov 13, 2024

kay-kim Nov 13, 2024

		ON <object_type> \| Specifies an object type to show privileges for a particular object type. Valid values are: <div style="display: flex;"> <ul style="margin-right: 20px;"> <li><strong>TABLES</strong></li> <li><strong>TYPES</strong></li> <li><strong>SECRETS</strong></li> <li><strong>CONNECTION</strong></li> </ul> <ul> <li><strong>DATABASES</strong></li> <li><strong>SCHEMAS</strong></li> <li><strong>CLUSTERS</strong></li> <li><strong>SYSTEM</strong></li> </ul> </div>Omit to show privileges for all object types.
		FOR <role_name> \| Specifies a role for which to show the membership. Omit to show role membership for all roles.

	FOR <role_name> \| Specifies a role for which to show the membership. Omit to show role membership for all roles.
	FOR <role_name> \| The role for which to show the membership. If omitted, role membership for all roles is shown.

		LIKE \<pattern\> \| Specifies the pattern to show only the roles whose name matches the pattern.
		WHERE <condition(s)> \| Specifies the condition(s) to show only the roles that meet the condition(s).

	FROM <database_name> \| Specifies the database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).
	FROM <database_name> \| The database to show schemas from. Defaults to the current database. For available databases, see [`SHOW DATABASES`](../show-databases).

	FROM <schema_name> \| Specifies the schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).
	FROM <schema_name> \| The schema to show secrets from. If omitted, secrets from the first schema in the search path are shown. For available schemas, see [`SHOW SCHEMAS`](../show-schemas).

docs: Update sql syntax and options table (part 2) #30425

Are you sure you want to change the base?

docs: Update sql syntax and options table (part 2) #30425

Conversation

kay-kim commented Nov 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment