pgkiln 0.74.0 → 0.75.0

package/docs/guide/19-rest-data-sources.md

@@ -15,7 +15,8 @@ Web Credentials and the Invoke API process):
   puts values of the response into items; the **`invoke_api` workflow step** does the same on the
   server, with workflow variables ([chapter 6](06-processing.md#invoke-api-steps)).
 
-Both are **Shared Components**. The server only calls hosts its administrator allows
+Both are **Shared Components**, as are **JSON sources** ([below](#json-sources-and-document-views)): forms,
+reports and grids over the documents in a `jsonb` column of your own tables. The server only calls hosts its administrator allows
 ([below](#server-configuration-and-the-allow-list)): out of the box, no outgoing request is made.
 
 Try it with the HR example: page 23 "Web services" reads the HR example's own REST module
@@ -355,6 +356,110 @@ A workflow calls a web service with an **`invoke_api` step** instead: the same k
 `variables`, `status_variable` and `response_variable` for the items, `&VAR.` for workflow
 variables and an optional `timeout` ([chapter 6](06-processing.md#invoke-api-steps)).
 
+## JSON sources and document views
+
+(Sprint 142; APEX: Shared Components → Data Sources → **JSON Sources**, and JSON Relational **Duality Views**.)
+A `jsonb` column is a single text item to a form, and one cell to a report. A **JSON source** describes the
+documents in such a column with a **data profile**, and pgkiln makes updatable views from it, so forms, reports,
+interactive grids, master-detail pages, REST (AutoREST) and MCP read and write the documents' values like columns
+of a table.
+
+### A JSON source
+
+Shared Components → Data Sources → **JSON Sources** → *Add JSON source*:
+
+- **Table and jsonb column**: a column of an ordinary table (`hr.emp.profile`), or the one document column of a
+  *table of documents* (`id`, `doc`). The table needs a primary key: the views find their row by it. The list
+  shows the json and jsonb columns of the tables your SQL Workshop connection may use (an isolated workspace: its
+  own schemas).
+- **View**: the name of the view, made in the table's schema.
+- **The view also adds and deletes rows of the table**: for a table of documents. Off (the default), the view
+  only changes the documents of existing rows; an insert or delete through it is refused.
+- **Propose from the data** reads up to 200 documents and proposes the profile: a **column** per path to a value
+  (nested objects become `office_city` for `office.city`), typed from the values it found (`integer`, `numeric`,
+  `boolean`, `date`, `timestamptz` for ISO date-times, `text`, `jsonb` for mixed or nested values), and an **array**
+  per list in the documents: a list of objects gets a column per key, a list of values (`["en", "nl"]`) one column
+  for the value itself (an empty path). Names, paths and types stay editable; columns you already named are kept.
+  A column can be **read only**.
+
+**Create views** (the source's page) makes them in one transaction with your SQL Workshop connection and records
+the statements in the [Change Log](03-builder.md#change-log); *Open in the SQL Worksheet* shows them first. After
+changing the profile, *Make the views again* drops and makes them (a view other objects depend on can't be
+dropped: the error says which). The views are ordinary database objects of your application, like the table:
+put the statements in your own migration scripts for the other environments (the source itself travels with the
+application's export as `json_sources`).
+
+For `hr.emp.profile` with `{"title": "Analyst", "since": "1987-04-19", "office": {"city": "Dallas"},
+"skills": [{"name": "SQL", "level": 5}], "badge": {"color": "blue"}}` the HR example's source EMP_PROFILE makes:
+
+| View | Columns | One row per |
+| --- | --- | --- |
+| `hr.emp_profile` | `empno`, `title`, `since` (date), `office_city`, `office_floor` (integer), `remote` (boolean) | employee |
+| `hr.emp_profile_skills` | `empno`, `row_key`, `position`, `skill`, `level` (integer) | element of `skills` |
+| `hr.emp_profile_languages` | `empno`, `row_key`, `position`, `language` | element of `languages` |
+
+- A value that doesn't read as its column's type (`"floor": "ground"`) shows **NULL** in that column instead of
+  failing the whole query (`meta.input_ok`, PostgreSQL's `pg_input_is_valid`).
+- **Writing keeps what the profile doesn't know.** An `UPDATE` of the view writes only the paths whose values
+  changed, into the row's document, in one `UPDATE` of the table (`meta.jsonb_patch`): `badge` above, or any key a
+  newer version of another program added, stays. Setting a column to NULL removes its key; a path to a nested
+  object makes the objects on the way. The key columns are never changed through the view.
+- **Arrays as rows.** An array view has the table's key, `row_key` and `position` (1, 2 …) and the element's
+  columns. `row_key` is the element's contents (an md5) and its occurrence among equal elements: it stays the same
+  when other elements are added, changed or removed, so deleting two rows of a grid in one save removes the right
+  two. An `INSERT` appends an element (the table's key column says to which row), an `UPDATE` patches one
+  (unknown keys of the element stay), a `DELETE` removes it. An element that someone changed meanwhile is no
+  longer found and the statement fails (*Reload and try again*): nothing is overwritten.
+- **Security.** The views are `security_invoker` and get the table's grants (SELECT, INSERT, UPDATE, DELETE of each
+  role that has them on the table). Their INSTEAD OF triggers (`meta.json_source_write`, `meta.json_array_write`)
+  are SECURITY INVOKER too: they write the table as the role that writes the view, so its grants and the table's
+  row level security apply, exactly as for a direct `UPDATE`.
+
+### Pages on a JSON source
+
+The views work everywhere a table does: Create Page, a form's or report's source, the interactive grid, AutoREST
+and MCP. **Create page** on the source's page makes a form on the view with a **detail grid per array** (the
+grid's master is the form's key item, `position` read only, `row_key` hidden) and their save processes; open it
+with the key in the URL, for example from a report's link. HR page 51 *Employee profiles* (Administration) is
+such a page with a report on top:
+
+```sql
+-- the report's source: hr.emp with its jsonb column
+select empno, ename, job, profile from hr.emp order by profile is null, ename
+```
+
+### JSON path columns in reports
+
+A report region's **JSON path columns** (Page Designer → the report's settings) add columns read from a json or
+jsonb column of its query, without writing the SQL: `name=column:path[:type]`, separated by `;`:
+
+```
+title=profile:title; first_skill=profile:skills.0.name; since=profile:since:date
+```
+
+A path is keys separated by dots; a number picks an element of an array (`skills.0.name`). They are columns like
+the others: search, filters, sorting, control breaks, aggregates, headings, format masks and downloads. In the
+region's JSON: `"json_columns": [{"name": "title", "column": "profile", "path": "title", "type": "text"}]`.
+
+### Document views (duality views)
+
+SQL Workshop › Table Properties → **Document view…** (or a table's ⋯ menu) makes a view with the table's key and a
+`jsonb` document per row: the row's columns and, per **child table** you tick (tables whose foreign keys reference
+it), a list of its rows without the foreign key columns:
+
+```json
+{"deptno": 10, "dname": "ACCOUNTING", "loc": "NEW YORK",
+ "emp": [{"empno": 7782, "ename": "CLARK", "job": "MANAGER", "sal": 2450}, …]}
+```
+
+Writing the document back (`update hr.dept_doc set doc = $1 where deptno = 10`, or a PUT through AutoREST on the
+view) updates the row's columns the document names, **upserts** the children it lists (by their key; one without
+a key is inserted) and **deletes** the children it leaves out. A document without the list leaves the children
+alone. An `INSERT` of a document inserts the row and its children, a `DELETE` removes the children and the row.
+Full-text and vector columns are left out of the documents. Like APEX's duality views this gives REST clients and
+MCP tools one document per business object; the trigger (`meta.json_document_write`) is SECURITY INVOKER, so the
+tables' grants and row level security apply to every row it touches.
+
 ## Export, import and application files
 
 The export ([chapter 3](03-builder.md#export-format)) has two new sections: `web_credentials`
@@ -363,6 +468,8 @@ synchronisation settings, without the synchronisation's next and last run; an im
 the schedule off). In the directory format they are
 `shared/web-credentials/` and `shared/rest-sources/` ([chapter 18](18-cli.md)). Regions, lists of
 values, processes and workflow steps refer to sources and credentials by name, so nothing needs remapping.
+JSON sources are part of the application (`json_sources`, in `app.yaml` of the directory format); their
+views are not: they belong to your schema's migration scripts, like the table.
 
 ## Security notes
 

package/examples/hr/hr_77_json_sources.sql

@@ -0,0 +1,174 @@
+-- =====================================================================
+-- HR example, part 77: a JSON source (sprint 142, AP-8; migration 142;
+-- docs/guide/19-rest-data-sources.md "JSON sources")
+--
+-- hr.emp gets a jsonb column "profile": a document per employee with a
+-- job title, a start date, an office, skills (objects) and languages
+-- (values), and keys no form knows about (e.g. "badge"). JSON source
+-- EMP_PROFILE (Shared Components → JSON sources) describes it, and the
+-- three views below are what its "Create views" makes:
+--
+--   hr.emp_profile            empno and a column per path (title, since,
+--                             office_city, office_floor, remote);
+--   hr.emp_profile_skills     a row per skill: empno, row_key, position,
+--                             skill, level;
+--   hr.emp_profile_languages  a row per language.
+--
+-- Saving the form changes only the paths whose values changed, so "badge"
+-- and anything else in the document stay. Page 51 "Employee profiles"
+-- (Administration): a report of the employees with JSON path columns
+-- (title and first skill read from the document), a form on
+-- hr.emp_profile and the skills and languages as detail grids.
+-- =====================================================================
+
+alter table hr.emp add column if not exists profile jsonb
+  check (profile is null or jsonb_typeof(profile) = 'object');
+comment on column hr.emp.profile is 'Profile document (JSON source EMP_PROFILE): title, since, office {city, floor}, remote, skills [{name, level}], languages []';
+
+update hr.emp e set profile = p.doc::jsonb
+  from (values
+  (7839, '{"title": "Chief executive", "since": "1981-11-17", "office": {"city": "New York", "floor": 30}, "remote": false,
+           "skills": [{"name": "Strategy", "level": 5}, {"name": "Negotiation", "level": 4}], "languages": ["en", "fr"],
+           "badge": {"color": "gold", "printed": "2024-01-08"}}'),
+  (7698, '{"title": "Sales manager", "since": "1981-05-01", "office": {"city": "Chicago", "floor": 12}, "remote": false,
+           "skills": [{"name": "Sales", "level": 5}, {"name": "Coaching", "level": 3, "certified": true}], "languages": ["en", "es"]}'),
+  (7782, '{"title": "Accounting manager", "since": "1981-06-09", "office": {"city": "New York", "floor": 28},
+           "skills": [{"name": "Accounting", "level": 5}, {"name": "SQL", "level": 3}], "languages": ["en"]}'),
+  (7566, '{"title": "Research manager", "since": "1981-04-02", "office": {"city": "Dallas", "floor": 4}, "remote": true,
+           "skills": [{"name": "PostgreSQL", "level": 5}, {"name": "Statistics", "level": 4}], "languages": ["en", "de", "nl"],
+           "badge": {"color": "blue"}}'),
+  (7788, '{"title": "Analyst", "since": "1987-04-19", "office": {"city": "Dallas"}, "remote": true,
+           "skills": [{"name": "SQL", "level": 5}, {"name": "TypeScript", "level": 3}], "languages": ["en"]}')
+  ) as p (empno, doc)
+ where e.empno = p.empno and e.profile is null;
+
+-- the JSON source (the builder writes this list; it travels with the application's export)
+update meta.app set json_sources = json_sources || $j$[{"name": "EMP_PROFILE",
+  "description": "The employee profile (hr.emp.profile): job title, office, skills and languages",
+  "schema": "hr", "table": "emp", "key": ["empno"], "column": "profile", "view": "emp_profile",
+  "columns": [{"name": "title", "path": ["title"], "type": "text"}, {"name": "since", "path": ["since"], "type": "date"},
+              {"name": "office_city", "path": ["office", "city"], "type": "text"},
+              {"name": "office_floor", "path": ["office", "floor"], "type": "integer"},
+              {"name": "remote", "path": ["remote"], "type": "boolean"}],
+  "arrays": [{"name": "skills", "path": ["skills"], "view": "emp_profile_skills",
+              "columns": [{"name": "skill", "path": ["name"], "type": "text"}, {"name": "level", "path": ["level"], "type": "integer"}]},
+             {"name": "languages", "path": ["languages"], "view": "emp_profile_languages",
+              "columns": [{"name": "language", "path": [], "type": "text"}]}]}]$j$::jsonb
+ where alias = 'hr' and not json_sources @> '[{"name": "EMP_PROFILE"}]';
+
+-- the views, as Shared Components → JSON sources → Create views makes them
+create view hr.emp_profile with (security_invoker = true) as
+select t.empno,
+       t.profile #>> array['title'] as title,
+       case when meta.input_ok(t.profile #>> array['since'], 'date') then (t.profile #>> array['since'])::date end as since,
+       t.profile #>> array['office', 'city'] as office_city,
+       case when meta.input_ok(t.profile #>> array['office', 'floor'], 'integer') then (t.profile #>> array['office', 'floor'])::integer end as office_floor,
+       case when meta.input_ok(t.profile #>> array['remote'], 'boolean') then (t.profile #>> array['remote'])::boolean end as remote
+  from hr.emp t;
+
+comment on view hr.emp_profile is 'JSON source EMP_PROFILE of application hr: hr.emp.profile (made by pgkiln; Shared Components → JSON sources makes it again)';
+
+create trigger json_source_write
+  instead of insert or update or delete on hr.emp_profile
+  for each row execute function meta.json_source_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","rows":false,"columns":[{"name":"title","path":["title"]},{"name":"since","path":["since"]},{"name":"office_city","path":["office","city"]},{"name":"office_floor","path":["office","floor"]},{"name":"remote","path":["remote"]}]}');
+
+grant delete, insert, select, update on hr.emp_profile to "hr_app";
+
+create view hr.emp_profile_skills with (security_invoker = true) as
+select t.empno,
+       k.key as row_key,
+       k.idx + 1 as position,
+       e.v #>> array['name'] as skill,
+       case when meta.input_ok(e.v #>> array['level'], 'integer') then (e.v #>> array['level'])::integer end as level
+  from hr.emp t
+  cross join lateral meta.jsonb_element_keys(t.profile #> array['skills']) k
+  cross join lateral (select (t.profile #> array['skills']) -> k.idx as v) e;
+
+comment on view hr.emp_profile_skills is 'JSON source EMP_PROFILE of application hr: the array skills of hr.emp.profile, one row per element (made by pgkiln)';
+
+create trigger json_source_write
+  instead of insert or update or delete on hr.emp_profile_skills
+  for each row execute function meta.json_array_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","array":["skills"],"row_key":"row_key","position":"position","columns":[{"name":"skill","path":["name"]},{"name":"level","path":["level"]}]}');
+
+grant delete, insert, select, update on hr.emp_profile_skills to "hr_app";
+
+create view hr.emp_profile_languages with (security_invoker = true) as
+select t.empno,
+       k.key as row_key,
+       k.idx + 1 as position,
+       e.v #>> array[]::text[] as language
+  from hr.emp t
+  cross join lateral meta.jsonb_element_keys(t.profile #> array['languages']) k
+  cross join lateral (select (t.profile #> array['languages']) -> k.idx as v) e;
+
+comment on view hr.emp_profile_languages is 'JSON source EMP_PROFILE of application hr: the array languages of hr.emp.profile, one row per element (made by pgkiln)';
+
+create trigger json_source_write
+  instead of insert or update or delete on hr.emp_profile_languages
+  for each row execute function meta.json_array_write('{"name":"EMP_PROFILE","schema":"hr","table":"emp","key":["empno"],"column":"profile","array":["languages"],"row_key":"row_key","position":"position","columns":[{"name":"language","path":[]}]}');
+
+grant delete, insert, select, update on hr.emp_profile_languages to "hr_app";
+
+-- ---------------------------------------------------------------- page 51
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 51, 'Employee profiles', 'Employee profiles', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, source, table_name, pk_column, pk_item, condition, config)
+select p.id, r.seq, r.title, r.type, r.cols, r.source, r.table_name, r.pk_column, r.pk_item, r.condition, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'Employees', 'report', 12,
+   'select empno, ename, job, profile from hr.emp order by profile is null, ename', null, null, null, null,
+   '{"hidden": ["profile"], "headings": {"empno": "No.", "ename": "Name", "job": "Job", "title": "Title (profile)", "first_skill": "First skill", "since": "Since"},
+     "json_columns": [{"name": "title", "column": "profile", "path": "title", "type": "text"},
+                      {"name": "first_skill", "column": "profile", "path": "skills.0.name", "type": "text"},
+                      {"name": "since", "column": "profile", "path": "since", "type": "date"}],
+     "link": {"page": 51, "column": "empno", "items": {"P51_EMPNO": "#empno#"}}, "page_size": 5}'),
+  (20, 'Profile', 'form', 12, null, 'hr.emp_profile', 'empno', 'P51_EMPNO', ':P51_EMPNO is not null', '{}'),
+  (30, 'Skills', 'grid', 8,
+   'select empno, row_key, position, skill, level
+  from hr.emp_profile_skills
+ where empno::text = :P51_EMPNO
+ order by position', 'hr.emp_profile_skills', 'row_key', null, ':P51_EMPNO is not null',
+   '{"master": {"item": "P51_EMPNO", "column": "empno"}, "readonly": ["position"], "layout": {"hidden": ["empno", "row_key"]},
+     "headings": {"position": "#", "skill": "Skill", "level": "Level (1-5)"}, "columns": {"skill": {"required": true}}, "row_actions": {"delete": true}}'),
+  (40, 'Languages', 'grid', 4,
+   'select empno, row_key, position, language
+  from hr.emp_profile_languages
+ where empno::text = :P51_EMPNO
+ order by position', 'hr.emp_profile_languages', 'row_key', null, ':P51_EMPNO is not null',
+   '{"master": {"item": "P51_EMPNO", "column": "empno"}, "readonly": ["position"], "layout": {"hidden": ["empno", "row_key"]},
+     "headings": {"position": "#", "language": "Language"}, "row_actions": {"delete": true}}')
+  ) as r (seq, title, type, cols, source, table_name, pk_column, pk_item, condition, config)
+ where a.alias = 'hr' and p.page_no = 51;
+
+insert into meta.item (page_id, region_id, seq, name, label, type, source_column)
+select p.id, r.id, i.seq, i.name, i.label, i.type, i.col
+  from meta.page p join meta.app a on a.id = p.app_id
+  join meta.region r on r.page_id = p.id and r.title = 'Profile', (values
+  (10, 'P51_EMPNO', 'Employee', 'hidden', 'empno'),
+  (20, 'P51_TITLE', 'Title', 'text', 'title'),
+  (30, 'P51_SINCE', 'Since', 'date', 'since'),
+  (40, 'P51_OFFICE_CITY', 'Office city', 'text', 'office_city'),
+  (50, 'P51_OFFICE_FLOOR', 'Office floor', 'number', 'office_floor'),
+  (60, 'P51_REMOTE', 'Works remotely', 'switch', 'remote')
+  ) as i (seq, name, label, type, col)
+ where a.alias = 'hr' and p.page_no = 51;
+
+insert into meta.button (page_id, region_id, seq, name, label, action, hot)
+select p.id, r.id, 10, 'SAVE', 'Apply Changes', 'submit', true
+  from meta.page p join meta.app a on a.id = p.app_id
+  join meta.region r on r.page_id = p.id and r.title = 'Profile'
+ where a.alias = 'hr' and p.page_no = 51;
+
+insert into meta.process (page_id, region_id, seq, name, type, point)
+select p.id, r.id, r.seq, case r.type when 'form' then 'Process form Profile' else 'Save ' || r.title end,
+       case r.type when 'form' then 'form_dml' else 'grid_dml' end, 'submit'
+  from meta.page p join meta.app a on a.id = p.app_id
+  join meta.region r on r.page_id = p.id and r.type in ('form', 'grid')
+ where a.alias = 'hr' and p.page_no = 51;
+
+insert into meta.nav_entry (app_id, parent_id, seq, label, icon, target_page)
+select a.id, n.id, 80, 'Employee profiles', 'id-card', 51
+  from meta.app a join meta.nav_entry n on n.app_id = a.id and n.label = 'Administration' and n.parent_id is null
+ where a.alias = 'hr';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/src/app.ts

@@ -27,6 +27,8 @@ import { ldapRoutes } from './builder/ldap.ts';
 import { aiRoutes } from './builder/ai.ts';
 import { aiAgentRoutes } from './builder/ai-agents.ts';
 import { vectorProviderRoutes } from './builder/vector-providers.ts';
+import { jsonSourceRoutes } from './builder/json-sources.ts';
+import { documentViewRoutes } from './builder/document-view.ts';
 import { mailRoutes } from './builder/mail.ts';
 import { backupRoutes } from './builder/backups.ts';
 import { availabilityRoutes } from './builder/availability.ts';
@@ -252,6 +254,9 @@ export async function buildApp(opts: { logger?: boolean } = {}) {
   await app.register(aiAgentRoutes);
   // (sprint 136, AP-1) vector providers: Shared Components and Workspace utilities
   await app.register(vectorProviderRoutes);
+  // (sprint 142, AP-8) JSON sources (Shared Components) and document views (Table Properties)
+  await app.register(jsonSourceRoutes);
+  await app.register(documentViewRoutes);
   await app.register(mailRoutes);
   await app.register(backupRoutes);
   await app.register(availabilityRoutes);

package/src/builder/document-view.ts

@@ -0,0 +1,117 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import { joinStatements, recordChanges } from '../changelog.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { childTables, documentViewDdl, ident, NAME, primaryKey, tableGrants } from '../json-sources.ts';
+import { clientIp, logActivity } from '../session.ts';
+import { readTable } from '../tabledef.ts';
+import { clearCompletions } from './code-editor.ts';
+import { tr } from './i18n.ts';
+import { SYSTEM_SCHEMAS } from './object-browser.ts';
+import { back, BASE, csrf, developer, flash, send, shell, workshopTabs, type Body, type Req } from './ui.ts';
+import { currentWorkspace, usableSchemas, workshopDb } from './workspaces.ts';
+
+// (sprint 142, AP-8; APEX: JSON Relational Duality Views) SQL Workshop › Table Properties › Document view: a view
+// with the table's key and a jsonb document of each row with lists of its child rows (tables whose foreign keys
+// reference it, the developer picks them). The view is security_invoker; its INSTEAD OF trigger
+// (meta.json_document_write, migration 142) writes a document back: the row's columns it names, the children it lists
+// (updated by key, or inserted), and deletes the children it leaves out. REST (AutoREST on the view) and MCP read and
+// write whole documents. Preview, Apply (one transaction with the workshop's connection, in the Change Log) and Open
+// in the worksheet, as Add full-text search. Names come from the catalog.
+
+async function page(req: Req, reply: FastifyReply) {
+  const s = await developer(req, reply);
+  if (!s) return;
+  const tx = tr(s);
+  const db = await workshopDb(s);
+  const isPost = req.method === 'POST';
+  const b: Body = (isPost ? req.body : req.query) ?? {};
+  const ref = String(b.o ?? '');
+  const t = ref ? await readTable(db, ref) : null;
+  const schemas = (await usableSchemas(db)).filter((n) => !SYSTEM_SCHEMAS.includes(n));
+  if (!t || !schemas.includes(t.schema)) return reply.code(404).send('Not found');
+  const table = `${ident(t.schema)}.${ident(t.name)}`;
+  const key = await primaryKey(db, t.schema, t.name);
+  const children = (await childTables(db, t.schema, t.name)).filter((c) => schemas.includes(c.schema));
+  // columns a document leaves out: full-text and vector columns (generated or kept by triggers)
+  const omitOf = async (schema: string, name: string) => (await db.query<{ n: string }>(
+    `select a.attname as n from pg_attribute a join pg_class c on c.oid = a.attrelid join pg_namespace s on s.oid = c.relnamespace join pg_type ty on ty.oid = a.atttypid
+      where s.nspname = $1 and c.relname = $2 and a.attnum > 0 and not a.attisdropped and ty.typname in ('tsvector', 'vector', 'halfvec', 'sparsevec')`, [schema, name])).rows.map((r) => r.n);
+  const view = isPost ? String(b.view ?? '').trim() : `${t.name}_doc`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').slice(0, 63);
+  const document = isPost ? String(b.document ?? '').trim() : 'doc';
+  const picked = new Set<number>();
+  if (isPost) children.forEach((c, i) => b[`c.${i}.use`] === 'on' && b[`c.${i}.name`] === `${c.schema}.${c.table}` && picked.add(i));
+  else children.forEach((_, i) => picked.add(i));
+
+  const errors: string[] = [];
+  let ddl: string[] = [];
+  if (!key.length) errors.push(`${table} has no primary key: a document view finds its rows by it.`);
+  if (isPost && !errors.length) {
+    for (const n of [view, document]) if (!NAME.test(n)) errors.push(tx('fts.bad_name', { name: n }));
+    if (key.includes(document)) errors.push(`The document column may not have the name of a key column (${document}).`);
+    if (NAME.test(view) && (await db.one('select 1 as x from pg_class where relnamespace = $1::regnamespace and relname = $2', [ident(t.schema), view]))) errors.push(tx('fts.exists', { name: view }));
+    if (!errors.length) {
+      const kids = [];
+      for (const i of picked) kids.push({ ...children[i], omit: await omitOf(children[i].schema, children[i].table) });
+      ddl = documentViewDdl({ schema: t.schema, table: t.name, key, view, document, children: kids, omit: await omitOf(t.schema, t.name), grants: await tableGrants(db, t.schema, t.name) });
+    }
+    if (ddl.length && b.mode === 'worksheet') {
+      s.state.__SQLDRAFT = `${ddl.join(';\n\n')};`;
+      flash(s, tx('te.review'));
+      return back(reply, s, `${BASE}/sql/worksheet`);
+    }
+    if (ddl.length && b.mode === 'apply') {
+      const c = await db.pool.connect();
+      let failed = '';
+      try {
+        await c.query('begin');
+        for (const x of ddl) await c.query(x);
+        await c.query('commit');
+      } catch (e) {
+        failed = (e as Error).message;
+        await c.query('rollback').catch(() => {});
+      } finally {
+        c.release(true);
+      }
+      await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), detail: ddl.join(';\n').slice(0, 2000) });
+      clearCompletions();
+      if (!failed) {
+        await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'table', defaultSchema: t.schema, statements: [joinStatements(ddl)] });
+        flash(s, `The document view ${t.schema}.${view} is made.`);
+        return back(reply, s, `${BASE}/sql/objects/table?${new URLSearchParams({ o: `${ident(t.schema)}.${ident(view)}` })}`);
+      }
+      errors.push(`${tx('te.nothing_changed')}: ${failed}`);
+    }
+  }
+
+  const title = `${tx('docv.add')}: ${table}`;
+  const form: Raw = key.length ? html`<form method="post" action="${BASE}/sql/objects/document" class="fts-form">${csrf(s)}
+      <input type="hidden" name="o" value="${table}">
+      <fieldset class="prop-group"><legend>Child tables in the document</legend>
+        ${children.length ? html`<div class="table-wrap"><table class="report"><thead><tr><th scope="col">${tx('fts.include')}</th><th scope="col">Table</th><th scope="col">List in the document</th><th scope="col">Foreign key</th></tr></thead><tbody>
+          ${children.map((c, i) => html`<tr><td class="te-c"><input type="hidden" name="c.${i}.name" value="${c.schema}.${c.table}"><input type="checkbox" id="dv-c${i}" name="c.${i}.use"${picked.has(i) ? raw(' checked') : ''}></td>
+            <td><label for="dv-c${i}">${c.schema}.${c.table}</label></td><td><code>${c.name}</code></td><td><code>${c.fk.map(([col, p]) => `${col} → ${p}`).join(', ')}</code></td></tr>`)}
+          </tbody></table></div>` : html`<p class="muted">No other table references ${table}: the document is the row alone.</p>`}
+        <small class="help">Each child row is an object in its list, without the foreign key columns. Writing a document updates the children it lists by their key, inserts the ones without a key, and deletes the ones it leaves out; a document without the list leaves the children alone.</small></fieldset>
+      <div class="form-grid u-mt1">
+        <div class="field"><label class="label" for="dv-view">View</label><input id="dv-view" name="view" value="${view}" required autocomplete="off" spellcheck="false" class="code"></div>
+        <div class="field"><label class="label" for="dv-doc">Document column</label><input id="dv-doc" name="document" value="${document}" required autocomplete="off" spellcheck="false" class="code"></div>
+      </div>
+      ${ddl.length ? html`<h2>DDL</h2><pre class="source te-ddl" data-code-view="sql" tabindex="0" aria-label="DDL">${ddl.map((x) => `${x};`).join('\n\n')}</pre>` : ''}
+      <div class="buttons te-buttons">
+        <button class="btn" name="mode" value="preview">${icon('eye')} ${tx('te.preview')}</button>
+        <button class="btn btn-hot" name="mode" value="apply">${icon('check')} ${tx('te.apply')}</button>
+        <button class="btn" name="mode" value="worksheet">${icon('code')} ${tx('te.open_ws')}</button>
+        <a class="btn" href="${BASE}/sql/objects/table?${new URLSearchParams({ o: table })}">${tx('common.cancel')}</a>
+      </div></form>` : html``;
+  const main = html`<h1 class="u-mb1">${title}</h1>${workshopTabs('objects', s)}
+    <p class="muted">A document view shows each row of ${table} with its child rows as one JSON document, like an Oracle JSON Relational Duality View. Reports, REST (AutoREST on the view) and MCP read whole documents; an update of the document column writes the row and its children back in one statement. The table's row level security and grants apply (the view is security_invoker and gets the table's grants).</p>
+    ${errors.length ? html`<div class="alert alert-error" role="alert"><ul>${errors.map((e) => html`<li>${e}</li>`)}</ul></div>` : ''}
+    ${form}`;
+  return send(reply, s, shell(s, title, [['SQL Workshop', `${BASE}/sql`], [tx('ob.title'), `${BASE}/sql/objects`], [tx('te.title_table', { table }), `${BASE}/sql/objects/table?${new URLSearchParams({ o: table })}`], [tx('docv.add')]], main, 'sql'));
+}
+
+export async function documentViewRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/sql/objects/document`, page);
+  app.post(`${BASE}/sql/objects/document`, page);
+}

package/src/builder/i18n/de.ts

@@ -1077,6 +1077,7 @@ export const de: BuilderMessages = {
   'fts.added': "Volltextsuche zu {table} hinzugefügt: Spalte {column} mit Index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Vektorspalte hinzufügen",
+  'docv.add': "Dokumentansicht",
   'vec.title': "Vektorspalte für {table}",
   'vec.intro': "Fügt eine Embedding-Spalte vector(n) hinzu (n: die Dimensionen des Vektoranbieters), einen HNSW-Index für die Distanz und einen Trigger, der eine Zeile neu einbettet, wenn sich ihre Quellspalten ändern. Eine Suchkonfiguration vom Typ vector oder hybrid oder das Retrieve-Werkzeug eines KI-Agenten findet Zeilen dann nach Bedeutung. Die vorhandenen Zeilen werden sofort für ihre Embeddings eingereiht.",
   'vec.existing': "Vektorspalten jetzt",

package/src/builder/i18n/en.ts

@@ -1081,6 +1081,7 @@ export const en = {
   'fts.added': "Added full-text search to {table}: column {column} with index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Add vector column",
+  'docv.add': "Document view",
   'vec.title': "Vector column on {table}",
   'vec.intro': "Adds an embedding column vector(n) (n: the vector provider's dimensions), an HNSW index for the distance, and a trigger that re-embeds a row when its source columns change. A search configuration of type vector or hybrid, or an AI agent's Retrieve tool, then finds rows by meaning. The rows there are now are queued for their embeddings at once.",
   'vec.existing': "Vector columns now",

package/src/builder/i18n/es.ts

@@ -1077,6 +1077,7 @@ export const es: BuilderMessages = {
   'fts.added': "Búsqueda de texto completo añadida a {table}: columna {column} con el índice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Añadir columna vectorial",
+  'docv.add': "Vista de documento",
   'vec.title': "Columna vectorial en {table}",
   'vec.intro': "Añade una columna de embedding vector(n) (n: las dimensiones del proveedor de vectores), un índice HNSW para la distancia y un disparador que vuelve a calcular el embedding de una fila cuando cambian sus columnas de origen. Una configuración de búsqueda de tipo vector o hybrid, o la herramienta Retrieve de un agente de IA, encuentra entonces las filas por su significado. Las filas que ya existen se ponen en cola enseguida para sus embeddings.",
   'vec.existing': "Columnas vectoriales actuales",

package/src/builder/i18n/fr.ts

@@ -1077,6 +1077,7 @@ export const fr: BuilderMessages = {
   'fts.added': "Recherche plein texte ajoutée à {table} : colonne {column} avec l'index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Ajouter une colonne vectorielle",
+  'docv.add': "Vue document",
   'vec.title': "Colonne vectorielle sur {table}",
   'vec.intro': "Ajoute une colonne d'embedding vector(n) (n : les dimensions du fournisseur de vecteurs), un index HNSW pour la distance et un déclencheur qui recalcule l'embedding d'une ligne quand ses colonnes sources changent. Une configuration de recherche de type vector ou hybrid, ou l'outil Retrieve d'un agent IA, trouve alors les lignes par leur sens. Les lignes existantes sont mises en file d'attente tout de suite pour leurs embeddings.",
   'vec.existing': "Colonnes vectorielles actuelles",

package/src/builder/i18n/it.ts

@@ -1077,6 +1077,7 @@ export const it: BuilderMessages = {
   'fts.added': "Ricerca full-text aggiunta a {table}: colonna {column} con l'indice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Aggiungi colonna vettoriale",
+  'docv.add': "Vista documento",
   'vec.title': "Colonna vettoriale su {table}",
   'vec.intro': "Aggiunge una colonna di embedding vector(n) (n: le dimensioni del provider di vettori), un indice HNSW per la distanza e un trigger che ricalcola l'embedding di una riga quando cambiano le sue colonne di origine. Una configurazione di ricerca di tipo vector o hybrid, o lo strumento Retrieve di un agente IA, trova allora le righe per significato. Le righe già presenti vengono messe subito in coda per i loro embedding.",
   'vec.existing': "Colonne vettoriali attuali",

package/src/builder/i18n/ja.ts

@@ -1077,6 +1077,7 @@ export const ja: BuilderMessages = {
   'fts.added': "{table} に全文検索を追加しました：列 {column}、索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "ベクトル列を追加",
+  'docv.add': "ドキュメント・ビュー",
   'vec.title': "{table} のベクトル列",
   'vec.intro': "埋め込み列 vector(n)（n はベクトル・プロバイダの次元数）、距離用の HNSW 索引、およびソース列が変わったときに行を再埋め込みするトリガーを追加します。その後、検索タイプ vector または hybrid の検索構成や AI エージェントの Retrieve ツールで、意味によって行を検索できます。既存の行はすぐに埋め込みのキューに入れられます。",
   'vec.existing': "現在のベクトル列",

package/src/builder/i18n/ko.ts

@@ -1077,6 +1077,7 @@ export const ko: BuilderMessages = {
   'fts.added': "{table}에 전체 텍스트 검색을 추가했습니다: 열 {column}, 인덱스 {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "벡터 열 추가",
+  'docv.add': "문서 뷰",
   'vec.title': "{table}의 벡터 열",
   'vec.intro': "임베딩 열 vector(n)(n: 벡터 공급자의 차원 수), 거리용 HNSW 인덱스, 그리고 소스 열이 바뀌면 행을 다시 임베딩하는 트리거를 추가합니다. 그러면 검색 유형 vector 또는 hybrid의 검색 구성이나 AI 에이전트의 Retrieve 도구가 의미로 행을 찾습니다. 지금 있는 행은 바로 임베딩 대기열에 들어갑니다.",
   'vec.existing': "현재 벡터 열",

package/src/builder/i18n/nl.ts

@@ -1077,6 +1077,7 @@ export const nl: BuilderMessages = {
   'fts.added': "Volledige-tekstzoeken toegevoegd aan {table}: kolom {column} met index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Vectorkolom toevoegen",
+  'docv.add': "Documentview",
   'vec.title': "Vectorkolom op {table}",
   'vec.intro': "Voegt een embeddingkolom vector(n) toe (n: de dimensies van de vectorprovider), een HNSW-index voor de afstand, en een trigger die een rij opnieuw embedt als de bronkolommen veranderen. Een zoekconfiguratie van het type vector of hybrid, of de Retrieve-tool van een AI-agent, vindt rijen dan op betekenis. De rijen die er nu zijn, komen meteen in de wachtrij voor hun embeddings.",
   'vec.existing': "Vectorkolommen nu",

package/src/builder/i18n/pt.ts

@@ -1077,6 +1077,7 @@ export const pt: BuilderMessages = {
   'fts.added': "Pesquisa de texto integral adicionada a {table}: coluna {column} com o índice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Adicionar coluna vetorial",
+  'docv.add': "Vista de documento",
   'vec.title': "Coluna vetorial em {table}",
   'vec.intro': "Adiciona uma coluna de embedding vector(n) (n: as dimensões do fornecedor de vetores), um índice HNSW para a distância e um gatilho que recalcula o embedding de uma linha quando as colunas de origem mudam. Uma configuração de pesquisa do tipo vector ou hybrid, ou a ferramenta Retrieve de um agente de IA, encontra então as linhas pelo significado. As linhas que já existem entram logo na fila para os seus embeddings.",
   'vec.existing': "Colunas vetoriais atuais",

package/src/builder/i18n/zh-cn.ts

@@ -1077,6 +1077,7 @@ export const zhCN: BuilderMessages = {
   'fts.added': "已为 {table} 添加全文搜索：列 {column}，索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "添加向量列",
+  'docv.add': "文档视图",
   'vec.title': "{table} 的向量列",
   'vec.intro': "添加一个嵌入列 vector(n)（n：向量提供者的维数）、一个用于该距离的 HNSW 索引，以及在源列变化时重新嵌入该行的触发器。之后，搜索类型为 vector 或 hybrid 的搜索配置，或 AI 代理的 Retrieve 工具，就能按含义找到行。现有的行会立即进入嵌入队列。",
   'vec.existing': "当前的向量列",

package/src/builder/i18n/zh-tw.ts

@@ -1077,6 +1077,7 @@ export const zhTW: BuilderMessages = {
   'fts.added': "已為 {table} 新增全文檢索：欄位 {column}，索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "新增向量欄位",
+  'docv.add': "文件檢視",
   'vec.title': "{table} 的向量欄位",
   'vec.intro': "新增一個嵌入欄位 vector(n)（n：向量提供者的維度數）、一個用於該距離的 HNSW 索引，以及在來源欄位變更時重新嵌入該列的觸發程序。之後，搜尋類型為 vector 或 hybrid 的搜尋組態，或 AI 代理的 Retrieve 工具，就能依含意找到資料列。現有的資料列會立即進入嵌入佇列。",
   'vec.existing': "目前的向量欄位",