docs: create table update syntax (part 1)

Author: kay-kim

doc/user/assets/sass/_content.scss

@@ -749,9 +749,7 @@ p+p {
         padding: 0;
         border-bottom: 1px solid #9c86e0;
         display: flex;
-        overflow-x: scroll;
-
-        padding-bottom: var(--xx-small);
+        overflow-x: auto;
 
         @media(max-width: 850px) {}
 
@@ -760,13 +758,15 @@ p+p {
             margin: 0 rem(0.1);
             padding: 0;
             position: relative;
-            bottom: -1px;
+
             background: var(--gray-lightest);
+            border-radius: 8px 8px 0 0;
+
 
             a {
                 color: var(--body);
                 display: block;
-                padding: rem(0.8) rem(1.6);
+                padding: rem(0.8) rem(1.5);
                 font-size: rem(1.4);
                 text-decoration: none;
                 font-weight: 500;
@@ -787,7 +787,6 @@ p+p {
 
             &.active {
                 background: var(--bg);
-                border-radius: 2px 2px 0 0;
                 border: 1px solid #9c86e0;
                 border-bottom-color: var(--bg);
 

doc/user/content/sql/create-table.md

@@ -9,45 +9,84 @@ menu:
     parent: 'commands'
 ---
 
-`CREATE TABLE` defines a table that is persisted in durable storage and can be
-written to, updated and seamlessly joined with other tables, views or sources.
+`CREATE TABLE` defines a table that is persisted in durable storage. In
+Materialize, you can create:
 
-Tables in Materialize are similar to tables in standard relational databases:
-they consist of rows and columns where the columns are fixed when the table is
-created but rows can be added to at will via [`INSERT`](../insert) statements.
+- User-populated tables. User-populated tables can be written to (i.e.,
+  [`INSERT`]/[`UPDATE`]/[`DELETE`]) by the user.
 
-{{< warning >}}
-At the moment, tables have many [known limitations](#known-limitations). In most
-situations, you should use [sources](/sql/create-source) instead.
-{{< /warning >}}
+- [Source-populated](/concepts/sources/) tables. Source-populated tables cannot
+  be written to by the user; they are populated through data ingestion from a
+  source.
 
-[//]: # "TODO(morsapaes) Bring back When to use a table? once there's more
-clarity around best practices."
+Tables can be joined with other tables, materialized views, and views. Tables in
+Materialize are similar to tables in standard relational databases: they consist
+of rows and columns where the columns are fixed when the table is created.
 
 ## Syntax
 
-{{< diagram "create-table.svg" >}}
+{{< tabs >}}
 
-### `col_option`
+{{< tab "User-populated tables" >}}
 
-{{< diagram "col-option.svg" >}}
+To create a table that users can write to (i.e., perform
+[`INSERT`](/sql/insert/)/[`UPDATE`](/sql/update/)/[`DELETE`](/sql/delete/)
+operations):
 
-### `with_options`
+```mzsql
+CREATE [TEMP|TEMPORARY] TABLE <table_name> (
+  <column_name> <column_type> [NOT NULL][DEFAULT <default_expr>]
+  [, ...]
+)
+[WITH (
+  RETAIN HISTORY [=] FOR <duration> | PARTITION BY (<column_name> [, ...])
+  [, ...]
+)]
+;
+```
+
+{{% yaml-table data="syntax_options/create_table_options_user_populated" %}}
+
+{{</ tab >}}
+
+{{< tab "Source-populated tables (DB source)" >}}
 
-{{< diagram "with-options-retain-history.svg" >}}
+To create a table from a [source](/sql/create-source/), where the source maps to
+an external database system:
 
-Field | Use
-------|-----
-**TEMP** / **TEMPORARY** | Mark the table as [temporary](#temporary-tables).
-_table&lowbar;name_ | A name for the table.
-_col&lowbar;name_ | The name of the column to be created in the table.
-_col&lowbar;type_ | The data type of the column indicated by _col&lowbar;name_.
-**NOT NULL** | Do not allow the column to contain _NULL_ values. Columns without this constraint can contain _NULL_ values.
-*default_expr* | A default value to use for the column in an [`INSERT`](/sql/insert) statement if an explicit value is not provided. If not specified, `NULL` is assumed.
-_retention_period_ | ***Private preview.** This option has known performance or stability issues and is under active development.* Duration for which Materialize retains historical data, which is useful to implement [durable subscriptions](/transform-data/patterns/durable-subscriptions/#history-retention-period). Accepts positive [interval](/sql/types/interval/) values (e.g. `'1hr'`). Default: `1s`.
+{{< note >}}
+
+Users cannot write to source-populated tables; i.e., users cannot perform
+[`INSERT`](/sql/insert/)/[`UPDATE`](/sql/update/)/[`DELETE`](/sql/delete/)
+operations on source-populated tables.
+
+{{</ note >}}
+
+```mzsql
+CREATE TABLE <table_name> FROM SOURCE <source_name> (REFERENCE <ref_object>)
+[WITH (
+    TEXT COLUMNS (<fq_column_name> [, ...])
+  | EXCLUDE COLUMNS (<fq_column_name> [, ...])
+  | PARTITION BY  (<fq_column_name> [, ...])
+  [, ...]
+)]
+;
+```
+
+{{% yaml-table data="syntax_options/create_table_options_source_populated_db" %}}
+
+{{</ tab >}}
+
+
+{{</ tabs >}}
 
 ## Details
 
+### Table names and column names
+
+Names for tables and column(s) must follow the [naming
+guidelines](/sql/identifiers/#naming-restrictions).
+
 ### Known limitations
 
 Tables do not currently support:
@@ -104,4 +143,9 @@ The privileges required to execute this statement are:
 ## Related pages
 
 - [`INSERT`](../insert)
+- [`CREATE SOURCE`](/sql/create-source/)
 - [`DROP TABLE`](../drop-table)
+
+[`INSERT`]: /sql/insert/
+[`UPDATE`]: /sql/update/
+[`DELETE`]: /sql/delete/

doc/user/data/syntax_options/create_table_options_source_populated_db.yml

@@ -0,0 +1,45 @@
+columns:
+  - column: "Parameter"
+  - column: "Description"
+rows:
+  - "Parameter": "`<table_name>`"
+    "Description": |
+
+      The name of the table to create. Names for tables must follow the [naming
+      guidelines](/sql/identifiers/#naming-restrictions).
+
+  - "Parameter": "`<source_name>`"
+    "Description": |
+
+      The name of the [source](/sql/create-source/) associated with the
+      reference object from which to create the table.
+
+  - "Parameter": "**(REFERENCE <ref_object>)**"
+    "Description": |
+
+      The name of the reference object from which to create the table. Reference
+      objects are the names of the tables in the upstream database. You can
+      create multiple tables from the same reference object.
+
+      To find the reference objects available in your
+      [source](/sql/create-source/), you can use the following query,
+      substituting your source name for `<source_name>`:
+
+      <br>
+
+      ```mzsql
+      SELECT refs.*
+      FROM mz_internal.mz_source_references refs, mz_sources s
+      WHERE s.name = '<source_name>' -- substitute with your source name
+      AND refs.source_id = s.id;
+      ```
+
+  - "Parameter": "**WITH (<with_option>[,...])**"
+    "Description": |
+      The following `<with_option>`s are supported:
+
+      | Option | Description |
+      |--------|-------------|
+      | `TEXT COLUMNS (<fq_column_name> [, ...])` | *Optional.* If specified, decode data as `text` for the listed column(s). Use fully qualified column names. |
+      | `EXCLUDE COLUMNS (<fq_column_name> [, ...])` | *Optional.* If specified, exclude the listed column(s) from the table. Use fully qualified column names. |
+      | `RETAIN HISTORY <duration>` | *Optional.* ***Private preview.** This option has known performance or stability issues and is under active development.* <br>If specified, Materialize retains historical data for the specified duration, which is useful to implement [durable subscriptions](/transform-data/patterns/durable-subscriptions/#history-retention-period).<br>Accepts positive [interval](/sql/types/interval/) values (e.g., `'1hr'`).|

doc/user/data/syntax_options/create_table_options_user_populated.yml

@@ -0,0 +1,41 @@
+columns:
+  - column: "Parameter"
+  - column: "Description"
+rows:
+  - "Parameter": "**TEMP** / **TEMPORARY**"
+    "Description": |
+      *Optional.* If specified, mark the table as [temporary](#temporary-tables). Temporary
+      tables are automatically dropped at the end of the SQL session and are not
+      visible to other connections. See [temporary tables](#temporary-tables)
+      for more details.
+  - "Parameter": "`<table_name>`"
+    "Description": |
+
+      The name of the table to create. Names for tables must follow the [naming
+      guidelines](/sql/identifiers/#naming-restrictions).
+
+  - "Parameter": "`<column_name>`"
+    "Description": |
+
+      The name of a column to be created in the new table. Names for columns
+      must follow the [naming guidelines](/sql/identifiers/#naming-restrictions).
+
+  - "Parameter": "`<column_type>`"
+    "Description": |
+
+      The type of the column. For supported types, see [SQL data types](/sql/types/).
+
+  - "Parameter": "**NOT NULL**"
+    "Description": |
+      *Optional.* If specified, disallow  _NULL_ values for the column. Columns without this constraint can contain _NULL_ values.
+  - "Parameter": "**DEFAULT <default_expr>**"
+    "Description": |
+      *Optional.* If specified, use the `<default_expr>` as the default value for the column. If not specified, `NULL` is used as the default value.
+  - "Parameter": "**WITH (<with_option>[,...])**"
+    "Description": |
+
+      The following `<with_option>`s are supported:
+
+      | Option | Description |
+      |--------|-------------|
+      | `RETAIN HISTORY <duration>` | *Optional.* ***Private preview.** This option has known performance or stability issues and is under active development.* <br>If specified, Materialize retains historical data for the specified duration, which is useful to implement [durable subscriptions](/transform-data/patterns/durable-subscriptions/#history-retention-period).<br>Accepts positive [interval](/sql/types/interval/) values (e.g., `'1hr'`).|

doc/user/layouts/partials/head.html

@@ -115,35 +115,50 @@
 
 {{/* Tabs */}}
 <script>
-  $(document).ready(function () {
-    // make nav-tab lists from tab-panes
-    $(".tab-content").each(function (idx, tab) {
-      $(tab)
-        .find(".tab-pane")
-        .each(function (item) {
-          var navTabs = $(this).closest(".code-tabs").find(".nav-tabs"),
-            title = $(this).attr("title"),
-            id = title
-              .toLowerCase()
-              .replace(/ /g, "-")
-              .replace(/[^\w-]+/g, "");
-          navTabs.append(`<li><a href="#${id}-t${idx}">${title}</a></li>`);
-        });
-    });
+document.addEventListener("DOMContentLoaded", function () {
+  document.querySelectorAll(".code-tabs").forEach(function (tabGroup, groupIndex) {
+    const navTabs = tabGroup.querySelector(".nav-tabs");
+    const tabContent = tabGroup.querySelector(".tab-content");
+    const tabPanes = Array.from(tabContent.children).filter(child =>
+      child.classList.contains("tab-pane")
+    );
+
+    // Create tab headers from panes
+    tabPanes.forEach(function (pane, tabIndex) {
+      const title = pane.getAttribute("title") || `Tab ${tabIndex + 1}`;
+      const id = `tab-${groupIndex}-${tabIndex}`;
+      pane.setAttribute("id", id);
 
-    // handle click events
-    $(".nav-tabs a").click(function (e) {
-      var tab = $(this).parent(),
-        tabIndex = tab.index(),
-        tabPanel = $(this).closest(".code-tabs"),
-        tabPane = tabPanel.find(".tab-pane").eq(tabIndex);
-      tabPanel.find(".active").removeClass("active");
-      tab.addClass("active");
-      tabPane.addClass("active");
+      const tabItem = document.createElement("li");
+      const link = document.createElement("a");
+      link.setAttribute("href", `#${id}`);
+      link.textContent = title;
+      tabItem.appendChild(link);
+      navTabs.appendChild(tabItem);
     });
 
-    // activate first tab
-    $(".nav-tabs li:first-child a").click();
+    // Handle tab click events
+    navTabs.querySelectorAll("a").forEach(function (link, index) {
+      link.addEventListener("click", function (e) {
+        e.preventDefault();
+
+        // Deactivate all tabs and panes
+        navTabs.querySelectorAll("li").forEach(li => li.classList.remove("active"));
+        tabPanes.forEach(pane => pane.classList.remove("active"));
 
+        // Activate clicked tab and corresponding pane
+        link.parentElement.classList.add("active");
+        const targetPane = tabContent.querySelector(link.getAttribute("href"));
+        if (targetPane) {
+          targetPane.classList.add("active");
+        }
+      });
+    });
+
+    // Activate the first tab by default
+    const firstLink = navTabs.querySelector("a");
+    if (firstLink) firstLink.click();
   });
+});
+
 </script>