seatable · christophdb · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/docs/sql/data-types.md b/docs/sql/data-types.md
diff --git a/docs/sql/index.md b/docs/sql/index.md
@@ -26,7 +26,8 @@ SQL syntax is case insensitive. We use upper-cased keywords for readability.
 
 | Feature | Notes |
 |:---|:---|
-| `SELECT`, `INSERT`, `UPDATE`, `DELETE` | [INSERT requires Big Data storage](insert-update-delete.md) |
+| `SELECT`, `UPDATE`, `DELETE` | |
+| `INSERT` | [Requires Big Data storage](insert.md) |
 | `WHERE` with `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=` | |
 | `LIKE`, `ILIKE`, `IN`, `NOT IN`, `BETWEEN`, `IS [NOT] NULL` | |
 | `AND`, `OR`, `NOT` | |
@@ -60,12 +61,3 @@ You can use SeaTable formula syntax directly in SQL queries. A few differences f
 - Column aliases cannot be used in formulas: `abs(t.column)` is invalid
 
 For the complete list of available functions, see the [function reference](./functions.md).
-
-## Big Data storage indexes
-
-SeaTable automatically creates indexes for rows in big data storage to improve query performance. Indexed column types: text, number, date, single select, multiple select, collaborators, creator, create date, modifier, modification date.
-
-Indexes are updated when:
-
-1. The table is archived the next time
-2. A user triggers index management from the "Big data management" menu in the base
diff --git a/docs/sql/insert-update-delete.md b/docs/sql/insert-update-delete.md
@@ -1,41 +1,10 @@
-# INSERT, UPDATE, DELETE
+# UPDATE and DELETE
 
-These statements modify data in a base. Available since SeaTable version 2.7.
-
-## INSERT
-
-Appends a new row to a table. `INSERT` **only** works with bases that have [Big Data storage](https://seatable.com/help/big-data-capabilities/) enabled. Rows are inserted into big data storage.
-
-!!! warning "Enterprise subscription needed"
-
-    `INSERT` requires Big Data storage support, which is available only with an [Enterprise subscription](https://seatable.com/help/subscription-plans/#seatable-cloud-enterprise-search).
-
-For non-archived bases, use the API functions instead (e.g. [Python `append_row`](/python/objects/rows/#add-rows) or [JavaScript `appendRow`](/javascript/rows/)).
-
-### Syntax
-
-```
-INSERT INTO table_name [column_list] VALUES value_list [, ...]
-```
-
-- `column_list`: column names in parentheses. If omitted, defaults to all updatable columns.
-- `value_list`: values in parentheses, matching the column order: `(1, "text", 3.0)`
-- Multi-value columns (e.g. multiple select): use nested parentheses: `(1, "text", ("foo", "bar"))`
-- Single/multiple select values must be option **names**, not keys
-
-### Column restrictions
-
-These column types cannot be inserted: `_id`, `_ctime` (built-in), image, file, formula, link, link-formula, geolocation, auto-number, button.
-
-__Example__
-
-```
-INSERT INTO Table1 (Name, Age) VALUES ('Erika', 38)
-```
+These statements modify existing data in a base. They work with both normal and big data storage. Available since SeaTable version 2.7.
 
 ## UPDATE
 
-Updates one or multiple rows. Works with both normal and big data storage.
+Updates one or multiple rows.
 
 ### Syntax
 
@@ -51,7 +20,7 @@ UPDATE table_name SET column_name = value [, ...] [WHERE ...]
 
     The `value` in SET must be a constant (string, number, or boolean). Functions, arithmetic expressions, and column references are **not supported** in SET. They can only be used in SELECT and WHERE.
 
-The same column restrictions and multi-value rules as INSERT apply.
+The same column restrictions and multi-value rules as [INSERT](insert.md) apply.
 
 __Example__
 
@@ -65,7 +34,7 @@ UPDATE Contacts SET Adult=true, `Age group`="18+" WHERE Age>=18
 
 ## DELETE
 
-Deletes one or multiple rows. Works with both normal and big data storage.
+Deletes one or multiple rows.
 
 ### Syntax
 

diff --git a/docs/sql/insert.md b/docs/sql/insert.md
@@ -0,0 +1,32 @@
+# INSERT
+
+Appends a new row to a table via SQL.
+
+!!! warning "Big Data storage only"
+
+    `INSERT` **only** works with bases that have [Big Data storage](https://seatable.com/help/big-data-capabilities/) enabled. Rows are inserted into big data storage. This feature requires an [Enterprise subscription](https://seatable.com/help/subscription-plans/#seatable-cloud-enterprise-search).
+
+For non-archived bases, use the API functions instead (e.g. [Python `append_row`](/python/objects/rows/#add-rows) or [JavaScript `appendRow`](/javascript/rows/)).
+
+Available since SeaTable version 2.7.
+
+## Syntax
+
+```
+INSERT INTO table_name [column_list] VALUES value_list [, ...]
+```
+
+- `column_list`: column names in parentheses. If omitted, defaults to all updatable columns.
+- `value_list`: values in parentheses, matching the column order: `(1, "text", 3.0)`
+- Multi-value columns (e.g. multiple select): use nested parentheses: `(1, "text", ("foo", "bar"))`
+- Single/multiple select values must be option **names**, not keys
+
+## Column restrictions
+
+These column types cannot be inserted: `_id`, `_ctime` (built-in), image, file, formula, link, link-formula, geolocation, auto-number, button.
+
+__Example__
+
+```
+INSERT INTO Table1 (Name, Age) VALUES ('Erika', 38)
+```
diff --git a/docs/sql/limitations.md b/docs/sql/limitations.md
@@ -0,0 +1,93 @@
+# Limitations
+
+This page documents SQL-specific behavior and restrictions. For general column type definitions, see the [API column model reference](https://api.seatable.com/reference/models).
+
+## Column writability
+
+Not all column types can be written via SQL (`INSERT`, `UPDATE`). The following columns are **read-only** in SQL:
+
+| Column type | Readable | Writable | Notes |
+|:---|:---:|:---:|:---|
+| image | Yes | **No** | Use API to upload/update |
+| file | Limited | **No** | WHERE and ORDER BY not supported |
+| link | Yes | **No** | Use API to manage links |
+| link-formula | Yes | **No** | Computed from links |
+| formula | Yes | **No** | Computed value |
+| geolocation | Yes | **No** | WHERE and ORDER BY not supported; use `country()` function to query |
+| auto-number | Yes | **No** | System-managed sequence |
+| digital-sign | Limited | **No** | WHERE and ORDER BY not supported |
+| button | **No** | **No** | Not queryable |
+| \_creator, \_ctime | Yes | **No** | System-managed |
+| \_last\_modifier, \_mtime | Yes | **No** | System-managed |
+
+All other column types (text, long-text, number, single-select, multiple-select, checkbox, date, duration, rate, url, email, collaborator) are both readable and writable.
+
+## Query result formats
+
+Some column types return data in a format that differs from the REST API:
+
+| Column type | SQL result format |
+|:---|:---|
+| date, \_ctime, \_mtime | RFC 3339 string (e.g. `2025-01-03T00:00:00+02:00`) |
+| collaborator, \_creator, \_last\_modifier | Internal user ID (`xxx@auth.local`) |
+| geolocation | JSON object: `{"country_region": "..."}` or `{"lat": ..., "lng": ...}` |
+| image | JSON array of URLs |
+| long-text | Raw Markdown |
+| duration | Number in seconds |
+
+## List types
+
+Several column types contain multiple values: multiple-select, image, file, collaborator, link, and link formulas using `lookup`, `findmin`, or `findmax`.
+
+### WHERE rules for list types
+
+| Element type | Operator | Rule |
+|:---|:---|:---|
+| string | `IN`, `HAS ANY OF`, etc. | Follow operator rules |
+| string | `LIKE`, `ILIKE` | Uses first element; empty string if no element |
+| string | `IS NULL` | True when list is empty |
+| string | `=`, `!=` | Uses first element |
+| float | `=`, `!=`, `<`, `<=`, `>`, `>=`, `BETWEEN` | Uses single element; only `!=` returns true for multiple |
+| float | `IS NULL` | True when list is empty |
+| float | `+`, `-`, `*`, `/` | Uses first element |
+| datetime | Same rules as float | |
+| bool | `IS TRUE` | Uses first element; false if empty |
+| linked record | | Follows rules for the display column type |
+
+Only the first ten elements are returned in query results.
+
+### Sorting list types
+
+In `GROUP BY` / `ORDER BY`, elements are first sorted ascending within each list, then lists are compared element by element. Shorter lists sort before longer lists when all compared elements are equal.
+
+### Aggregation on list types
+
+For `MIN`, `MAX`, `SUM`, `AVG`: if the list has exactly one element, that element is used. Otherwise the row is not aggregated.
+
+## NULL values
+
+NULL represents a missing value (distinct from 0). These are treated as NULL:
+
+- Empty cells
+- Values that cannot be converted to the column type
+- Empty strings (`""`)
+- Empty lists (see list types rules)
+- Formulas that return an error
+
+### NULL in WHERE
+
+- Arithmetic on NULL returns NULL
+- `!=`, `NOT LIKE`, `NOT IN`, `NOT BETWEEN`, `HAS NONE OF`, `IS NOT TRUE`, `IS NULL` return `true` for NULL
+- `AND`, `OR`, `NOT` treat NULL as `false`
+- Aggregate functions ignore NULL values
+
+In formulas, NULL is converted to 0 or empty string.
+
+## Big Data storage indexes
+
+SeaTable automatically creates indexes for rows in big data storage to improve query performance. Indexed column types: text, number, date, single select, multiple select, collaborators, creator, create date, modifier, modification date.
+
+Indexes are updated when:
+
+1. The table is archived the next time
+2. A user triggers index management from the "Big data management" menu in the base
diff --git a/docs/sql/select.md b/docs/sql/select.md
@@ -5,7 +5,13 @@ The `SELECT` statement retrieves an optionally filtered, sorted, and grouped lis
 ## Syntax
 
 ```
-SELECT [Column List] FROM tableName [WHERE ...] [GROUP BY ...] [HAVING ...] [ORDER BY ...] [LIMIT ... OFFSET ...]
+SELECT [Column List]
+  FROM tableName
+  [WHERE ...]
+  [GROUP BY ...]
+  [HAVING ...]
+  [ORDER BY ...]
+  [LIMIT ... OFFSET ...]
 ```
 
 `[Column List]` is a comma-separated list of columns. Use `*` to retrieve all columns.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -105,6 +105,7 @@ plugins:
         'scripts/sql/functions.md': 'sql/functions.md'
         'sql/clauses.md': 'sql/select.md'
         'sql/extended-syntax.md': 'sql/index.md'
+        'sql/data-types.md': 'sql/limitations.md'
 
         # Old "Client APIs" section → new language sections
         'clients/index.md': 'index.md'
@@ -219,8 +220,9 @@ nav:
   - SQL:
       - sql/index.md
       - SELECT: sql/select.md
-      - INSERT, UPDATE, DELETE: sql/insert-update-delete.md
-      - Data Types: sql/data-types.md
+      - INSERT: sql/insert.md
+      - UPDATE, DELETE: sql/insert-update-delete.md
+      - Limitations: sql/limitations.md
       - Functions: sql/functions.md
   - Plugin Development:
       - plugins/index.md