# Tables, Fields & Records

- Human documentation: [https://docs.univer.ai/guides/bases/model/tables-fields-records](https://docs.univer.ai/guides/bases/model/tables-fields-records)

- Agent Markdown: [https://docs.univer.ai/guides/bases/model/tables-fields-records.md](https://docs.univer.ai/guides/bases/model/tables-fields-records.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [bases/model/tables-fields-records.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/bases/model/tables-fields-records.mdx)

---

A Base contains ordered tables. Each table contains field definitions, record values, optional cell data matrices, resources, views, and indexes used by rendering and lookup logic.

New tables start with zero records; add records explicitly through the Facade API or imported snapshot data.

## Table snapshot

| Property       | Type                                | Description                                      |
| -------------- | ----------------------------------- | ------------------------------------------------ |
| id             | `string`                            | Table id.                                        |
| name           | `string`                            | Table name.                                      |
| fields         | `Record\<string, IFieldSnapshot\>`  | Field definitions keyed by field id.             |
| fieldOrder     | `string[]`                          | Ordered list of field ids.                       |
| records        | `Record\<string, IRecordSnapshot\>` | Record data keyed by record id.                  |
| recordOrder?   | `string[]`                          | Ordered list of record ids.                      |
| primaryFieldId | `string`                            | Primary field id.                                |
| views          | `Record\<string, IViewSnapshot\>`   | Views keyed by view id.                          |
| viewOrder      | `string[]`                          | Ordered list of view ids.                        |
| resources?     | `IBaseResources`                    | Shared option, member, and attachment resources. |

## Field snapshot

| Property      | Type                        | Description                          |
| ------------- | --------------------------- | ------------------------------------ |
| id            | `string`                    | Field id.                            |
| name          | `string`                    | Field name.                          |
| description?  | `string`                    | Field description.                   |
| type          | `BaseFieldType`             | Field type.                          |
| config        | `Record\<string, unknown\>` | Type-specific field config.          |
| defaultValue? | `BaseCellValue`             | Default value for new records.       |
| system?       | `boolean`                   | Whether the field is system-managed. |
| readonly?     | `boolean`                   | Whether values are read-only.        |

## Field types

Common field types include `text`, `number`, `currency`, `progress`, `rating`, `checkbox`, `singleSelect`, `multiSelect`, `person`, `group`, `date`, `attachment`, `formula`, `createdAt`, `updatedAt`, `createdBy`, and `updatedBy`.

Use facade enums when building application code:

```ts
const field = table.addField('Due date', univerAPI.Enum.BaseFieldType.Date)
```

## Record snapshot

| Property   | Type                              | Description               |
| ---------- | --------------------------------- | ------------------------- |
| id         | `string`                          | Record id.                |
| values     | `Record\<string, BaseCellValue\>` | Values keyed by field id. |
| orderKey   | `string`                          | Stable ordering key.      |
| createdAt  | `number`                          | Creation timestamp.       |
| updatedAt  | `number`                          | Update timestamp.         |
| createdBy? | `string`                          | Creator id.               |
| updatedBy? | `string`                          | Last updater id.          |

## Facade example

```ts
const table = base.insertTable('Tasks', { primaryFieldName: 'Title' })
const title = table.getPrimaryField()
const status = table.addField('Status', univerAPI.Enum.BaseFieldType.SingleSelect)

const record = table.addRecord({
  [title.getId()]: 'Write guide',
  [status.getId()]: 'In progress',
})
```