FBaseTable

Facade API object bound to a Base table.

A Base table is similar to a worksheet: fields are columns, records are rows, and ranges address rectangular record-field regions.

Use table methods for field, record, cell, range, view, schema, and table permission operations. The table facade always resolves the latest table snapshot from the Base model, so a previously created FTable remains usable after other facade commands mutate the table.

Access

Access through:

• FBase.getTables()
• FBase.getTableById()
• FBase.getTableByName()
• FBase.insertTable()
• FBase.duplicateTable()

Example

Create fields, records, a view, and a query

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.insertTable('Tasks', {  index: 0,  primaryFieldName: 'Title',})const name = fBaseTable.addField('Name', univerAPI.Enum.BaseFieldType.Text)const status = fBaseTable.addField('Status', univerAPI.Enum.BaseFieldType.SingleSelect, {  field: {    config: {      options: [        { id: 'todo', name: 'Todo', color: 'blue' },        { id: 'done', name: 'Done', color: 'green' },      ],    },  },})const progress = fBaseTable.addField('Progress', univerAPI.Enum.BaseFieldType.Progress)fBaseTable.addRecord({  [fBaseTable.getPrimaryFieldId()]: 'Review protocol',  [name.getId()]: 'Review protocol',  [status.getId()]: 'todo',  [progress.getId()]: 0,})fBaseTable.addRecords([  {    values: {      [fBaseTable.getPrimaryFieldId()]: 'Design protocol',      [status.getId()]: 'todo',      [progress.getId()]: 20,    },  },  {    values: {      [fBaseTable.getPrimaryFieldId()]: 'Wire server load',      [status.getId()]: 'done',      [progress.getId()]: 100,    },  },])const grid = fBaseTable.createView('Main Grid', univerAPI.Enum.BaseViewType.Grid, {  view: {    config: {      frozenFieldCount: 1,    },  },})const done = fBaseTable.queryRecords({  filter: {    conditions: [      {        fieldId: status.getId(),        operator: univerAPI.Enum.BaseFilterOperator.IS,        value: 'done',      },    ],  },})console.log(done)

Setup

Register @univerjs-pro/bases or a preset that includes it. In plugin mode, import @univerjs-pro/bases/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/bases

FBaseTable.addField

Add a field to this table.

addField(name: string, type: BaseFieldType.Formula, options: IBaseAddFormulaFieldOptions): FBaseTableFieldaddField(name: string, type: BaseFieldType.RecordLink, options: IBaseAddRecordLinkFieldOptions): FBaseTableFieldaddField<T extends Exclude<BaseFieldType, BaseFieldType.Formula | BaseFieldType.RecordLink>>(name: string, type: T, options?: IBaseAddFieldOptions<T>): FBaseTableFieldaddField<T extends BaseFieldType>(name: string, type: T, options: BaseAddFieldOptions<NoInfer<T>>): FBaseTableField

Parameters

• name — Required. The field display name.
• type — Required. The field type, such as text, number, singleSelect, recordLink, or formula.
• options — Required. Optional field parameters.

Returns

The new field facade.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.addField('Name', univerAPI.Enum.BaseFieldType.Text)console.log(field)

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.addField('Status', univerAPI.Enum.BaseFieldType.SingleSelect, {  index: 1,  field: {    config: {      options: [        { id: 'todo', name: 'Todo', color: 'blue' },        { id: 'done', name: 'Done', color: 'green' },      ],    },  },})console.log(field)

RecordLink field

const fBase = univerAPI.getActiveBase()const tasks = fBase.getTableById('tasks-table')const projects = fBase.getTableById('projects-table')if (!tasks || !projects) {  throw new Error('Expected the Tasks and Projects tables.')}const ownerField = projects.getFieldByName('Owner')const relatedProjects = tasks.addField(  'Related projects',  univerAPI.Enum.BaseFieldType.RecordLink,  {    field: {      config: {        targetTableId: projects.getId(),        multiple: true,        // One field supplies the visible chip label. Omit this to use        // the target table's primary field.        displayFieldId: projects.getPrimaryFieldId(),        // These fields appear below the label in the picker only.        pickerFieldIds: ownerField ? [ownerField.getId()] : [],      },    },  },)const task = tasks.getRecordById('task-1')const project = projects.getRecordById('project-1')if (task && project) {  task.addLinkedRecord(relatedProjects.getId(), project.getId())}

Formula field

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const amount = fBaseTable.addField('Amount', univerAPI.Enum.BaseFieldType.Number, {  field: {    config: {      decimalPlaces: 2,    },  },})const tax = fBaseTable.addField('Tax', univerAPI.Enum.BaseFieldType.Number, {  field: {    config: {      decimalPlaces: 2,    },  },})const formulaTableName = fBaseTable.getFormulaName()const total = fBaseTable.addField('Total', univerAPI.Enum.BaseFieldType.Formula, {  field: {    config: {      formula: `=SUM(${formulaTableName}[[#This Row],[Amount]],${formulaTableName}[[#This Row],[Tax]])`,    },  },  externalReferences: [], // Required; this formula only uses fields in the Host Base.})

Cross-Unit Formula field

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const pricingBase = {  unitId: 'pricing-base',  formulaQualifier: 'Pricing',}const formulaTableName = fBaseTable.getFormulaName()const taxAmount = univerAPI.getFormula().buildReference({  hostUnitId: fBase.getId(),  unit: pricingBase,  target: {    kind: univerAPI.Enum.FormulaReferenceType.TABLE_COLUMN,    tableName: 'Tax Rates',    columnName: 'Amount',  },})const total = fBaseTable.addField('Total', univerAPI.Enum.BaseFieldType.Formula, {  field: {    config: {      formula: `=SUM(${formulaTableName}[[#This Row],[Amount]])+SUM(${taxAmount})`,      numberFormat: {        type: 'currency',        pattern: '"$"#,##0.00',      },    },    readonly: true,  },  externalReferences: [    {      qualifier: pricingBase.formulaQualifier,      sourceUnitId: pricingBase.unitId,      sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_BASE,    },  ],})

Types: FBaseTableField · BaseFieldType.Formula · IBaseAddFormulaFieldOptions · BaseFieldType.RecordLink · IBaseAddRecordLinkFieldOptions · IBaseAddFieldOptions · BaseAddFieldOptions · NoInfer

Package: @univerjs-pro/bases · Type definitions

FBaseTable.addRecord

Add a record to this table synchronously.

This method is also the low-level, data-oriented way to create a child record: use the id returned by getHierarchyFieldId() as a value key and use the parent's record id as its value. The call does not require await. If the table has not created its canonical Parent field yet, the command creates the same-table, single-value RecordLink field, the record, and the Parent edge as one JSON1 operation and one Undo entry. No observer can see an intermediate field-only or record-only state.

Parent values use the same canonical storage format as a single-value RecordLink: pass one record id string. Hierarchy validation rejects a missing parent, self-parent, cycle, or hierarchy deeper than five levels before any mutation is committed. parent.addChild() remains available as a semantic convenience when code already has the parent record Facade.

The virtual Parent field has no display name until the first write. Therefore, address it by id and keep the default BaseFieldKeyEnum.Id; other ordinary fields may still be resolved by name in a separate call.

addRecord(values: Record<FieldId, BaseCellValue>, fieldKey?: BaseFieldKeyEnum, record?: Partial<Omit<IRecordSnapshot, 'id'>>): FBaseTableRecord

Parameters

• values — Required. The record field values, keyed by field id or name.
• fieldKey — Optional. Default: BaseFieldKeyEnum.Id. Optional field key type for the values. Defaults to id.
• record — Optional. Optional partial record snapshot to merge into the new record.

Returns

The new record Facade immediately after the synchronous command succeeds.

Throws

If an initial Parent value is missing, cyclic, self-referential, or would exceed five levels.

If another record or field value is invalid, or the atomic command cannot be applied.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const record = fBaseTable.addRecord({  title: 'Ship beta',  status: 'todo',})console.log(record)

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const record = fBaseTable.addRecord(  {    Title: 'Ship beta',    Status: 'todo',  },  univerAPI.Enum.BaseFieldKeyEnum.Name,)console.log(record)

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()const values: Record<FieldId, BaseCellValue> = {}for (const field of fields) {  if (field.getName() === 'Title') {    values[field.getId()] = 'Ship Base adapter'  } else if (field.getName() === 'Status') {    values[field.getId()] = 'todo'  }}const record = fBaseTable.addRecord(values)console.log(record)

Create the first child with the generic record API (no await)

const base = univerAPI.getActiveBase()if (!base) throw new Error('No active Base.')const table = base.getTableById('tasks')if (!table) throw new Error('Tasks table not found.')const parent = table.getRecordById('task-1')if (!parent) throw new Error('Parent record not found.')const parentFieldId = table.getHierarchyFieldId()const child = table.addRecord({  [table.getPrimaryFieldId()]: 'Write integration tests',  [parentFieldId]: parent.getId(),})console.log(child.getParent(parentFieldId)?.getId()) // 'task-1'console.log(parent.getChildren(parentFieldId).map((item) => item.getId()))

Add a record with a public URL attachment

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const imageField = fBaseTable.getFieldByName('Product image')const record = fBaseTable.addRecord({  [fBaseTable.getPrimaryFieldId()]: 'Red Nail Polish',  [imageField.getId()]: [    {      id: 'product-image',      name: 'product.webp',      source: 'https://example.com/product.webp',      sourceType: univerAPI.Enum.ImageSourceType.URL,      mimeType: 'image/webp',    },  ],})console.log(record)

Types: FBaseTableRecord · Record · FieldId · BaseCellValue · BaseFieldKeyEnum · Partial · Omit · IRecordSnapshot

Package: @univerjs-pro/bases · Type definitions

FBaseTable.addRecords

Add multiple records to this table.

Each initial Parent value is validated before the batch is applied. The first batch may use the virtual id returned by getHierarchyFieldId(); the Parent field is then materialized once in the same atomic command. Every accepted Parent edge is included in one atomic hierarchy event with Facade source, and Undo removes the records and those edges together.

addRecords(records: Array<{ values: Record<FieldId, BaseCellValue>; fieldKey?: BaseFieldKeyEnum; record?: Partial<Omit<IRecordSnapshot, 'id'>>; }>): FBaseTableRecord[]

Parameters

• records — Required. An array of record values, optional field key types, and optional partial record snapshots.

Returns

The created record Facades immediately after the synchronous command succeeds.

Throws

If any initial Parent value is invalid.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const records = fBaseTable.addRecords([  { values: { title: 'Task A' } },  { values: { title: 'Task B' } },])console.log(records)

Create sibling records below one parent in a single Undo entry

const base = univerAPI.getActiveBase()if (!base) throw new Error('No active Base.')const table = base.getTableById('tasks')if (!table) throw new Error('Tasks table not found.')const parent = table.getRecordById('task-1')if (!parent) throw new Error('Parent record not found.')const parentFieldId = table.getHierarchyFieldId()const children = table.addRecords([  { values: { [table.getPrimaryFieldId()]: 'Child A', [parentFieldId]: parent.getId() } },  { values: { [table.getPrimaryFieldId()]: 'Child B', [parentFieldId]: parent.getId() } },])console.log(children.map((child) => child.getId()))

Types: FBaseTableRecord · Array · Record · FieldId · BaseCellValue · BaseFieldKeyEnum · Partial · Omit · IRecordSnapshot

Package: @univerjs-pro/bases · Type definitions

FBaseTable.createView

Create a view in this table.

createView(name: string, type: BaseViewType, options?: { index?: number; view?: Partial<Omit<IViewSnapshot, 'id'>>; }): FBaseTableView

Parameters

• name — Required. The view display name.
• type — Required. The view type, such as grid, calendar, or gantt.
• options — Optional. Optional view parameters.

Returns

The new view facade.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const view = fBaseTable.createView('API Grid', univerAPI.Enum.BaseViewType.Grid, {  view: {    id: 'grid-api',    config: {      frozenFieldCount: 1,    },  },})console.log(view)

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const calendar = fBaseTable.createView('Calendar', univerAPI.Enum.BaseViewType.Calendar, {  view: {    id: 'calendar-main',    config: {      startFieldId: 'start',      endFieldId: 'end',    },  },})console.log(calendar)const gantt = fBaseTable.createView('Gantt', univerAPI.Enum.BaseViewType.Gantt, {  view: {    id: 'gantt-main',    config: {      startFieldId: 'start',      endFieldId: 'end',      progressFieldId: 'progress',    },  },})console.log(gantt)

Types: FBaseTableView · BaseViewType · Partial · Omit · IViewSnapshot

Package: @univerjs-pro/bases · Type definitions

FBaseTable.deleteRecords

Delete multiple records from this table.

deleteRecords(recordIds: string[]): boolean

Parameters

• recordIds — Required. An array of record ids to delete.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const records = fBaseTable.getRecords()const success = fBaseTable.deleteRecords([records[0].getId(), records[2].getId()])console.log(success)

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getBase

Get the table's parent Base data model.

getBase(): BaseDataModel

Returns

The Base data model.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable.getBase())

Types: BaseDataModel

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getDataRange

Get a range that covers the current table data area.

getDataRange(): FBaseTableRange

Returns

The range facade covering the table data area.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const values = fBaseTable.getDataRange().getValues()console.log(values)

Types: FBaseTableRange

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getFieldById

Get a field by id.

getFieldById(fieldId: string): FBaseTableField | null

Parameters

• fieldId — Required. The field id.

Returns

The field facade, or null if the field does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldById('status')console.log(field)

Types: FBaseTableField

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getFieldByName

Get a field by name.

getFieldByName(fieldName: string): FBaseTableField | null

Parameters

• fieldName — Required. The field name.

Returns

The field facade, or null if the field does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')console.log(field)

Types: FBaseTableField

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getFields

Get all existing fields in this table.

getFields(): FBaseTableField[]

Returns

An array of field facades ordered by the table field order.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields)

Types: FBaseTableField

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getFormulaName

Get the stable canonical OOXML-compatible table name used in structured formula references. The name is allocated when the table is created or a historical snapshot is migrated; later display-name changes do not change formula identity. Always use the returned name; table is not a reserved alias unless it is the actual identifier returned by this method.

Base Formula fields use Excel structured-reference scopes. Use Table[[#This Row],[Column]] (or Table[@[Column]]) for one value from the formula record's row. Use Table[[#Data],[Column]] (or Table[Column]) only when the formula intentionally consumes the complete data column. For another Base table, call that table's getFormulaName() instead of typing its display name or relying on a placeholder.

getFormulaName(): string

Returns

The canonical normalized formula table name.

Examples

const fBase = univerAPI.getActiveBase()const table = fBase.getTableById('table-1')const tableName = table.getFormulaName()const currentAmount = `=${tableName}[[#This Row],[Amount]]`const allAmounts = `=SUM(${tableName}[[#Data],[Amount]])`

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getHierarchyFieldId

Get the field id used by this table's record hierarchy.

Record hierarchy is a table-level capability. Every Grid or Kanban view of the table observes the same Parent relationship; a view does not enable or own hierarchy separately.

Before the first hierarchy write, this method returns a deterministic virtual field id. Passing that id to addRecord(), addRecords(), FBaseTableRecord.addChild(), or FBaseTableRecord.setParent() creates the same-table, single-value RecordLink field and applies the record change in one command and one Undo entry. Therefore, getFieldById(getHierarchyFieldId()) may return null until the first successful write.

getHierarchyFieldId(): string

Returns

The materialized Parent field id, or the deterministic id that the first hierarchy write will materialize.

Examples

Create the first child without creating a field manually

const base = univerAPI.getActiveBase()if (!base) throw new Error('No active Base.')const table = base.getTableById('tasks')if (!table) throw new Error('Tasks table not found.')const parent = table.getRecordById('task-1')if (!parent) throw new Error('Parent record not found.')const parentFieldId = table.getHierarchyFieldId()console.log(table.getFieldById(parentFieldId)) // null before the first writeconst child = parent.addChild(parentFieldId, {  [table.getPrimaryFieldId()]: 'Write integration tests',})console.log(table.getFieldById(parentFieldId)?.getId()) // parentFieldIdconsole.log(child.getParent(parentFieldId)?.getId()) // 'task-1'

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getId

Get the table id.

getId(): string

Returns

The table id.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable.getId()) // 'table-1'

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getName

Get the human-readable table display name.

Do not use this value in formulas. Use getFormulaName() for structured references.

getName(): string

Returns

The human-readable table display name.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable.getName())

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getPermission

Returns the Table object permission facade.

getPermission(): FBaseObjectPermission

Returns

Permission facade combining the Base and Table Edit points.

Examples

const table = univerAPI.getActiveBase()?.getTables()[0]if (!table) throw new Error('Table not found.')await table.getPermission().setReadOnly()

Types: FBaseObjectPermission

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getPrimaryField

Get the primary field.

getPrimaryField(): FBaseTableField

Returns

The primary field facade.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const primaryField = fBaseTable.getPrimaryField()console.log(primaryField)

Types: FBaseTableField

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getPrimaryFieldId

Get the primary field id.

getPrimaryFieldId(): string

Returns

The primary field id.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable.getPrimaryFieldId())

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getRange

Get a rectangular range by row and column indexes.

Range indexes use the table's current recordOrder and fieldOrder. This mirrors Sheet-style row/column addressing while still writing Base record/field values under the hood.

getRange(row: number, column: number, numRows?: number, numColumns?: number): FBaseTableRange

Parameters

• row — Required. The zero-based row index.
• column — Required. The zero-based column index.
• numRows — Optional. Default: 1. Optional number of rows in the range. Defaults to 1.
• numColumns — Optional. Default: 1. Optional number of columns in the range. Defaults to 1.

Returns

The range facade.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const range = fBaseTable.getRange(0, 0, 2, 3)console.log(range.getValues())fBaseTable.getRange(0, 0, 2, 2).setValues([  ['Task A', 'todo'],  ['Task B', 'done'],])

Types: FBaseTableRange

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getRecordById

Get a record by id.

getRecordById(recordId: string): FBaseTableRecord | null

Parameters

• recordId — Required. The record id.

Returns

The record facade, or null if the record does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const record = fBaseTable.getRecordById('record-1')console.log(record)

Types: FBaseTableRecord

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getRecords

Get all records in this table, optionally filtered, sorted, and paginated.

getRecords(): FBaseTableRecord[]

Returns

An array of record facades ordered by the table record order.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const records = fBaseTable.getRecords()console.log(records)

Types: FBaseTableRecord

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getSchema

Get a compact schema snapshot for this table.

getSchema(): IBaseTableSchemaSnapshot

Returns

Table schema without row values.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const schema = fBaseTable.getSchema()console.log(schema)

Types: IBaseTableSchemaSnapshot

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getTable

Get the table snapshot.

getTable(): ITableSnapshot

Returns

The table snapshot.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable.getTable())

Types: ITableSnapshot

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getViewById

Get a view by id.

getViewById(viewId: string): FBaseTableView | null

Parameters

• viewId — Required. The view id.

Returns

The view facade, or null if the view does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const view = fBaseTable.getViewById('grid')console.log(view)

Types: FBaseTableView

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getViewByName

Get a view by name.

getViewByName(viewName: string): FBaseTableView | null

Parameters

• viewName — Required. The view name.

Returns

The view facade, or null if the view does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const view = fBaseTable.getViewByName('Grid')console.log(view)

Types: FBaseTableView

Package: @univerjs-pro/bases · Type definitions

FBaseTable.getViews

Get all existing views in this table.

getViews(): FBaseTableView[]

Returns

An array of view facades ordered by the table view order.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const views = fBaseTable.getViews()console.log(views)

Types: FBaseTableView

Package: @univerjs-pro/bases · Type definitions

FBaseTable.queryRecords

Query records with filter, sort, and pagination metadata.

queryRecords(options?: IListRecordOptions): IQueryRecordsResult

Parameters

• options — Optional. Default: {}. Optional query options.

Returns

The query result with records, total count, offset, limit, and hasMore flag.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const page = fBaseTable.queryRecords({  filter: {    conditions: [      {        fieldId: 'status',        operator: univerAPI.Enum.BaseFilterOperator.IS,        value: 'done',      },    ],  },  sort: [    {      fieldId: 'progress',      direction: univerAPI.Enum.BaseSortDirection.DESC,    },  ],  limit: 20,})console.log(page)

Types: IQueryRecordsResult · IListRecordOptions

Package: @univerjs-pro/bases · Type definitions

FBaseTable.search

Search records in this table.

Search reads the current table snapshot. When viewId is provided, the search space follows that view projection, including hidden fields and projected row order.

search(request: Omit<IBaseTableSearchRequest, 'table' | 'rows'>, viewId?: string): IBaseTableSearchResult

Parameters

• request — Required. The search request parameters, excluding table and rows.
• viewId — Optional. Optional view id to search within a specific view projection.

Returns

The search result with matching records and total count.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const result = fBaseTable.search({  query: 'release',  fieldIds: ['title', 'status'],  limit: 20,})console.log(result)

Types: IBaseTableSearchResult · Omit · IBaseTableSearchRequest

Package: @univerjs-pro/bases · Type definitions

FBaseTable.setHierarchyField

Select or clear the table's materialized Parent field.

The selected field must already exist and must be a RecordLink that targets this table with multiple: false. The command assigns the Parent semantic role to that field and removes the role from the previous Parent field. Stored RecordLink values are not rewritten.

Passing null clears the semantic role and flattens the effective hierarchy. It does not delete the former field or its values. Because hierarchy is a default table capability, getHierarchyFieldId() will then return a new deterministic virtual id for a future hierarchy write.

Grid and Kanban views consume the table-level relationship automatically; there is no per-view activation API.

setHierarchyField(fieldId: string | null): boolean

Parameters

• fieldId — Required. An eligible RecordLink field id, or null to clear the currently materialized Parent role.

Returns

true when the command succeeds. The change is undoable.

Throws

With univerAPI.Enum.BaseHierarchyErrorCode.InvalidField when fieldId is not an existing same-table, single-value RecordLink field.

Examples

Use an existing RecordLink field as Parent

import { BaseHierarchyError } from '@univerjs-pro/bases'const base = univerAPI.getActiveBase()if (!base) throw new Error('No active Base.')const table = base.getTableById('tasks')if (!table) throw new Error('Tasks table not found.')try {  table.setHierarchyField('parent-record-link')} catch (error) {  if (    error instanceof BaseHierarchyError &&    error.code === univerAPI.Enum.BaseHierarchyErrorCode.InvalidField  ) {    console.error('The Parent field must link to one record in the same table.')  } else {    throw error  }}// Later, flatten the table without deleting the RecordLink field or its values.table.setHierarchyField(null)

Package: @univerjs-pro/bases · Type definitions

FBaseTable.setName

Rename this table's human-readable display label. The name becomes an Excel worksheet name during export, so it must contain 1-31 characters, not start or end with an apostrophe, not contain : \\ / ? * [ ], and be unique within the Base (case-insensitive).

Its stable formula name does not change. Existing and new structured references must continue to use the value returned by getFormulaName().

setName(displayName: string): boolean

Parameters

• displayName — Required. The new human-readable table display name.

Returns

Whether the rename command succeeded.

Throws

If displayName violates the Excel worksheet-name rules. The error includes both the complete contract and the specific reason, so callers and agents can correct it.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const success = fBaseTable.setName('Roadmap')console.log(success)

Package: @univerjs-pro/bases · Type definitions