Univer Base Units
Load univer first. A Base is one remote Workspace Unit:
FUniver
└── FBase
└── FBaseTable
├── FBaseTableField schema and value contract
├── FBaseTableRecord stored business data
└── FBaseTableView projection of the same table records
- Resolve
FBase by Unit ID. Tables own their fields, records, and views; views only add filter,
sort, group, visibility, and type-specific presentation.
- The primary field is the record's visible identity for links, cards, and details. Define it with
insertTable(..., { primaryFieldName }) instead of adding a duplicate label field.
- Use stable Unit/Table/Field/Record/View IDs in Facade relationships and user-facing names for
display. Record values and view config normally refer to Field IDs.
table.getFormulaName() is only the structured-reference name for formulas; it may differ from
the table's display name.
Entry
Create the Base with univer_unit in a draft worktree, then call univer_inspect with its unitId and unitType: "base" before editing. univer_execute predefines univerAPI, api, and the selected FBase as base. Use base directly; these bindings are reserved and must not be redeclared.
Do not call createBase() after univer_unit just to obtain a handle. A new Base already contains Table 1 with a primary Name field and Grid; insertTable() also creates a Grid. Inspect first, then deliberately reuse, rename, or delete defaults.
Exact API
Use univer_api to show:
FUniver.getBase, FBase, FBaseTable, FBaseTableField, FBaseTableRecord, FBaseTableView
FEnum.BaseFieldType, FBase.insertTable, FBaseTable.addField, FBaseTable.addRecords, FBaseTable.createView
IGridViewConfig, ICalendarViewConfig, IGalleryViewConfig, IGanttViewConfig, IKanbanViewConfig, ICardLayoutConfig
Use focused discovery such as recordLink with the Base Unit filter. Follow every referenced child type: if a result says card?: ICardLayoutConfig, show ICardLayoutConfig instead of guessing its shape.
Core contracts
- Add fields one at a time with
FBaseTable.addField(...); there is no addFields method.
- Single/MultiSelect options use
{ id, name, color? }; records store option IDs, not labels.
- Progress values follow its configured range: with
{ start: 0, end: 100 }, 75% is 75, not
0.75.
- Money uses
BaseFieldType.Currency and numeric values; Number is not a semantic substitute.
- RecordLink config targets a Table ID and stores target Record IDs. Prefer its dedicated Facade
methods when editing links.
- View config uses Field IDs. Kanban/Gallery card title and fields follow
ICardLayoutConfig;
fieldSettings does not replace the card contract.
OOXML Base table formulas
Base Formula fields must use exact Excel structured references:
Table[[#This Row],[Column]] or Table[@[Column]] reads one value from the formula record's row.
Table[[#Data],[Column]] or Table[Column] reads the complete data column.
- Unqualified
[@[Column]] is valid only for the current row of the Host table.
table[Column] is invalid unless table is the real table identifier.
Resolve every table's formula identifier with table.getFormulaName(). It may differ from the display name when duplicated or illegal as an Excel table name.
const ordersName = orders.getFormulaName();
const pricingName = pricing.getFormulaName();
orders.addField("Line Total", univerAPI.Enum.BaseFieldType.Formula, {
field: {
config: {
formula: `=${ordersName}[[#This Row],[Quantity]]*${pricingName}[[#This Row],[Unit Price]]`,
},
},
externalReferences: [],
});
A qualified #This Row reference to another Base table aligns by row position. Use it only when both tables deliberately share row order. For relational data, use a stable key or RecordLink with lookup logic. Use #Data only for intended full-column aggregation.
After writing a Formula field, subscribe to calculation completion before triggering the change, await it, and read computed record values. Stored formula text alone is not evidence.
Formula fields with a Sheet source
Persist the complete external-reference binding with the Formula field:
const table = base?.getTableById("<table-id>");
if (!table) throw new Error("Base table not found");
table.addField("Current Total", univerAPI.Enum.BaseFieldType.Formula, {
field: {
config: { formula: "=SUM('[Sales Source]Data'!B2:B4)" },
},
externalReferences: [
{
qualifier: "Sales Source",
sourceUnitId: "<sheet-unit-id>",
sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,
},
],
});
The formula qualifier and binding qualifier must match exactly. For broader cross-Unit formula work, load univer-cross-unit-formula as well.
Verification
After the last write, check:
univer_inspect for tables, primary fields, field types and config, record counts, and view types. It is read-only and accepts no range selector for Base.
- In a fresh
univer_edit with mode: "read", explicitly return record values plus view.getConfig() / view.getProjection() for stored IDs and view bindings. For Formula fields, also verify formula source, external bindings, and calculated results.
- Call
univer_screenshot with the Base unitId, selected worktree or trunk, and an explicit workspace output directory. Inspect the returned full-workbench PNG for blank labels, exposed IDs, implausible dates/percentages, missing card fields, empty defaults, and the opening active table/view.
Base screenshots accept only common screenshot arguments; do not pass Sheet ranges, Slide pages, or Board selectors.
Base may export to .xlsx, .csv, or .tsv through univer_export. Await calculation and complete readback before export.
1---2name: univer-base3description: Create, edit, calculate, inspect, export, and review Univer Base database Units through DSH tools and the Lite Interface. Use proactively for Base tables, fields, records, views, Formula fields, structured references, Sheet-backed external references, Base import/export, or any Base Unit task.4metadata:5 source: https://skillmd.com/skills/dream-num/univer-base6---78# Univer Base Units910Load `univer` first. A Base is one remote Workspace Unit:1112```text13FUniver14└── FBase15 └── FBaseTable16 ├── FBaseTableField schema and value contract17 ├── FBaseTableRecord stored business data18 └── FBaseTableView projection of the same table records19```2021- Resolve `FBase` by Unit ID. Tables own their fields, records, and views; views only add filter,22 sort, group, visibility, and type-specific presentation.23- The primary field is the record's visible identity for links, cards, and details. Define it with24 `insertTable(..., { primaryFieldName })` instead of adding a duplicate label field.25- Use stable Unit/Table/Field/Record/View IDs in Facade relationships and user-facing names for26 display. Record values and view config normally refer to Field IDs.27- `table.getFormulaName()` is only the structured-reference name for formulas; it may differ from28 the table's display name.2930## Entry3132Create the Base with `univer_unit` in a draft worktree, then call `univer_inspect` with its `unitId` and `unitType: "base"` before editing. `univer_execute` predefines `univerAPI`, `api`, and the selected `FBase` as `base`. Use `base` directly; these bindings are reserved and must not be redeclared.3334Do not call `createBase()` after `univer_unit` just to obtain a handle. A new Base already contains `Table 1` with a primary `Name` field and `Grid`; `insertTable()` also creates a Grid. Inspect first, then deliberately reuse, rename, or delete defaults.3536## Exact API3738Use `univer_api` to show:3940- `FUniver.getBase`, `FBase`, `FBaseTable`, `FBaseTableField`, `FBaseTableRecord`, `FBaseTableView`41- `FEnum.BaseFieldType`, `FBase.insertTable`, `FBaseTable.addField`, `FBaseTable.addRecords`, `FBaseTable.createView`42- `IGridViewConfig`, `ICalendarViewConfig`, `IGalleryViewConfig`, `IGanttViewConfig`, `IKanbanViewConfig`, `ICardLayoutConfig`4344Use focused discovery such as `recordLink` with the Base Unit filter. Follow every referenced child type: if a result says `card?: ICardLayoutConfig`, show `ICardLayoutConfig` instead of guessing its shape.4546## Core contracts4748- Add fields one at a time with `FBaseTable.addField(...)`; there is no `addFields` method.49- Single/MultiSelect options use `{ id, name, color? }`; records store option IDs, not labels.50- Progress values follow its configured range: with `{ start: 0, end: 100 }`, 75% is `75`, not51 `0.75`.52- Money uses `BaseFieldType.Currency` and numeric values; Number is not a semantic substitute.53- RecordLink config targets a Table ID and stores target Record IDs. Prefer its dedicated Facade54 methods when editing links.55- View config uses Field IDs. Kanban/Gallery card title and fields follow `ICardLayoutConfig`;56 `fieldSettings` does not replace the card contract.5758## OOXML Base table formulas5960Base Formula fields must use exact Excel structured references:6162- `Table[[#This Row],[Column]]` or `Table[@[Column]]` reads one value from the formula record's row.63- `Table[[#Data],[Column]]` or `Table[Column]` reads the complete data column.64- Unqualified `[@[Column]]` is valid only for the current row of the Host table.65- `table[Column]` is invalid unless `table` is the real table identifier.6667Resolve every table's formula identifier with `table.getFormulaName()`. It may differ from the display name when duplicated or illegal as an Excel table name.6869```js70const ordersName = orders.getFormulaName();71const pricingName = pricing.getFormulaName();72orders.addField("Line Total", univerAPI.Enum.BaseFieldType.Formula, {73 field: {74 config: {75 formula: `=${ordersName}[[#This Row],[Quantity]]*${pricingName}[[#This Row],[Unit Price]]`,76 },77 },78 externalReferences: [],79});80```8182A qualified `#This Row` reference to another Base table aligns by row position. Use it only when both tables deliberately share row order. For relational data, use a stable key or RecordLink with lookup logic. Use `#Data` only for intended full-column aggregation.8384After writing a Formula field, subscribe to calculation completion before triggering the change, await it, and read computed record values. Stored formula text alone is not evidence.8586## Formula fields with a Sheet source8788Persist the complete external-reference binding with the Formula field:8990```js91const table = base?.getTableById("<table-id>");92if (!table) throw new Error("Base table not found");9394table.addField("Current Total", univerAPI.Enum.BaseFieldType.Formula, {95 field: {96 config: { formula: "=SUM('[Sales Source]Data'!B2:B4)" },97 },98 externalReferences: [99 {100 qualifier: "Sales Source",101 sourceUnitId: "<sheet-unit-id>",102 sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,103 },104 ],105});106```107108The formula qualifier and binding qualifier must match exactly. For broader cross-Unit formula work, load `univer-cross-unit-formula` as well.109110## Verification111112After the last write, check:1131141. `univer_inspect` for tables, primary fields, field types and config, record counts, and view types. It is read-only and accepts no range selector for Base.1152. In a fresh `univer_edit` with `mode: "read"`, explicitly `return` record values plus `view.getConfig()` / `view.getProjection()` for stored IDs and view bindings. For Formula fields, also verify formula source, external bindings, and calculated results.1163. Call `univer_screenshot` with the Base `unitId`, selected worktree or trunk, and an explicit workspace `output` directory. Inspect the returned full-workbench PNG for blank labels, exposed IDs, implausible dates/percentages, missing card fields, empty defaults, and the opening active table/view.117118Base screenshots accept only common screenshot arguments; do not pass Sheet ranges, Slide pages, or Board selectors.119120Base may export to `.xlsx`, `.csv`, or `.tsv` through `univer_export`. Await calculation and complete readback before export.