Skip to content

Commit fe2a29f

Browse files
kay-kimkay-kim
committed
docs: create table update syntax (part 1)
1 parent c327d6d commit fe2a29f

File tree

7 files changed

+310
-65
lines changed

7 files changed

+310
-65
lines changed

‎doc/user/assets/sass/_content.scss

+5-6
Original file line numberDiff line numberDiff line change
@@ -749,9 +749,7 @@ p+p {
749749
padding: 0;
750750
border-bottom: 1px solid #9c86e0;
751751
display: flex;
752-
overflow-x: scroll;
753-
754-
padding-bottom: var(--xx-small);
752+
overflow-x: auto;
755753

756754
@media(max-width: 850px) {}
757755

@@ -760,13 +758,15 @@ p+p {
760758
margin: 0 rem(0.1);
761759
padding: 0;
762760
position: relative;
763-
bottom: -1px;
761+
764762
background: var(--gray-lightest);
763+
border-radius: 8px 8px 0 0;
764+
765765

766766
a {
767767
color: var(--body);
768768
display: block;
769-
padding: rem(0.8) rem(1.6);
769+
padding: rem(0.8) rem(1.5);
770770
font-size: rem(1.4);
771771
text-decoration: none;
772772
font-weight: 500;
@@ -787,7 +787,6 @@ p+p {
787787

788788
&.active {
789789
background: var(--bg);
790-
border-radius: 2px 2px 0 0;
791790
border: 1px solid #9c86e0;
792791
border-bottom-color: var(--bg);
793792

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

+176-28
Original file line numberDiff line numberDiff line change
@@ -9,50 +9,193 @@ menu:
99
parent: 'commands'
1010
---
1111

12-
`CREATE TABLE` defines a table that is persisted in durable storage and can be
13-
written to, updated and seamlessly joined with other tables, views or sources.
12+
`CREATE TABLE` defines a table that is persisted in durable storage. In
13+
Materialize, you can create:
1414

15-
Tables in Materialize are similar to tables in standard relational databases:
16-
they consist of rows and columns where the columns are fixed when the table is
17-
created but rows can be added to at will via [`INSERT`](../insert) statements.
15+
- User-populated tables. User-populated tables can be written to (i.e.,
16+
[`INSERT`]/[`UPDATE`]/[`DELETE`]) by the user.
1817

19-
{{< warning >}}
20-
At the moment, tables have many [known limitations](#known-limitations). In most
21-
situations, you should use [sources](/sql/create-source) instead.
22-
{{< /warning >}}
18+
- [Source-populated](/concepts/sources/) tables. Source-populated tables cannot
19+
be written to by the user; they are populated through data ingestion from a
20+
source.
2321

24-
[//]: # "TODO(morsapaes) Bring back When to use a table? once there's more
25-
clarity around best practices."
22+
Tables can be joined with other tables, materialized views, and views. Tables in
23+
Materialize are similar to tables in standard relational databases: they consist
24+
of rows and columns where the columns are fixed when the table is created.
2625

2726
## Syntax
2827

29-
{{< diagram "create-table.svg" >}}
28+
{{< tabs >}}
3029

31-
### `col_option`
30+
{{< tab "User-populated tables" >}}
3231

33-
{{< diagram "col-option.svg" >}}
32+
To create a table that users can write to (i.e., perform
33+
[`INSERT`](/sql/insert/)/[`UPDATE`](/sql/update/)/[`DELETE`](/sql/delete/)
34+
operations):
3435

35-
Field | Use
36-
------|-----
37-
**TEMP** / **TEMPORARY** | Mark the table as [temporary](#temporary-tables).
38-
_table&lowbar;name_ | A name for the table.
39-
_col&lowbar;name_ | The name of the column to be created in the table.
40-
_col&lowbar;type_ | The data type of the column indicated by _col&lowbar;name_.
41-
**NOT NULL** | Do not allow the column to contain _NULL_ values. Columns without this constraint can contain _NULL_ values.
42-
*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.
36+
```mzsql
37+
CREATE [TEMP|TEMPORARY] TABLE <table_name> (
38+
<column_name> <column_type> [NOT NULL][DEFAULT <default_expr>]
39+
[, ...]
40+
)
41+
[WITH (
42+
PARTITION BY (<column_name> [, ...]) |
43+
RETAIN HISTORY [=] FOR <duration>
44+
)]
45+
;
46+
```
47+
48+
{{% yaml-table data="syntax_options/create_table_options_user_populated" %}}
49+
50+
{{</ tab >}}
51+
52+
{{< tab "Source-populated tables (DB source)" >}}
53+
54+
To create a table from a [source](/sql/create-source/), where the source maps to
55+
an external database system:
4356

44-
### `with_options`
57+
{{< note >}}
4558

46-
{{< diagram "with-options.svg" >}}
59+
Users cannot write to source-populated tables; i.e., users cannot perform
60+
[`INSERT`](/sql/insert/)/[`UPDATE`](/sql/update/)/[`DELETE`](/sql/delete/)
61+
operations on source-populated tables.
4762

48-
| Field | Value | Description |
49-
|------------------------------------------|---------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50-
| **PARTITION BY** _columns_ | `(ident [, ident]*)` | The key by which Materialize should internally partition this durable collection. See the [partitioning guide](/transform-data/patterns/partition-by/) for restrictions on valid values and other details.
51-
| **RETAIN HISTORY FOR** _retention_period_ | `interval` | ***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`.
63+
{{</ note >}}
5264

65+
```mzsql
66+
CREATE TABLE <table_name> FROM SOURCE <source_name> (REFERENCE <ref_object>)
67+
[WITH (
68+
TEXT COLUMNS (<fq_column_name> [, ...])
69+
| EXCLUDE COLUMNS (<fq_column_name> [, ...])
70+
| PARTITION BY (<column_name> [, ...])
71+
[, ...]
72+
)]
73+
;
74+
```
75+
76+
{{% yaml-table data="syntax_options/create_table_options_source_populated_db" %}}
77+
78+
<a name="supported-db-source-types" ></a>
79+
80+
{{< tabs >}}
81+
{{< tab "Supported MySQL types">}}
82+
83+
Materialize natively supports the following MySQL types:
84+
85+
<ul style="column-count: 3">
86+
<li><code>bigint</code></li>
87+
<li><code>binary</code></li>
88+
<li><code>bit</code></li>
89+
<li><code>blob</code></li>
90+
<li><code>boolean</code></li>
91+
<li><code>char</code></li>
92+
<li><code>date</code></li>
93+
<li><code>datetime</code></li>
94+
<li><code>decimal</code></li>
95+
<li><code>double</code></li>
96+
<li><code>float</code></li>
97+
<li><code>int</code></li>
98+
<li><code>json</code></li>
99+
<li><code>longblob</code></li>
100+
<li><code>longtext</code></li>
101+
<li><code>mediumblob</code></li>
102+
<li><code>mediumint</code></li>
103+
<li><code>mediumtext</code></li>
104+
<li><code>numeric</code></li>
105+
<li><code>real</code></li>
106+
<li><code>smallint</code></li>
107+
<li><code>text</code></li>
108+
<li><code>time</code></li>
109+
<li><code>timestamp</code></li>
110+
<li><code>tinyblob</code></li>
111+
<li><code>tinyint</code></li>
112+
<li><code>tinytext</code></li>
113+
<li><code>varbinary</code></li>
114+
<li><code>varchar</code></li>
115+
</ul>
116+
117+
Replicating tables that contain **unsupported data types** is
118+
possible via the [`TEXT COLUMNS` option](#text-columns) for the
119+
following types:
120+
121+
<ul style="column-count: 1">
122+
<li><code>enum</code></li>
123+
<li><code>year</code></li>
124+
</ul>
125+
126+
The specified columns will be treated as `text`, and will thus not offer the
127+
expected MySQL type features. For any unsupported data types not listed above,
128+
use the [`EXCLUDE COLUMNS`](#exclude-columns) option.
129+
130+
{{</ tab >}}
131+
132+
{{< tab "Supported PostgreSQL types">}}
133+
Materialize natively supports the following PostgreSQL types (including the
134+
array type for each of the types):
135+
136+
<ul style="column-count: 3">
137+
<li><code>bool</code></li>
138+
<li><code>bpchar</code></li>
139+
<li><code>bytea</code></li>
140+
<li><code>char</code></li>
141+
<li><code>date</code></li>
142+
<li><code>daterange</code></li>
143+
<li><code>float4</code></li>
144+
<li><code>float8</code></li>
145+
<li><code>int2</code></li>
146+
<li><code>int2vector</code></li>
147+
<li><code>int4</code></li>
148+
<li><code>int4range</code></li>
149+
<li><code>int8</code></li>
150+
<li><code>int8range</code></li>
151+
<li><code>interval</code></li>
152+
<li><code>json</code></li>
153+
<li><code>jsonb</code></li>
154+
<li><code>numeric</code></li>
155+
<li><code>numrange</code></li>
156+
<li><code>oid</code></li>
157+
<li><code>text</code></li>
158+
<li><code>time</code></li>
159+
<li><code>timestamp</code></li>
160+
<li><code>timestamptz</code></li>
161+
<li><code>tsrange</code></li>
162+
<li><code>tstzrange</code></li>
163+
<li><code>uuid</code></li>
164+
<li><code>varchar</code></li>
165+
</ul>
166+
167+
Replicating tables that contain **unsupported data types** is possible via the
168+
[`TEXT COLUMNS` option](#text-columns). When decoded as `text`, the specified
169+
columns will not have the expected PostgreSQL type features. For example:
170+
171+
* [`enum`]: When decoded as `text`, the resulting `text` values will
172+
not observe the implicit ordering of the original PostgreSQL `enum`; instead,
173+
Materialize will sort the values as `text`.
174+
175+
* [`money`]: When decoded as `text`, the resulting `text` value
176+
cannot be cast back to `numeric` since PostgreSQL adds typical currency
177+
formatting to the output.
178+
179+
[`enum`]: https://www.postgresql.org/docs/current/datatype-enum.html
180+
[`money`]: https://www.postgresql.org/docs/current/datatype-money.html
181+
182+
{{</ tab >}}
183+
{{</ tabs >}}
184+
185+
See also [Materialize SQL data types](/sql/types/).
186+
187+
{{</ tab >}}
188+
189+
190+
{{</ tabs >}}
53191

54192
## Details
55193

194+
### Table names and column names
195+
196+
Names for tables and column(s) must follow the [naming
197+
guidelines](/sql/identifiers/#naming-restrictions).
198+
56199
### Known limitations
57200

58201
Tables do not currently support:
@@ -109,4 +252,9 @@ The privileges required to execute this statement are:
109252
## Related pages
110253

111254
- [`INSERT`](../insert)
255+
- [`CREATE SOURCE`](/sql/create-source/)
112256
- [`DROP TABLE`](../drop-table)
257+
258+
[`INSERT`]: /sql/insert/
259+
[`UPDATE`]: /sql/update/
260+
[`DELETE`]: /sql/delete/

‎doc/user/content/transform-data/patterns/partition-by.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ If you want to return results in a specific order, use an `ORDER BY` clause on y
2626

2727
## Syntax
2828

29-
The option `PARTITION BY <column list>` declares that a [materialized view](/sql/create-materialized-view/#with_options) or [table](/sql/create-table/#with_options) should be partitioned by the listed columns.
29+
The option `PARTITION BY <column list>` declares that a [materialized view](/sql/create-materialized-view/#with_options) or [table](/sql/create-table/#partition-by) should be partitioned by the listed columns.
3030
For example, a table that stores an append-only collection of events may want to partition the data by time:
3131

3232
```mzsql

‎doc/user/data/syntax_options/create_table_options_source_populated_db.yml

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
columns:
2+
- column: "Parameter"
3+
- column: "Description"
4+
rows:
5+
- "Parameter": "`<table_name>`"
6+
"Description": |
7+
8+
The name of the table to create. Names for tables must follow the [naming
9+
guidelines](/sql/identifiers/#naming-restrictions).
10+
11+
- "Parameter": "`<source_name>`"
12+
"Description": |
13+
14+
The name of the [source](/sql/create-source/) associated with the
15+
reference object from which to create the table.
16+
17+
- "Parameter": "**(REFERENCE <ref_object>)**"
18+
"Description": |
19+
20+
The name of the reference object from which to create the table. Reference
21+
objects are the names of the tables in the upstream database. You can
22+
create multiple tables from the same reference object.
23+
24+
To find the reference objects available in your
25+
[source](/sql/create-source/), you can use the following query,
26+
substituting your source name for `<source_name>`:
27+
28+
<br>
29+
30+
```mzsql
31+
SELECT refs.*
32+
FROM mz_internal.mz_source_references refs, mz_sources s
33+
WHERE s.name = '<source_name>' -- substitute with your source name
34+
AND refs.source_id = s.id;
35+
```
36+
37+
- "Parameter": "**WITH (<with_option>[,...])**"
38+
"Description": |
39+
The following `<with_option>`s are supported:
40+
41+
| Option | Description |
42+
|--------|-------------|
43+
| <a name="text-columns"></a>`TEXT COLUMNS (<fq_column_name> [, ...])` | *Optional.* If specified, decode data as `text` for the listed column(s), such as for unsupported data types. Use fully qualified column names. See also [supported types](#supported-db-source-types). |
44+
| <a name="exclude-columns"></a>`EXCLUDE COLUMNS (<fq_column_name> [, ...])` | *Optional.* If specified, exclude the listed column(s) from the table. Use fully qualified column names. |
45+
| <a name="partition-by"></a>`PARTITION BY (<column> [, ...])` | *Optional.* The key by which Materialize should internally partition the table. See the [partitioning guide](/transform-data/patterns/partition-by/) for restrictions on valid values and other details. |

‎doc/user/data/syntax_options/create_table_options_user_populated.yml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
columns:
2+
- column: "Parameter"
3+
- column: "Description"
4+
rows:
5+
- "Parameter": "**TEMP** / **TEMPORARY**"
6+
"Description": |
7+
*Optional.* If specified, mark the table as [temporary](#temporary-tables). Temporary
8+
tables are automatically dropped at the end of the SQL session and are not
9+
visible to other connections. See [temporary tables](#temporary-tables)
10+
for more details.
11+
- "Parameter": "`<table_name>`"
12+
"Description": |
13+
14+
The name of the table to create. Names for tables must follow the [naming
15+
guidelines](/sql/identifiers/#naming-restrictions).
16+
17+
- "Parameter": "`<column_name>`"
18+
"Description": |
19+
20+
The name of a column to be created in the new table. Names for columns
21+
must follow the [naming guidelines](/sql/identifiers/#naming-restrictions).
22+
23+
- "Parameter": "`<column_type>`"
24+
"Description": |
25+
26+
The type of the column. For supported types, see [SQL data types](/sql/types/).
27+
28+
- "Parameter": "**NOT NULL**"
29+
"Description": |
30+
*Optional.* If specified, disallow _NULL_ values for the column. Columns without this constraint can contain _NULL_ values.
31+
- "Parameter": "**DEFAULT <default_expr>**"
32+
"Description": |
33+
*Optional.* If specified, use the `<default_expr>` as the default value for the column. If not specified, `NULL` is used as the default value.
34+
- "Parameter": "**WITH (<with_option>[,...])**"
35+
"Description": |
36+
37+
The following `<with_option>`s are supported:
38+
39+
| Option | Description |
40+
|--------|-------------|
41+
| `PARTITION BY (<column> [, ...])` | <a name="partition-by"></a> *Optional.* The key by which Materialize should internally partition the table. See the [partitioning guide](/transform-data/patterns/partition-by/) for restrictions on valid values and other details. |
42+
| `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'`).|

0 commit comments

Comments
 (0)