diff --git a/docs/sql/data-types.md b/docs/sql/data-types.md deleted file mode 100644 index 3132f90..0000000 --- a/docs/sql/data-types.md +++ /dev/null @@ -1,78 +0,0 @@ -# Data Types - -## SeaTable to SQL mapping - -| SeaTable column type | SQL data type | Query result format | WHERE | GROUP BY / ORDER BY | -|:---|:---|:---|:---|:---| -| text | String | | Supported | Supported | -| long-text | String | Raw Markdown | Supported | Supported | -| number | Float | | Supported | Supported | -| single-select | String | Option name | By option name | By definition order | -| multiple-select | List of strings | Option names | By option name | See list types | -| checkbox | Boolean | | Supported | Supported | -| date | Datetime | RFC 3339 format | ISO or RFC 3339 strings | Supported | -| image | List of URLs | JSON array | See list types | See list types | -| file | JSON string | | Not supported | Not supported | -| collaborator | List of user IDs | `xxx@auth.local` | See list types | See list types | -| link to other records | List of linked rows | | See list types | See list types | -| formula | Depends on return value | | Depends on type | Depends on type | -| \_creator | String (user ID) | `xxx@auth.local` | Supported | Supported | -| \_ctime | Datetime | RFC 3339 format | ISO or RFC 3339 strings | Supported | -| \_last\_modifier | String (user ID) | `xxx@auth.local` | Supported | Supported | -| \_mtime | Datetime | RFC 3339 format | ISO or RFC 3339 strings | Supported | -| auto number | String | | Supported | Supported | -| url | String | | Supported | Supported | -| email | String | | Supported | Supported | -| duration | Float | In seconds | Supported | Supported | - -## List types - -Two categories of columns have list values: - -- **Built-in**: multiple select, image, file, collaborator, link to other records -- **Formula-based**: link formulas using `lookup`, `findmin`, or `findmax` - -### WHERE clause 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 | `IN`, `HAS ANY OF`, etc. | Follow operator rules | -| 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. diff --git a/docs/sql/index.md b/docs/sql/index.md index 08283b1..6046f14 100644 --- 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 index 3a81b88..8510f49 100644 --- 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 new file mode 100644 index 0000000..d9409d5 --- /dev/null +++ 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 new file mode 100644 index 0000000..bcc43f6 --- /dev/null +++ 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 index 9198e56..500fea7 100644 --- 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 index 3586c12..8ec722f 100644 --- 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