From 3e98a14ebdc6e7089bdf918695f5f8b9e85bdef0 Mon Sep 17 00:00:00 2001 From: nichenqin Date: Tue, 13 Oct 2026 20:50:38 +0800 Subject: [PATCH 1/4] docs: clarify query selection and data access boundaries --- skills/teable-assistant-ops/SKILL.md | 3 +- .../guides/app-builder-guide.md | 2 + .../guides/cli-reference.md | 2 + .../guides/data-query-guide.md | 37 +++++++++++++++++++ skills/teable-assistant-ops/metadata.json | 2 +- 5 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 skills/teable-assistant-ops/guides/data-query-guide.md diff --git a/skills/teable-assistant-ops/SKILL.md b/skills/teable-assistant-ops/SKILL.md index 0a00c32..b804cb3 100644 --- a/skills/teable-assistant-ops/SKILL.md +++ b/skills/teable-assistant-ops/SKILL.md @@ -32,7 +32,7 @@ A **Project** (项目 in Chinese) is called `base` in the API, with IDs starting | Module | What it solves | Entry commands | Guide to read | |--------|---------------|----------------|---------------| -| Data Query | Read records, analytics, aggregations | `record get`, `sql-query` | [cli-reference.md § Data Queries](guides/cli-reference.md#data-queries) | +| Data Query | Read records, analytics, query reuse and access boundaries | `record get`, `sql-query`; discover other installed capabilities before use | [data-query-guide.md](guides/data-query-guide.md), [CLI reference](guides/cli-reference.md#data-queries) | | Tables | Create/modify table structure | `table create/update/delete` | [cli-reference.md § Field Type Aliases](guides/cli-reference.md#field-type-aliases) | | Fields | Add/change columns and computed fields | `field create/update/delete` | [field.simple.md](api-reference/field.simple.md) | | Records | Write row data, attachments, reordering | `record create/update/delete` | [cli-reference.md § Record Operations](guides/cli-reference.md#record-operations) | @@ -64,6 +64,7 @@ A **Project** (项目 in Chinese) is called `base` in the API, with IDs starting | Aggregation (count, sum, avg) | Data Query: `sql-query` with GROUP BY | Fetch all records + compute in code | | Read records for subsequent writes | Data Query: `record get` (returns record IDs) | `sql-query` (no record IDs) | | Cross-table analytics / JOINs | Data Query: `sql-query` | Multiple `record get` calls | +| Reusable or structured data reads | Data Query: check installed CLI and target-host support in [data-query-guide.md](guides/data-query-guide.md) | Assume an internal v2 implementation is a released command or active endpoint | | One-time chart shown only in the conversation | Visualization: HTML code block | App Builder or artifact | | Durable report/chart stored in Teable | Artifacts: `artifact list` → `artifact update` or `artifact create` | App Builder | | Live dashboard / data-connected custom UI | App Builder: `app create` | HTML code block or artifact | diff --git a/skills/teable-assistant-ops/guides/app-builder-guide.md b/skills/teable-assistant-ops/guides/app-builder-guide.md index b0f7709..c1b8b23 100644 --- a/skills/teable-assistant-ops/guides/app-builder-guide.md +++ b/skills/teable-assistant-ops/guides/app-builder-guide.md @@ -99,6 +99,8 @@ teable app ai-docs # equivalent to: teable get-doc --topic app.ai By default a generated app is open. To require end-users to authenticate before accessing it, set a login config: +App login controls who can enter the app. It does not automatically make server-side data requests run with each visitor's table/row/field permissions. When users must see different records, require a verified server-side data access policy; see [query permissions and parameters](data-query-guide.md#permissions-and-parameters). + ```bash teable app login-config --app-id appXXX --login-config '{ "enabled": true, diff --git a/skills/teable-assistant-ops/guides/cli-reference.md b/skills/teable-assistant-ops/guides/cli-reference.md index 12dec71..8944910 100644 --- a/skills/teable-assistant-ops/guides/cli-reference.md +++ b/skills/teable-assistant-ops/guides/cli-reference.md @@ -39,6 +39,8 @@ Advanced types (link, lookup, rollup, formula, AI) require `field create` with o ## Data Queries +For choosing an entry, inline versus saved-query reuse, permissions and feature availability, read [Data Query Guide](data-query-guide.md). The entries below describe the released CLI surface; they do not activate an optional structured-query endpoint. + **`record get` vs `sql-query`** — if you'll write back to the same records, use `record get` (returns record IDs); for analytics or cross-table reads, use `sql-query`. - **record get** — record IDs for subsequent writes, `--search` for fuzzy search, simple pagination. Returns compact tabular output with an `id` column per row. diff --git a/skills/teable-assistant-ops/guides/data-query-guide.md b/skills/teable-assistant-ops/guides/data-query-guide.md new file mode 100644 index 0000000..ee2d72b --- /dev/null +++ b/skills/teable-assistant-ops/guides/data-query-guide.md @@ -0,0 +1,37 @@ +# Data Query Guide + +Use this guide for choosing a data-read path, reusing a query, or diagnosing a query failure. Query execution serves people, scripts, reports, integrations, and apps; it is not specific to AI or App Builder. + +## Choose a supported entry + +| Need | Choose | +|------|--------| +| Record identities for later writes, view-relative reads, simple search | `record get` | +| Cross-table joins or SQL-specific analysis | `sql-query`, following [SQL critical rules](cli-reference.md#sql-critical-rules) | +| A one-off or app-local structured read | An inline definition, **only if the installed CLI and selected host expose structured execution** | +| One managed query reused across apps, reports, or tasks | A saved reference with an explicit revision policy, **only if the host provides that query resource and execution entry** | + +For an unfamiliar capability, discover the installed command surface with `teable --help` or `teable tools list --search query`, then read the selected command's help. Backend implementation, a source PR, and a CLI version number alone do not prove that a target host has enabled a route. This skill follows the released CLI manifest; do not invent command names, query IDs, or URLs for an unavailable feature. Keep using the supported entry that fits the requested operation. + +## Structured execution, when available + +- Use the command's generated schema and help as the request authority. HTTP clients and CLI callers should use that same request/response contract, not separate hand-maintained schemas. +- Inline sends a `definition` and public `parameters`; it does not require creating a saved-query resource. Prefer it for exploratory reads or logic private to one app. The server still validates fields, authorization and parameter types and compiles the query; inline is not client-generated SQL or a permission bypass. +- A saved `reference` identifies a query and explicitly selects a pinned revision or latest. Use a pin for reproducible integrations; follow latest only when the consumer intentionally accepts future definition changes. Obtain real references through the host's authorized query-management surface, not by guessing a CRUD command. +- Query-library storage is for definitions, contracts and history, not business rows. Saving a query does not cache its result or guarantee faster execution. Do not persist every one-off read just because a library exists. +- Use stable table/field IDs and declared output aliases for structured reads. Keep database names confined to the raw SQL entry. Support for arbitrary SQL or joins in one entry does not imply support in another. + +## Permissions and parameters + +The credential's effective identity controls data access. Access to view, execute or edit a saved query is separate from access to its underlying tables, rows and fields. Sharing a definition is not permission to read as its owner. Pinning a revision freezes neither permissions nor data. + +Only public input values belong in caller parameters. Actor identity, groups, permission scope and trusted context values are resolved by the host; do not submit them as request properties or try to override a server-owned parameter. A missing trusted value requires fixing the authorized host integration, not supplying the value from the client. + +For generated apps, login controls admission to the app; it does not by itself establish viewer-specific row/field authorization for server-side data requests. Confirm the effective data identity and server-side access policy when users must see different records. See [App login](app-builder-guide.md#app-login--authentication). + +## Failure and performance decisions + +- Preserve the selected entry's documented error result. A permission denial, incompatible schema, timeout or missing endpoint is not an empty dataset. +- Do not silently replace a failed saved reference with an inline definition, or switch a failed structured request to raw SQL. That can change semantics and authorization. Diagnose the failure, then choose another entry only as an explicit supported operation. +- Compare equivalent queries, identities, row/field scopes and datasets before claiming a performance improvement. Saved references add lookup/governance work; inline avoids that lookup but retains live validation and authorization. Neither automatically creates indexes or fixes a slow SQL plan. +- For slow reads, keep projection and result limits bounded, distinguish client/metadata time from database execution, and report the measured case. Index or schema changes require a separate authorized operation; this guide grants no permission to apply them. diff --git a/skills/teable-assistant-ops/metadata.json b/skills/teable-assistant-ops/metadata.json index 7c6dae6..8f8dda7 100644 --- a/skills/teable-assistant-ops/metadata.json +++ b/skills/teable-assistant-ops/metadata.json @@ -1,5 +1,5 @@ { - "version": "1.10.0", + "version": "1.10.1", "organization": "teable", "authors": ["teable"], "tags": ["database", "teable", "no-code", "automation", "routines", "app-builder", "media", "ai-tools"], From acb5cf954f5ecb90e57676dcc802ad6b1fb3ae10 Mon Sep 17 00:00:00 2001 From: nichenqin Date: Wed, 14 Oct 2026 13:30:17 +0800 Subject: [PATCH 2/4] docs: narrow structured queries to opt-in inline execution --- skills/teable-assistant-ops/SKILL.md | 4 ++-- .../teable-assistant-ops/guides/cli-reference.md | 2 +- .../guides/data-query-guide.md | 16 +++++++--------- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/skills/teable-assistant-ops/SKILL.md b/skills/teable-assistant-ops/SKILL.md index b804cb3..03d4f57 100644 --- a/skills/teable-assistant-ops/SKILL.md +++ b/skills/teable-assistant-ops/SKILL.md @@ -32,7 +32,7 @@ A **Project** (项目 in Chinese) is called `base` in the API, with IDs starting | Module | What it solves | Entry commands | Guide to read | |--------|---------------|----------------|---------------| -| Data Query | Read records, analytics, query reuse and access boundaries | `record get`, `sql-query`; discover other installed capabilities before use | [data-query-guide.md](guides/data-query-guide.md), [CLI reference](guides/cli-reference.md#data-queries) | +| Data Query | Read records, analytics and access boundaries | `record get`, `sql-query`; discover other installed capabilities before use | [data-query-guide.md](guides/data-query-guide.md), [CLI reference](guides/cli-reference.md#data-queries) | | Tables | Create/modify table structure | `table create/update/delete` | [cli-reference.md § Field Type Aliases](guides/cli-reference.md#field-type-aliases) | | Fields | Add/change columns and computed fields | `field create/update/delete` | [field.simple.md](api-reference/field.simple.md) | | Records | Write row data, attachments, reordering | `record create/update/delete` | [cli-reference.md § Record Operations](guides/cli-reference.md#record-operations) | @@ -64,7 +64,7 @@ A **Project** (项目 in Chinese) is called `base` in the API, with IDs starting | Aggregation (count, sum, avg) | Data Query: `sql-query` with GROUP BY | Fetch all records + compute in code | | Read records for subsequent writes | Data Query: `record get` (returns record IDs) | `sql-query` (no record IDs) | | Cross-table analytics / JOINs | Data Query: `sql-query` | Multiple `record get` calls | -| Reusable or structured data reads | Data Query: check installed CLI and target-host support in [data-query-guide.md](guides/data-query-guide.md) | Assume an internal v2 implementation is a released command or active endpoint | +| Structured data reads | Data Query: check installed CLI and explicit host enablement in [data-query-guide.md](guides/data-query-guide.md) | Assume an internal v2 implementation is a released command or active endpoint | | One-time chart shown only in the conversation | Visualization: HTML code block | App Builder or artifact | | Durable report/chart stored in Teable | Artifacts: `artifact list` → `artifact update` or `artifact create` | App Builder | | Live dashboard / data-connected custom UI | App Builder: `app create` | HTML code block or artifact | diff --git a/skills/teable-assistant-ops/guides/cli-reference.md b/skills/teable-assistant-ops/guides/cli-reference.md index 8944910..7c5cdd5 100644 --- a/skills/teable-assistant-ops/guides/cli-reference.md +++ b/skills/teable-assistant-ops/guides/cli-reference.md @@ -39,7 +39,7 @@ Advanced types (link, lookup, rollup, formula, AI) require `field create` with o ## Data Queries -For choosing an entry, inline versus saved-query reuse, permissions and feature availability, read [Data Query Guide](data-query-guide.md). The entries below describe the released CLI surface; they do not activate an optional structured-query endpoint. +For choosing a read entry, inline execution, permissions and feature availability, read [Data Query Guide](data-query-guide.md). The entries below describe the released CLI surface; they do not activate an experimental structured-query endpoint. **`record get` vs `sql-query`** — if you'll write back to the same records, use `record get` (returns record IDs); for analytics or cross-table reads, use `sql-query`. diff --git a/skills/teable-assistant-ops/guides/data-query-guide.md b/skills/teable-assistant-ops/guides/data-query-guide.md index ee2d72b..6556fdd 100644 --- a/skills/teable-assistant-ops/guides/data-query-guide.md +++ b/skills/teable-assistant-ops/guides/data-query-guide.md @@ -1,6 +1,6 @@ # Data Query Guide -Use this guide for choosing a data-read path, reusing a query, or diagnosing a query failure. Query execution serves people, scripts, reports, integrations, and apps; it is not specific to AI or App Builder. +Use this guide to choose a data-read path or diagnose a query failure. Query execution serves people, scripts, reports, integrations, and apps; it is not specific to AI or App Builder. ## Choose a supported entry @@ -9,29 +9,27 @@ Use this guide for choosing a data-read path, reusing a query, or diagnosing a q | Record identities for later writes, view-relative reads, simple search | `record get` | | Cross-table joins or SQL-specific analysis | `sql-query`, following [SQL critical rules](cli-reference.md#sql-critical-rules) | | A one-off or app-local structured read | An inline definition, **only if the installed CLI and selected host expose structured execution** | -| One managed query reused across apps, reports, or tasks | A saved reference with an explicit revision policy, **only if the host provides that query resource and execution entry** | For an unfamiliar capability, discover the installed command surface with `teable --help` or `teable tools list --search query`, then read the selected command's help. Backend implementation, a source PR, and a CLI version number alone do not prove that a target host has enabled a route. This skill follows the released CLI manifest; do not invent command names, query IDs, or URLs for an unavailable feature. Keep using the supported entry that fits the requested operation. ## Structured execution, when available - Use the command's generated schema and help as the request authority. HTTP clients and CLI callers should use that same request/response contract, not separate hand-maintained schemas. -- Inline sends a `definition` and public `parameters`; it does not require creating a saved-query resource. Prefer it for exploratory reads or logic private to one app. The server still validates fields, authorization and parameter types and compiles the query; inline is not client-generated SQL or a permission bypass. -- A saved `reference` identifies a query and explicitly selects a pinned revision or latest. Use a pin for reproducible integrations; follow latest only when the consumer intentionally accepts future definition changes. Obtain real references through the host's authorized query-management surface, not by guessing a CRUD command. -- Query-library storage is for definitions, contracts and history, not business rows. Saving a query does not cache its result or guarantee faster execution. Do not persist every one-off read just because a library exists. +- The structured interface accepts an inline `definition` and optional public `parameters`. It has no saved-reference, revision or query-sharing mode. The server validates current fields, authorization and parameter types and compiles the query; inline is not client-generated SQL or a permission bypass. +- The Nest endpoint is experimental and defaults off behind `V2_DATA_QUERY_ENABLED`. A disabled host does not advertise it in public OpenAPI. Explicit host enablement and a CLI release containing the command are separate prerequisites. - Use stable table/field IDs and declared output aliases for structured reads. Keep database names confined to the raw SQL entry. Support for arbitrary SQL or joins in one entry does not imply support in another. ## Permissions and parameters -The credential's effective identity controls data access. Access to view, execute or edit a saved query is separate from access to its underlying tables, rows and fields. Sharing a definition is not permission to read as its owner. Pinning a revision freezes neither permissions nor data. +The credential's effective identity controls table, row and field access. Each execution resolves current authorization; retaining a definition in app code does not retain an earlier permission decision. -Only public input values belong in caller parameters. Actor identity, groups, permission scope and trusted context values are resolved by the host; do not submit them as request properties or try to override a server-owned parameter. A missing trusted value requires fixing the authorized host integration, not supplying the value from the client. +Only declared public input values belong in `parameters`. Parameter declarations have no `source` property. Actor identity, groups, permission scope and database routing remain host-owned; caller `contextParameters` and `reference` properties are rejected. User-field `Me` uses the authenticated execution actor, not a caller-supplied user ID. For generated apps, login controls admission to the app; it does not by itself establish viewer-specific row/field authorization for server-side data requests. Confirm the effective data identity and server-side access policy when users must see different records. See [App login](app-builder-guide.md#app-login--authentication). ## Failure and performance decisions - Preserve the selected entry's documented error result. A permission denial, incompatible schema, timeout or missing endpoint is not an empty dataset. -- Do not silently replace a failed saved reference with an inline definition, or switch a failed structured request to raw SQL. That can change semantics and authorization. Diagnose the failure, then choose another entry only as an explicit supported operation. -- Compare equivalent queries, identities, row/field scopes and datasets before claiming a performance improvement. Saved references add lookup/governance work; inline avoids that lookup but retains live validation and authorization. Neither automatically creates indexes or fixes a slow SQL plan. +- Keep a failed structured request as an explicit failure; never silently switch it to raw SQL. The entries have different capability and authorization semantics. +- Compare equivalent queries, identities, row/field scopes and datasets before claiming a performance improvement. Inline reads retain live metadata validation and authorization; they do not automatically cache results, create indexes or fix a slow SQL plan. - For slow reads, keep projection and result limits bounded, distinguish client/metadata time from database execution, and report the measured case. Index or schema changes require a separate authorized operation; this guide grants no permission to apply them. From a46c2cdde395182e6b42215ee78e0533f93a35eb Mon Sep 17 00:00:00 2001 From: nichenqin Date: Wed, 14 Oct 2026 19:04:00 +0800 Subject: [PATCH 3/4] docs: document app-local named query workflow --- .../guides/app-builder-guide.md | 7 ++++++ .../guides/cli-reference.md | 2 +- .../guides/data-query-guide.md | 22 ++++++++++++++++--- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/skills/teable-assistant-ops/guides/app-builder-guide.md b/skills/teable-assistant-ops/guides/app-builder-guide.md index c1b8b23..cc9abbf 100644 --- a/skills/teable-assistant-ops/guides/app-builder-guide.md +++ b/skills/teable-assistant-ops/guides/app-builder-guide.md @@ -42,6 +42,13 @@ teable app get-code --app-id appXXX `app get-code` writes a **read-only snapshot** to `~/.teable/refs//` (`.env*` files excluded; requires app update permission). `app list --search ` filters by name. +### Versioned named queries + +If the generated workspace contains `teable/queries.yaml`, reads belong in that manifest and are called through generated server-only `queries.getTodos(...)`-style functions. The builder must generate and live-check the candidate using the App's own credentials before saving; pages and query files share the existing App version. Do not move definitions back into page components or bypass a failed gate with SQL. See [Data Query Guide](data-query-guide.md#named-query-apps-when-available) for commands, `getTodoById`, permissions and failure handling. + +Feature availability is host-controlled and defaults off. Existing SQL apps are not silently migrated. `app get-code` remains a read-only inspection snapshot, not the live editable workspace. + + ## Key Parameters | Parameter | Required | Description | diff --git a/skills/teable-assistant-ops/guides/cli-reference.md b/skills/teable-assistant-ops/guides/cli-reference.md index 7c5cdd5..48aae9a 100644 --- a/skills/teable-assistant-ops/guides/cli-reference.md +++ b/skills/teable-assistant-ops/guides/cli-reference.md @@ -39,7 +39,7 @@ Advanced types (link, lookup, rollup, formula, AI) require `field create` with o ## Data Queries -For choosing a read entry, inline execution, permissions and feature availability, read [Data Query Guide](data-query-guide.md). The entries below describe the released CLI surface; they do not activate an experimental structured-query endpoint. +For choosing a read entry, inline execution, versioned App-local named queries, permissions and feature availability, read [Data Query Guide](data-query-guide.md). The entries below describe the released CLI surface; they do not activate an experimental structured-query endpoint. Discover manifest commands in the installed CLI before using them; scaffolded Apps can instead use their supplied standalone `teable/query-tool.mjs`. **`record get` vs `sql-query`** — if you'll write back to the same records, use `record get` (returns record IDs); for analytics or cross-table reads, use `sql-query`. diff --git a/skills/teable-assistant-ops/guides/data-query-guide.md b/skills/teable-assistant-ops/guides/data-query-guide.md index 6556fdd..3280c29 100644 --- a/skills/teable-assistant-ops/guides/data-query-guide.md +++ b/skills/teable-assistant-ops/guides/data-query-guide.md @@ -8,20 +8,36 @@ Use this guide to choose a data-read path or diagnose a query failure. Query exe |------|--------| | Record identities for later writes, view-relative reads, simple search | `record get` | | Cross-table joins or SQL-specific analysis | `sql-query`, following [SQL critical rules](cli-reference.md#sql-critical-rules) | -| A one-off or app-local structured read | An inline definition, **only if the installed CLI and selected host expose structured execution** | +| One-off structured read | Inline definition, only when the installed CLI and host expose structured execution | +| Reusable reads in a named-query App | Versioned `teable/queries.yaml` and generated server-only functions; see the workflow below | For an unfamiliar capability, discover the installed command surface with `teable --help` or `teable tools list --search query`, then read the selected command's help. Backend implementation, a source PR, and a CLI version number alone do not prove that a target host has enabled a route. This skill follows the released CLI manifest; do not invent command names, query IDs, or URLs for an unavailable feature. Keep using the supported entry that fits the requested operation. ## Structured execution, when available - Use the command's generated schema and help as the request authority. HTTP clients and CLI callers should use that same request/response contract, not separate hand-maintained schemas. -- The structured interface accepts an inline `definition` and optional public `parameters`. It has no saved-reference, revision or query-sharing mode. The server validates current fields, authorization and parameter types and compiles the query; inline is not client-generated SQL or a permission bypass. +- The transport accepts `definition`, optional public `parameters`, and optional `queryId` for observability. The full definition is always required; a name does not grant access or refer to a server-side query library. The server validates current fields, authorization and parameter types before compiling parameterized SQL. - The Nest endpoint is experimental and defaults off behind `V2_DATA_QUERY_ENABLED`. A disabled host does not advertise it in public OpenAPI. Explicit host enablement and a CLI release containing the command are separate prerequisites. - Use stable table/field IDs and declared output aliases for structured reads. Keep database names confined to the raw SQL entry. Support for arbitrary SQL or joins in one entry does not imply support in another. +## Named-query Apps, when available + +Check the actual App source first. Opted-in fresh Apps provide `teable/queries.yaml`, a generated JSON Schema, `lib/queries.ts`, and managed `teable/query-tool.mjs`. Keep existing apps on their current read path unless the user explicitly adopts named queries; restoring an app does not migrate SQL automatically. + +1. Read authorized table/field metadata and the supplied manifest schema. Keep editable definitions in `teable/queries.yaml`, not page components. The root is `schemaVersion: 1` plus `queries`; each stable name maps to `definition` and optional `result: many | one`. +2. Define functions such as `getTodos` and `getTodoById`. Single-record queries use the definition's `recordId`, optionally `{ type: parameter, name: id }`, with a declared string parameter. `result: one` requires this identity predicate; never fetch all rows to implement lookup by ID. +3. In the App workspace run `node teable/query-tool.mjs generate --live`, then `node teable/query-tool.mjs check --live`. The bundled tool uses injected `TEABLE_API_URL` / `TEABLE_APP_TOKEN` on the server; do not print them. Live validation checks schema and App permissions without reading records. Offline validation alone is not authority proof. +4. Import `queries` from `@/lib/queries` only in server-side code, then call `queries.getTodos(...)` or `queries.getTodoById({ id })`. Do not hand-edit generated code/schema or parse YAML per request. Numeric values can be strings when needed for precision; composite/computed values may remain `unknown`. +5. Keep pages, YAML and generated artifacts in the same App version. Build/save/publish gates reject invalid definitions or stale artifacts. Fix the named query and regenerate; do not delete the manifest, substitute an empty response, or fall back to SQL to bypass a failure. `one` returns `null` only for a successful zero-row result. + +The standalone managed tool does not require an installed `teable` binary. The released CLI manifest does not yet advertise named-query commands; use the supplied App runner only when it actually exists. Discover any future CLI equivalents through installed help rather than inventing command names. CLI live validation runs with its configured credential; an editor's successful PAT check does not prove the App can read the same fields. + +Names are App-local functions, not new API routes. JSON Schema describes the query language; OpenAPI describes its transport. oRPC is not required, and browser query caches do not replace backend authorization. + + ## Permissions and parameters -The credential's effective identity controls table, row and field access. Each execution resolves current authorization; retaining a definition in app code does not retain an earlier permission decision. +The credential's effective identity controls table, row and field access. Each execution resolves current authorization; retaining a definition in an App manifest or code does not retain an earlier permission decision. Only declared public input values belong in `parameters`. Parameter declarations have no `source` property. Actor identity, groups, permission scope and database routing remain host-owned; caller `contextParameters` and `reference` properties are rejected. User-field `Me` uses the authenticated execution actor, not a caller-supplied user ID. From ac792f895a98b58941a8ef2ef527edcf26a475e1 Mon Sep 17 00:00:00 2001 From: nichenqin Date: Fri, 16 Oct 2026 14:39:53 +0800 Subject: [PATCH 4/4] docs(query): document temporary inline reads --- .github/teable-cli-manifest.json | 68 +++++++++++++++++++ .../guides/data-query-guide.md | 32 ++++++++- 2 files changed, 98 insertions(+), 2 deletions(-) diff --git a/.github/teable-cli-manifest.json b/.github/teable-cli-manifest.json index c028207..c1abb68 100644 --- a/.github/teable-cli-manifest.json +++ b/.github/teable-cli-manifest.json @@ -14,6 +14,74 @@ ], "help": "Usage: teable [options] [command]\n\nTeable AI Tools CLI for operating Teable projects, tables, fields, views, records, SQL read queries,\nand related app/automation workflows with a safe read-before-write process.\n\nOptions:\n -V, --version Show CLI version\n --debug Enable debug output (verbose logging to stderr)\n -h, --help display help for command\n\nSetup:\n auth|init [options] Manage auth for teable\n config Manage project-level CLI configuration\n\nResources:\n media media operations (generate, get, cancel)\n base project operations (create, get, list, update, delete)\n table table operations (create, get, update, delete)\n field field operations (create, get, update, delete)\n record record operations (create, get, update, delete)\n view view operations (create, get, update, delete)\n app app operations (list, get-code, create, update, delete, publish,\n status, unpublish, login-config, ai-docs, ai-enable)\n automation automation operations (list, get, update, activate, setup-trigger,\n delete, test-node, delete-node, generate-script,\n generate-flowchart, get-script-input, get-runs, get-run)\n routine routine operations (create, list, get, update, activate,\n deactivate, delete, run-now, get-runs, get-run)\n authority authority operations (get, export, diff, apply, enable, disable,\n role-list, role-get, role-delete, role-duplicate)\n folder folder operations (create, update, delete, move)\n artifact artifact operations (list, create, update, get)\n scrape scrape operations (search, run, status)\n integration integration operations (connect, list, get-token)\n env env operations (list, set, update, delete)\n secret secret operations (list, set, grant, revoke, delete)\n sandbox sandbox operations (tool)\n skill skill operations (list, import-github, import-file, update)\n\nTools:\n get-node-tree [options] Get the tree structure of all nodes (tables, automations, apps,\n etc.) in a project\n search-api [options] Search available APIs by description to find the right endpoint\n get-doc [options] Get documentation for a topic\n tools Tool discovery and metadata commands\n sql-query [options] Execute SQL query on tables\n get-collaborators [options] Get collaborators in the current project with pagination and search\n get-ai-config [options] Get AI field configuration documentation with available models\n import [options] Import tabular data into Teable (analyzes by default; --table-name\n creates, --table-id appends)\n import-airtable [options] Import an Airtable base into Teable\n import-google-sheet [options] Import a Google spreadsheet into Teable\n import-status [options] Query import job status for a table\n upload-attachment [options] Upload a local file as an attachment\n call-api [options] Call any Teable API (axios-style: method, url, params, data)\n trigger-ai-fill [options] Trigger AI generation for an AI-configured field\n send-email [options] Send an email to one or more recipients (system SMTP by default, or\n --smtp for a custom transport)\n\nCommands:\n help [command] display help for command\n\nProject = API base (bse-prefixed ID). Commands use teable base and --base-id.\n\nExamples:\n teable table get --table-id tblXXXX List table metadata\n teable record get --table-id tblXXXX Query records\n teable table create --name Tasks --fields '[\"Title:text\",\"Status:sel:Todo,Done\"]'\n", "commands": [ + { + "name": "query", + "description": "query operations (schema, execute, inline, manifest-schema, validate, generate)", + "subcommands": [ + { + "name": "schema", + "summary": "Print the canonical inline query request JSON Schema offline", + "options": [{ "flags": "--pretty", "description": "Indent JSON for human readability" }] + }, + { + "name": "execute", + "summary": "Execute one inline query on a V2_DATA_QUERY_ENABLED host (default off)", + "options": [ + { "flags": "--request ", "description": "Canonical request JSON literal or @path/to/request.json", "required": true }, + { "flags": "--endpoint ", "description": "Teable API server base URL" }, + { "flags": "--token ", "description": "Personal access token" }, + { "flags": "--pretty", "description": "Indent JSON for human readability" } + ] + }, + { + "name": "inline", + "summary": "Run one temporary records query without writing App query files", + "options": [ + { "flags": "--table-id ", "description": "Stable table ID", "required": true }, + { "flags": "--select ", "description": "JSON array of projections", "required": true }, + { "flags": "--filter ", "description": "JSON filter expression" }, + { "flags": "--sort ", "description": "JSON array of sort expressions" }, + { "flags": "--parameter-definitions ", "description": "JSON map of declared parameter types" }, + { "flags": "--parameters ", "description": "JSON map of runtime parameter values" }, + { "flags": "--limit ", "description": "Maximum rows (default: 100; max: 1000)" }, + { "flags": "--offset ", "description": "Rows to skip" }, + { "flags": "--record-id ", "description": "Optional controlled record identity" }, + { "flags": "--query-id ", "description": "Optional observability name" }, + { "flags": "--endpoint ", "description": "Teable API server base URL" }, + { "flags": "--token ", "description": "Personal access token" }, + { "flags": "--pretty", "description": "Indent JSON for human readability" } + ] + }, + { + "name": "manifest-schema", + "summary": "Print the canonical app-local query manifest JSON Schema offline", + "options": [{ "flags": "--pretty", "description": "Indent JSON for human readability" }] + }, + { + "name": "validate", + "summary": "Validate a YAML/JSON query manifest, optionally against the live host", + "options": [ + { "flags": "--file ", "description": "App-local YAML or JSON query manifest", "required": true }, + { "flags": "--live", "description": "Validate schema compatibility and permissions" }, + { "flags": "--endpoint ", "description": "Teable API server base URL" }, + { "flags": "--token ", "description": "Personal access token" }, + { "flags": "--pretty", "description": "Indent JSON for human readability" } + ] + }, + { + "name": "generate", + "summary": "Validate a query manifest and atomically generate a typed server module", + "options": [ + { "flags": "--file ", "description": "App-local YAML or JSON query manifest", "required": true }, + { "flags": "--out ", "description": "Generated server-only TypeScript module", "required": true }, + { "flags": "--live", "description": "Validate schema compatibility and permissions" }, + { "flags": "--endpoint ", "description": "Teable API server base URL" }, + { "flags": "--token ", "description": "Personal access token" }, + { "flags": "--pretty", "description": "Indent JSON for human readability" } + ] + } + ] + }, { "name": "app", "description": "app operations (list, get-code, create, update, delete, publish, status, unpublish, login-config, ai-docs, ai-enable)", diff --git a/skills/teable-assistant-ops/guides/data-query-guide.md b/skills/teable-assistant-ops/guides/data-query-guide.md index 3280c29..0075bc4 100644 --- a/skills/teable-assistant-ops/guides/data-query-guide.md +++ b/skills/teable-assistant-ops/guides/data-query-guide.md @@ -8,7 +8,7 @@ Use this guide to choose a data-read path or diagnose a query failure. Query exe |------|--------| | Record identities for later writes, view-relative reads, simple search | `record get` | | Cross-table joins or SQL-specific analysis | `sql-query`, following [SQL critical rules](cli-reference.md#sql-critical-rules) | -| One-off structured read | Inline definition, only when the installed CLI and host expose structured execution | +| One-off structured read during App development | `teable query inline`, only when the installed CLI and host expose structured execution | | Reusable reads in a named-query App | Versioned `teable/queries.yaml` and generated server-only functions; see the workflow below | For an unfamiliar capability, discover the installed command surface with `teable --help` or `teable tools list --search query`, then read the selected command's help. Backend implementation, a source PR, and a CLI version number alone do not prove that a target host has enabled a route. This skill follows the released CLI manifest; do not invent command names, query IDs, or URLs for an unavailable feature. Keep using the supported entry that fits the requested operation. @@ -20,7 +20,35 @@ For an unfamiliar capability, discover the installed command surface with `teabl - The Nest endpoint is experimental and defaults off behind `V2_DATA_QUERY_ENABLED`. A disabled host does not advertise it in public OpenAPI. Explicit host enablement and a CLI release containing the command are separate prerequisites. - Use stable table/field IDs and declared output aliases for structured reads. Keep database names confined to the raw SQL entry. Support for arbitrary SQL or joins in one entry does not imply support in another. -## Named-query Apps, when available +### Temporary inline reads during App development + +Use the ephemeral records command when the AI needs to inspect live data before deciding what +belongs in the App. It builds the same canonical `definition` sent by `teable query execute` and +does not write `queries.yaml`, `lib/queries.ts`, or an App version: + +```bash +teable query inline \ + --table-id tblXXX \ + --select '[{"fieldId":"fldXXX","alias":"title"}]' \ + --filter '{"fieldId":"fldYYY","operator":"isGreaterEqual","value":10}' \ + --limit 100 +``` + +Use `--sort`, `--offset`, `--record-id`, `--parameter-definitions`, `--parameters`, and +`--query-id` as needed. The default/maximum limit is 100/1000. It is a development inspection +entry only; it must not be copied into page runtime code. `teable query execute --request @file` +remains the escape hatch for the full canonical request, including aggregate definitions. + +In an App that has `teable/queries.yaml`, runtime reads use generated `lib/queries.ts`. Do not +import or call `sqlQuery` from `@/lib/teable` as a fallback. Keep `sql-query` for legacy Apps and +one-off cross-table or SQL-specific analysis. A failed inline/named query is an explicit error, +not permission to silently retry through SQL. + +The standalone managed tool does not require an installed `teable` binary. The installed CLI may +also expose `query schema`, `query execute`, `query inline`, `query validate`, and `query generate`; +discover the actual command surface with `teable --help` before using it. CLI live validation runs +with its configured credential; an editor's successful PAT check does not prove the App can read the +same fields. Check the actual App source first. Opted-in fresh Apps provide `teable/queries.yaml`, a generated JSON Schema, `lib/queries.ts`, and managed `teable/query-tool.mjs`. Keep existing apps on their current read path unless the user explicitly adopts named queries; restoring an app does not migrate SQL automatically.