edu-4: refactor reference/sql reference

ci/test/lint-docs-catalog.sh

@@ -23,9 +23,9 @@ set -euo pipefail
 . misc/shlib/shlib.bash
 
 catalog_files=(
-  doc/user/content/sql/system-catalog/mz_internal.md
-  doc/user/content/sql/system-catalog/mz_introspection.md
-  doc/user/content/sql/system-catalog/mz_catalog.md
+  doc/user/content/reference/system-catalog/mz_internal.md
+  doc/user/content/reference/system-catalog/mz_introspection.md
+  doc/user/content/reference/system-catalog/mz_catalog.md
 )
 
 slt_directory=test/sqllogictest/autogenerated

doc/user/config.toml

@@ -64,10 +64,16 @@ weight = 12
 # Reference
 #
 
+[[menu.main]]
+identifier = "sql"
+name = "SQL Reference"
+weight = 75
+
+
 [[menu.main]]
 identifier = "reference"
 name = "Reference"
-weight = 80
+weight = 76
 
 #
 # Releases

doc/user/content/concepts/reaction-time.md

@@ -30,7 +30,7 @@ Together, these concepts form the basis for understanding how Materialize enable
 
 ### Monitoring Freshness
 
-You can monitor data freshness in Materialize by querying wallclock lag measurements from the [`mz_internal.mz_wallclock_global_lag`](/sql/system-catalog/mz_internal/#mz_wallclock_global_lag) system catalog view.
+You can monitor data freshness in Materialize by querying wallclock lag measurements from the [`mz_internal.mz_wallclock_global_lag`](/reference/system-catalog/mz_internal/#mz_wallclock_global_lag) system catalog view.
 Wallclock lag indicates how far behind real-world wall-clock time your data objects are, helping you understand freshness across your materialized views, indexes, and sources.
 
 ```sql

doc/user/content/headless/rbac-cloud/db-roles-initial-privileges.md

@@ -7,8 +7,8 @@ headless: true
 
 In addition, all roles have:
 - `USAGE` on all built-in types and [all system catalog
-schemas](/sql/system-catalog/).
-- `SELECT` on [system catalog objects](/sql/system-catalog/).
+schemas](/reference/system-catalog/).
+- `SELECT` on [system catalog objects](/reference/system-catalog/).
 - All [applicable privileges](/security/appendix/appendix-privileges/) for
   an object they create; for example, the creator of a schema gets `CREATE` and
   `USAGE`; the creator of a table gets `SELECT`, `INSERT`, `UPDATE`, and

doc/user/content/headless/rbac-sm/db-roles-initial-privileges.md

@@ -7,8 +7,8 @@ headless: true
 
 In addition, all roles have:
 - `USAGE` on all built-in types and [all system catalog
-schemas](/sql/system-catalog/).
-- `SELECT` on [system catalog objects](/sql/system-catalog/).
+schemas](/reference/system-catalog/).
+- `SELECT` on [system catalog objects](/reference/system-catalog/).
 - All [applicable privileges](/security/appendix/appendix-privileges/) for
   an object they create; for example, the creator of a schema gets `CREATE` and
   `USAGE`; the creator of a table gets `SELECT`, `INSERT`, `UPDATE`, and

doc/user/content/ingest-data/monitoring-data-ingestion.md

@@ -84,7 +84,7 @@ In the Materialize Console, you can go to the source overview page to view the
 data ingestion progress (e.g., rows_received, bytes_received, ingestion rate).
 
 Alternatively, you can query the
-[`mz_source_statistics`](/sql/system-catalog/mz_internal/#mz_source_statistics)
+[`mz_source_statistics`](/reference/system-catalog/mz_internal/#mz_source_statistics)
 table and look for ingestion statistics that advance over time:
 
 ```mzsql

doc/user/content/ingest-data/network-security/static-ips.md

@@ -38,7 +38,7 @@ Region          | CIDR
 ## Fetching static egress IPs addresses
 
 You can fetch the static egress CIDR blocks associated with your region by
-querying the [`mz_egress_ips`](/sql/system-catalog/mz_catalog/#mz_egress_ips)
+querying the [`mz_egress_ips`](/reference/system-catalog/mz_catalog/#mz_egress_ips)
 system catalog table.
 
 ```mzsql
@@ -53,7 +53,7 @@ SELECT * FROM mz_egress_ips;
 ```
 
 As an alternative, you can also submit an HTTP request to Materialize's
-[SQL API](/integrations/http-api/) querying the [`mz_egress_ips`](/sql/system-catalog/mz_catalog/#mz_egress_ips)
+[SQL API](/integrations/http-api/) querying the [`mz_egress_ips`](/reference/system-catalog/mz_catalog/#mz_egress_ips)
 system catalog table. In the request, specify the username, app password, and
 host for your Materialize region:
 

doc/user/content/ingest-data/troubleshooting.md

@@ -32,7 +32,7 @@ to https://console.materialize.com/, clicking the **Sources** tab in the
 navigation bar, and clicking the affected source.
 
 Alternatively, you can get this information from the system catalog by querying
-the [`mz_source_statuses`](/sql/system-catalog/mz_internal/#mz_source_statuses)
+the [`mz_source_statuses`](/reference/system-catalog/mz_internal/#mz_source_statuses)
 table:
 
 ```mzsql
@@ -66,7 +66,7 @@ breaks out of the query).
 {{< include-md file="shared-content/snapshotting-cluster-size-postgres.md" >}}
 
 To determine whether your source has completed ingesting the initial snapshot,
-you can query the [`mz_source_statistics`](/sql/system-catalog/mz_internal/#mz_source_statistics)
+you can query the [`mz_source_statistics`](/reference/system-catalog/mz_internal/#mz_source_statistics)
 system catalog table:
 
 ```mzsql

doc/user/content/ingest-data/webhooks/amazon-eventbridge.md

@@ -86,7 +86,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/ingest-data/webhooks/hubspot.md

@@ -86,7 +86,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/ingest-data/webhooks/rudderstack.md

@@ -86,7 +86,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/ingest-data/webhooks/segment.md

@@ -83,7 +83,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/ingest-data/webhooks/snowcatcloud.md

@@ -86,7 +86,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/ingest-data/webhooks/stripe.md

@@ -102,7 +102,7 @@ https://<HOST>/api/webhook/<database>/<schema>/<src_name>
 ```
 
 If you missed the notice, you can find the URLs for all webhook sources in the
-[`mz_internal.mz_webhook_sources`](/sql/system-catalog/mz_internal/#mz_webhook_sources)
+[`mz_internal.mz_webhook_sources`](/reference/system-catalog/mz_internal/#mz_webhook_sources)
 system table.
 
 ### Access and authentication

doc/user/content/manage/dbt/get-started.md

@@ -1008,7 +1008,7 @@ For "use-at-your-own-risk" workarounds, see [`dbt-core` #4226](https://github.co
     ```
 
 1. Once `persist-docs` is configured, any `description` defined in your `.yml`
-  files is persisted to Materialize in the [mz_internal.mz_comments](/sql/system-catalog/mz_internal/#mz_comments)
+  files is persisted to Materialize in the [mz_internal.mz_comments](/reference/system-catalog/mz_internal/#mz_comments)
   system catalog table on every `dbt run`:
 
     ```mzsql

doc/user/content/manage/monitor/cloud/alerting.md

@@ -24,10 +24,10 @@ For each threshold level, use the following table as a guide to set up your own
 
 Metric | Warning | Alert | Description
 -- | -- | -- | --
-Memory utilization | 80% | 90% | Average [memory utilization](https://materialize.com/docs/sql/system-catalog/mz_internal/#mz_cluster_replica_utilization), (defined using heap_percent) for a cluster in the last *15 minutes*.
+Memory utilization | 80% | 90% | Average [memory utilization](https://materialize.com/docs/reference/system-catalog/mz_internal/#mz_cluster_replica_utilization), (defined using heap_percent) for a cluster in the last *15 minutes*.
 Source status | - | On Change | Source status change in the last *1 minute*.
 Cluster status | - | On Change | Cluster replica status change in the last *1 minute*.
-Freshness | > 5s | > 1m | Average [lag behind an input](/sql/system-catalog/mz_internal/#mz_materialization_lag) in the last *15 minutes*.
+Freshness | > 5s | > 1m | Average [lag behind an input](/reference/system-catalog/mz_internal/#mz_materialization_lag) in the last *15 minutes*.
 
 {{<note>}}
 Customers on legacy cluster sizes should still monitor their Memory usage. Please [contact support](/support/) for questions.

doc/user/content/manage/monitor/self-managed/alerting.md

@@ -29,7 +29,7 @@ CPU | 85% | 100% | Average CPU usage for a cluster in the last *15 minutes*.
 Memory | 80% | 90% | Average memory usage for a cluster in the last *15 minutes*.
 Source status | - | On Change | Source status change in the last *1 minute*.
 Cluster status | - | On Change | Cluster replica status change in the last *1 minute*.
-Freshness | > 5s | > 1m | Average [lag behind an input](/sql/system-catalog/mz_internal/#mz_materialization_lag) in the last *15 minutes*.
+Freshness | > 5s | > 1m | Average [lag behind an input](/reference/system-catalog/mz_internal/#mz_materialization_lag) in the last *15 minutes*.
 
 ### Custom Thresholds
 

doc/user/content/sql/explain-plan-operators.md → doc/user/content/reference/explain-plan-operators.md

@@ -8,11 +8,13 @@ menu:
     identifier: 'explain-plan-operators'
     weight: 140
 disable_list: true
+aliases:
+  - /sql/explain-plan-operators/
 ---
 
 Materialize offers several output formats for [`EXPLAIN
 PLAN`](/sql/explain-plan/) and debugging. LIR plans as rendered in
-[`mz_introspection.mz_lir_mapping`](../../sql/system-catalog/mz_introspection/#mz_lir_mapping)
+[`mz_introspection.mz_lir_mapping`](../../reference/system-catalog/mz_introspection/#mz_lir_mapping)
 are deliberately succinct, while the plans in other formats give more detail.
 
 The decorrelated and optimized plans from `EXPLAIN DECORRELATED PLAN

doc/user/content/sql/m1-cc-mapping.md → doc/user/content/reference/m1-cc-mapping.md

@@ -5,7 +5,9 @@ menu:
   main:
     parent: reference
     identifier: 'm1-cc-mapping'
-    weight: 195
+    weight: 50
+aliases:
+  - /sql/m1-cc-mapping/
 ---
 
 The following table provides a general mapping of M.1 to cc cluster sizes:

doc/user/content/sql/system-catalog/_index.md → doc/user/content/reference/system-catalog/_index.md

@@ -8,6 +8,8 @@ menu:
     identifier: 'system-catalog'
     weight: 160
 disable_list: true
+aliases:
+  - /reference/system-catalog/
 ---
 
 Materialize exposes a system catalog that contains metadata about the running

doc/user/content/sql/system-catalog/information_schema.md → doc/user/content/reference/system-catalog/information_schema.md

@@ -5,6 +5,8 @@ menu:
   main:
     parent: 'system-catalog'
     weight: 3
+aliases:
+  - /reference/system-catalog/information_schema/
 ---
 
 Materialize has compatibility shims for the following relations from the