Restructure sql docs

docs/index.md

@@ -8,7 +8,7 @@ This manual is for **developers** who want to:
 
 - Build external applications that communicate with SeaTable (Python, JavaScript, PHP)
 - Develop custom plugins for SeaTable
-- Look up the complete function reference of the SeaTable API libraries
+- Look up the function reference of the SeaTable client libraries (Python, JavaScript, PHP)
 
 !!! tip "Looking to write scripts inside SeaTable?"
 

docs/python/index.md

@@ -4,6 +4,10 @@ Python scripts connect to SeaTable bases with the library [seatable-api](https:/
 
 The same library is used both **inside SeaTable scripts** and in **external Python programs**. The only difference is how you authenticate. All objects and methods work identically in both contexts.
 
+!!! info "Relationship to the SeaTable API"
+
+    Every `seatable-api` method is a wrapper around the [SeaTable REST API](https://api.seatable.com). The library covers the most common base operations but not every API endpoint (e.g. admin, webhooks, or team management). For anything not covered by this library, you can call the [API](https://api.seatable.com) directly. For column type formats and data models, see the [API model reference](https://api.seatable.com/reference/models).
+
 ## Installation
 
 ```
@@ -85,9 +89,9 @@ base.auth()
             base.auth()
     ```
 
-## Base Operation Limits
+## Rate and Size Limits
 
-Python scripts rely on the [SeaTable API](https://api.seatable.com) and are subject to [rate](https://api.seatable.com/reference/limits#general-rate-limits) and [size](https://api.seatable.com/reference/limits#size-limits) limits. Tips to stay within limits:
+Since every method call is an API request, scripts are subject to [rate](https://api.seatable.com/reference/limits#general-rate-limits) and [size](https://api.seatable.com/reference/limits#size-limits) limits. Tips to stay within limits:
 
 - Be careful with operations in `for` or `while` loops
 - Use **batch operations** whenever possible:

docs/sql/functions.md

@@ -4,7 +4,7 @@ With functions you can transform, calculate, combine or merge the values of othe
 
 The functions supported in SQL are roughly the same as the set of functions supported by formulas in SeaTable. The function parameters can be numbers, strings, constants, column names or other functions. Column name cannot be an alias. The function can be classified into the following categories:
 
-!!! info "Where can functions be used?"
+!!! danger "Where can functions be used?"
     Functions can be used in `SELECT`, `WHERE`, `GROUP BY`, `HAVING`, and `ORDER BY` clauses. They are **not supported** in the `SET` clause of `UPDATE` statements or in the `VALUES` list of `INSERT` statements. Only constant values can be used there.
 
 - [Operators](#operators)

docs/sql/index.md

@@ -1,6 +1,6 @@
 # SQL
 
-SQL queries are the most powerful way to access data stored in a base. SeaTable supports `SELECT`, `INSERT`, `UPDATE`, and `DELETE` statements. SQL is not a standalone interface but is used through the [Python](../python/) or [JavaScript](../javascript/) API via `base.query()`:
+SeaTable provides an SQL interface for querying and modifying data. It supports `SELECT`, `INSERT`, `UPDATE`, and `DELETE` statements. SQL can be used from any programming language — through the [Python](../python/) and [JavaScript](../javascript/) client libraries via `base.query()`, or directly through the [REST API](https://api.seatable.com/reference/query-with-sql).
 
 === "Python"
 
@@ -14,7 +14,17 @@ SQL queries are the most powerful way to access data stored in a base. SeaTable
     const results = await base.query("SELECT * FROM Table1 LIMIT 100");
     ```
 
-SQL syntax is case insensitive. We use upper-cased keywords for readability.
+=== "API"
+
+    ```bash
+    curl -X POST \
+      'https://cloud.seatable.io/api-gateway/api/v2/dtables/{base_uuid}/sql/' \
+      -H 'Authorization: Bearer {base_token}' \
+      -H 'Content-Type: application/json' \
+      -d '{"sql": "SELECT * FROM Table1 LIMIT 100", "convert_keys": true}'
+    ```
+
+All three methods use the same SQL engine and return identical results. SQL syntax is case insensitive. We use upper-cased keywords for readability.
 
 !!! tip "New to SQL?"
 

docs/sql/insert-update-delete.md

@@ -1,6 +1,6 @@
 # UPDATE and DELETE
 
-These statements modify existing data in a base. They work with both normal and big data storage. Available since SeaTable version 2.7.
+These statements modify existing data in a base. They work with both normal and Big Data storage.
 
 ## UPDATE
 

docs/sql/insert.md

@@ -8,22 +8,17 @@ Appends a new row to a table via SQL.
 
 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 [, ...]
+INSERT INTO tableName (column1, column2, ...)
+  VALUES (value1, value2, ...)
 ```
 
-- `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"))`
+- Values must be constants (strings, numbers, booleans) — functions and expressions are **not** supported in `VALUES`
+- Multi-value columns (e.g. multiple select): use nested parentheses: `("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.
+- Not all column types can be written via SQL — see [Limitations](limitations.md#column-writability) for details
 
 __Example__
 

docs/sql/limitations.md

@@ -22,19 +22,6 @@ Not all column types can be written via SQL (`INSERT`, `UPDATE`). The following
 
 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`.
@@ -54,8 +41,6 @@ Several column types contain multiple values: multiple-select, image, file, coll
 | 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.

docs/sql/select.md

@@ -1,6 +1,6 @@
 # SELECT
 
-The `SELECT` statement retrieves an optionally filtered, sorted, and grouped list of rows from a table. Each returned row is a JSON object.
+The `SELECT` statement retrieves an optionally filtered, sorted, and grouped list of rows from a table. Each returned row is a JSON object. `SELECT` works the same way regardless of whether the table uses normal or Big Data storage.
 
 ## Syntax