# FBaseTable

> Language fallback: requested `zh-CN`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/zh-CN/reference/facade/base-table](https://docs.univer.ai/zh-CN/reference/facade/base-table)

- Agent Markdown: [https://docs.univer.ai/zh-CN/reference/facade/base-table.md](https://docs.univer.ai/zh-CN/reference/facade/base-table.md)

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/base-table.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/base-table.mdx)

---

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()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#gettables)
* [`FBase.getTableById()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#gettablebyid)
* [`FBase.getTableByName()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#gettablebyname)
* [`FBase.insertTable()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#inserttable)
* [`FBase.duplicateTable()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#duplicatetable)

## Example

Create fields, records, a view, and a query

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) 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](https://docs.univer.ai/zh-CN/guides/bases/getting-started/facade.md).

## `@univerjs-pro/bases`

### `FBaseTable.addField`

Add a field to this table.

```typescript
addField(name: string, type: BaseFieldType.Formula, options: IBaseAddFormulaFieldOptions): FBaseTableField
addField(name: string, type: BaseFieldType.RecordLink, options: IBaseAddRecordLinkFieldOptions): FBaseTableField
addField<T extends Exclude<BaseFieldType, BaseFieldType.Formula | BaseFieldType.RecordLink>>(name: string, type: T, options?: IBaseAddFieldOptions<T>): FBaseTableField
addField<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**

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

```ts
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

```ts
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

```ts
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

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-table-field.md) · [`BaseFieldType.Formula`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseAddFormulaFieldOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts) · [`BaseFieldType.RecordLink`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseAddRecordLinkFieldOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts) · [`IBaseAddFieldOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts) · [`BaseAddFieldOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts) · [`NoInfer`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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**

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

```ts
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)
```

```ts
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`)

```ts
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

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-table-record.md) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`FieldId`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`BaseCellValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`BaseFieldKeyEnum`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/field-key.d.ts) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IRecordSnapshot`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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**

```ts
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

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-table-record.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`FieldId`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`BaseCellValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`BaseFieldKeyEnum`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/field-key.d.ts) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IRecordSnapshot`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.createView`

Create a view in this table.

```typescript
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**

```ts
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)
```

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-table-view.md) · [`BaseViewType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IViewSnapshot`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.deleteRecords`

Delete multiple records from this table.

```typescript
deleteRecords(recordIds: string[]): boolean
```

**Parameters**

* `recordIds` — Required. An array of record ids to delete.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getBase`

Get the table's parent Base data model.

```typescript
getBase(): BaseDataModel
```

**Returns**

The Base data model.

**Examples**

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

**Types:** [`BaseDataModel`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/base-data-model.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getDataRange`

Get a range that covers the current table data area.

```typescript
getDataRange(): FBaseTableRange
```

**Returns**

The range facade covering the table data area.

**Examples**

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

**Types:** [`FBaseTableRange`](https://docs.univer.ai/zh-CN/reference/facade/base-table-range.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getFieldById`

Get a field by id.

```typescript
getFieldById(fieldId: string): FBaseTableField | null
```

**Parameters**

* `fieldId` — Required. The field id.

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableField`](https://docs.univer.ai/zh-CN/reference/facade/base-table-field.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getFieldByName`

Get a field by name.

```typescript
getFieldByName(fieldName: string): FBaseTableField | null
```

**Parameters**

* `fieldName` — Required. The field name.

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableField`](https://docs.univer.ai/zh-CN/reference/facade/base-table-field.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getFields`

Get all existing fields in this table.

```typescript
getFields(): FBaseTableField[]
```

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableField`](https://docs.univer.ai/zh-CN/reference/facade/base-table-field.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
getFormulaName(): string
```

**Returns**

The canonical normalized formula table name.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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

```ts
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 write

const child = parent.addChild(parentFieldId, {
  [table.getPrimaryFieldId()]: 'Write integration tests',
})

console.log(table.getFieldById(parentFieldId)?.getId()) // parentFieldId
console.log(child.getParent(parentFieldId)?.getId()) // 'task-1'
```

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getId`

Get the table id.

```typescript
getId(): string
```

**Returns**

The table id.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getName`

Get the human-readable table display name.

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

```typescript
getName(): string
```

**Returns**

The human-readable table display name.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getPermission`

Returns the Table object permission facade.

```typescript
getPermission(): FBaseObjectPermission
```

**Returns**

Permission facade combining the Base and Table Edit points.

**Examples**

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

**Types:** [`FBaseObjectPermission`](https://docs.univer.ai/zh-CN/reference/facade/base-object-permission.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getPrimaryField`

Get the primary field.

```typescript
getPrimaryField(): FBaseTableField
```

**Returns**

The primary field facade.

**Examples**

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

**Types:** [`FBaseTableField`](https://docs.univer.ai/zh-CN/reference/facade/base-table-field.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getPrimaryFieldId`

Get the primary field id.

```typescript
getPrimaryFieldId(): string
```

**Returns**

The primary field id.

**Examples**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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**

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-table-range.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getRecordById`

Get a record by id.

```typescript
getRecordById(recordId: string): FBaseTableRecord | null
```

**Parameters**

* `recordId` — Required. The record id.

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableRecord`](https://docs.univer.ai/zh-CN/reference/facade/base-table-record.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getRecords`

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

```typescript
getRecords(): FBaseTableRecord[]
```

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableRecord`](https://docs.univer.ai/zh-CN/reference/facade/base-table-record.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getSchema`

Get a compact schema snapshot for this table.

```typescript
getSchema(): IBaseTableSchemaSnapshot
```

**Returns**

Table schema without row values.

**Examples**

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

**Types:** [`IBaseTableSchemaSnapshot`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getTable`

Get the table snapshot.

```typescript
getTable(): ITableSnapshot
```

**Returns**

The table snapshot.

**Examples**

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

**Types:** [`ITableSnapshot`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getViewById`

Get a view by id.

```typescript
getViewById(viewId: string): FBaseTableView | null
```

**Parameters**

* `viewId` — Required. The view id.

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableView`](https://docs.univer.ai/zh-CN/reference/facade/base-table-view.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getViewByName`

Get a view by name.

```typescript
getViewByName(viewName: string): FBaseTableView | null
```

**Parameters**

* `viewName` — Required. The view name.

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableView`](https://docs.univer.ai/zh-CN/reference/facade/base-table-view.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.getViews`

Get all existing views in this table.

```typescript
getViews(): FBaseTableView[]
```

**Returns**

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

**Examples**

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

**Types:** [`FBaseTableView`](https://docs.univer.ai/zh-CN/reference/facade/base-table-view.md)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `FBaseTable.queryRecords`

Query records with filter, sort, and pagination metadata.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts) · [`IListRecordOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/search/base-search.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBaseTableSearchRequest`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/search/base-search.d.ts)

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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.

```typescript
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

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)

### `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()`.

```typescript
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**

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

**Package:** [`@univerjs-pro/bases`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-table.d.ts)