# FBase

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade API object bound to a Base unit.

## Access

Access through:

* [`FUniver.createBase()`](https://docs.univer.ai/reference/facade/univer.md#createbase)
* [`FUniver.getActiveBase()`](https://docs.univer.ai/reference/facade/univer.md#getactivebase)
* [`FUniver.getBase()`](https://docs.univer.ai/reference/facade/univer.md#getbase)
* [`FUniver.getBases()`](https://docs.univer.ai/reference/facade/univer.md#getbases)

## Setup

Register [`@univerjs-pro/bases`](https://docs.univer.ai/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/guides/bases/getting-started/facade.md).

## `@univerjs-pro/bases`

### `FBase.deleteTable`

Delete a table from this Base.

```typescript
deleteTable(table: FBaseTable | string): boolean
```

**Parameters**

* `table` — Required. The table facade instance or table id to delete.

**Returns**

True if the table was deleted, false if it did not exist.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTable = fBase.getTables()[1]
if (fBaseTable) {
  const result = fBase.deleteTable(fBaseTable)
  console.log(result)
}
```

```ts
const fBase = univerAPI.getActiveBase()
const result = fBase.deleteTable('table-1')
console.log(result)
```

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

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

### `FBase.duplicateTable`

Duplicate a table in this Base.

```typescript
duplicateTable(table: FBaseTable | string, options?: { includeRecords?: boolean; regenerateViewIds?: boolean; }): FBaseTable
```

**Parameters**

* `table` — Required. The table facade instance or table id to duplicate.
* `options` — Optional. Optional parameters for table duplication.

**Returns**

The newly duplicated table facade.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTable = fBase.getTables()[0]
if (fBaseTable) {
  const fBaseTableCopy = fBase.duplicateTable(fBaseTable, { includeRecords: true })
  console.log(fBaseTableCopy)
}
```

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

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

### `FBase.getBase`

Get the underlying Base data model.

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

**Returns**

The underlying Base data model.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
console.log(fBase.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/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-base.d.ts)

### `FBase.getId`

Get the Base unit id.

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

**Returns**

The Base unit id.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
console.log(fBase.getId())
```

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

### `FBase.getName`

Get the Base name.

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

**Returns**

The Base name.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
console.log(fBase.getName())
```

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

### `FBase.getPermission`

Returns the Base unit permission facade.

```typescript
getPermission(): FBasePermission
```

**Returns**

Permission facade for Edit, Copy, Export, and Comment.

**Examples**

```ts
const base = univerAPI.getActiveBase()
if (!base) throw new Error('No active Base.')
await base.getPermission().setReadOnly()
```

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

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

### `FBase.getSchema`

Get a compact schema snapshot for agent/tooling use.

`getSchema()` intentionally omits row values. Use it when an agent,
server route, or prompt needs structure and ids without transferring the
full data payload.

```typescript
getSchema(): IBaseSchemaSnapshot
```

**Returns**

The compact Base schema snapshot.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
console.log(fBase.getSchema())
```

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

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

### `FBase.getTableById`

Get a table by id.

```typescript
getTableById(tableId: string): FBaseTable | null
```

**Parameters**

* `tableId` — Required. The table id.

**Returns**

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

**Examples**

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

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

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

### `FBase.getTableByName`

Get a table by its human-readable display name.

This method does not look up the stable identifier used in formulas. To author a
structured reference, get the table first and call `FBaseTable.getFormulaName()`.

```typescript
getTableByName(displayName: string): FBaseTable | null
```

**Parameters**

* `displayName` — Required. The table display name.

**Returns**

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

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTable = fBase.getTableByName('Tasks')
console.log(fBaseTable)
```

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

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

### `FBase.getTables`

Get all existing tables in this Base.

```typescript
getTables(): FBaseTable[]
```

**Returns**

The table facade instances.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTables = fBase.getTables()
console.log(fBaseTables)
```

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

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

### `FBase.insertTable`

Insert a new table into the Base.

The display name becomes an Excel worksheet name during export. It must contain
1-31 characters, not start or end with an apostrophe, not contain `: \\ / ? * [ ]`,
and be unique within the Base (case-insensitive). It may differ from the stable formula name.
Use the returned table's `getFormulaName()` when authoring structured references.

```typescript
insertTable(displayName: string, options?: { index?: number; table?: Partial<Omit<ITableSnapshot, 'id'>>; primaryFieldName?: string; }): FBaseTable
```

**Parameters**

* `displayName` — Required. The human-readable table display name.
* `options` — Optional. Optional parameters for table creation.

**Returns**

The newly created table facade.

**Throws**

If the effective display name violates the Excel worksheet-name rules.
The error includes both the complete contract and the specific reason, so callers and agents
can correct the input before retrying.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTable = fBase.insertTable('Risk tracker')
console.log(fBaseTable.getName()) // Human-readable display name: "Risk tracker"
console.log(fBaseTable.getFormulaName()) // Stable name for formulas: "Risk_tracker"
```

Full table creation flow

```ts
const fBase = univerAPI.getActiveBase()
const fBaseTable = fBase.insertTable('Tasks', {
  index: 0,
  primaryFieldName: 'Title',
})

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' },
      ],
    },
  },
})
const progress = fBaseTable.addField('Progress', univerAPI.Enum.BaseFieldType.Progress)

const record = fBaseTable.addRecord(
  {
    Status: 'todo',
    Progress: 10,
  },
  univerAPI.Enum.BaseFieldKeyEnum.Name,
)

console.log(fBaseTable.getTable())
```

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

### `FBase.save`

Save and return the current complete Base snapshot.

This method intentionally returns the full in-memory `IBaseSnapshot`
instead of performing I/O. The payload includes tables, fields, views,
records, cell data, resources, table order, and metadata. The caller
decides how to persist it, for example by sending it to the server-side
protocol adapter.

```typescript
save(): IBaseSnapshot
```

**Returns**

The current complete Base snapshot.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
console.log(fBase.save())
```

**Types:** [`IBaseSnapshot`](https://docs.univer.ai/reference/types/base-snapshot.md)

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

### `FBase.setName`

Set the Base name.

```typescript
setName(name: string): void
```

**Parameters**

* `name` — Required. The new Base name.

**Examples**

```ts
const fBase = univerAPI.getActiveBase()
fBase.setName('Product Roadmap')
console.log(fBase.getName())
```

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

## `@univerjs-pro/bases-dashboard`

### `FBase.createDashboard`

Creates an empty Dashboard through the command system, including undo and redo support.

```typescript
createDashboard(name: string, options?: ICreateBaseDashboardOptions): FBaseDashboard
```

**Parameters**

* `name` — Required. Human-readable Dashboard name.
* `options` — Optional. Stable id and insertion position.

**Returns**

The created Dashboard Facade.

**Throws**

If the Dashboard cannot be created, for example because its id already exists.

**Examples**

```ts
const base = univerAPI.getActiveBase()
if (!base) {
  throw new Error('No active Base.')
}
const dashboard = base.createDashboard('Executive overview', { id: 'executive' })
```

**Types:** [`FBaseDashboard`](https://docs.univer.ai/reference/facade/base-dashboard.md) · [`ICreateBaseDashboardOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

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

### `FBase.createPivotView`

Creates a Pivot View backed by the target table.

The default Pivot snapshot is produced by `engine-pivot`, while the default Chart is a column Chart.
Use the returned Facade's `getPivotTable()` to configure rows, columns, filters, values, and aggregation
with the Engine API, then persist the resulting snapshot with `updateConfig()`.

```typescript
createPivotView(name: string, tableId: string, options?: ICreateBasePivotViewOptions): FBasePivotView
```

**Parameters**

* `name` — Required. Human-readable Pivot View name.
* `tableId` — Required. Stable source table id.
* `options` — Optional. Stable id, insertion position, and initial configuration.

**Returns**

The created Pivot View Facade.

**Throws**

If the table does not exist or the Pivot View cannot be created.

**Examples**

```ts
const base = univerAPI.getActiveBase()
if (!base) {
  throw new Error('No active Base.')
}
const pivot = base.createPivotView('Revenue by region', 'orders')
```

**Types:** [`FBasePivotView`](https://docs.univer.ai/reference/facade/base-pivot-view.md) · [`ICreateBasePivotViewOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base.d.ts)

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

### `FBase.getDashboardById`

Returns a Dashboard by id.

```typescript
getDashboardById(dashboardId: string): FBaseDashboard | null
```

**Parameters**

* `dashboardId` — Required. Stable Dashboard id.

**Returns**

The Dashboard Facade, or null when absent.

**Examples**

```ts
const dashboard = univerAPI.getActiveBase()?.getDashboardById('executive')
```

**Types:** [`FBaseDashboard`](https://docs.univer.ai/reference/facade/base-dashboard.md)

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

### `FBase.getDashboards`

Returns all Dashboards in persisted order.

```typescript
getDashboards(): FBaseDashboard[]
```

**Returns**

Dashboard Facades for this Base.

**Examples**

```ts
const base = univerAPI.getActiveBase()
const dashboards = base?.getDashboards() ?? []
```

**Types:** [`FBaseDashboard`](https://docs.univer.ai/reference/facade/base-dashboard.md)

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

### `FBase.getPivotView`

Returns a Pivot View by id.

```typescript
getPivotView(tableId: string, viewId: string): FBasePivotView | null
```

**Parameters**

* `tableId` — Required. Stable table id.
* `viewId` — Required. Stable Pivot View id.

**Returns**

The Pivot View Facade, or null when absent or not a Pivot View.

**Examples**

```ts
const pivot = univerAPI.getActiveBase()?.getPivotView('orders', 'revenue-pivot')
```

**Types:** [`FBasePivotView`](https://docs.univer.ai/reference/facade/base-pivot-view.md)

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

### `FBase.getPivotViews`

Returns all Pivot Views in a table's persisted view order.

```typescript
getPivotViews(tableId: string): FBasePivotView[]
```

**Parameters**

* `tableId` — Required. Stable table id.

**Returns**

Pivot View Facades, or an empty array when the table does not exist.

**Examples**

```ts
const pivots = univerAPI.getActiveBase()?.getPivotViews('orders') ?? []
```

**Types:** [`FBasePivotView`](https://docs.univer.ai/reference/facade/base-pivot-view.md)

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