# Table

**Kind:** Class

Model class representing a table. Every `Base` has one or more tables.

```js
import {useBase} from '@airtable/blocks/interface/ui';

function App() {
    const base = useBase();
    const table = base.getTables()[0];
    if (table) {
        console.log('The name of this table is', table.name);
    }
}
```

## Properties

### `description`

Type: `string | null`

The description of the table, if it has one. Can be watched.

```js
console.log(myTable.description);
// => 'This is my table'
```

### `fields`

Type: `Array<Field>`

The fields in this table. The order is arbitrary, since fields are
only ordered in the context of a specific view.

Can be watched to know when fields are created or deleted.

```js
console.log(`This table has ${myTable.fields.length} fields`);
```

### `id`

Type: `string`

The ID for this model.

### `isDeleted`

Type: `boolean`

`true` if the model has been deleted, and `false` otherwise.

In general, it's best to avoid keeping a reference to an object past the
current event loop, since it may be deleted and trying to access any data
of a deleted object (other than its ID) will throw. But if you keep a
reference, you can use `isDeleted` to check that it's safe to access the
model's data.

### `name`

Type: `string`

The name of the table. Can be watched.

```js
console.log(myTable.name);
// => 'Table 1'
```

### `primaryField`

Type: `Field`

The table's primary field. Every table has exactly one primary
field. The primary field of a table will not change.

```js
console.log(myTable.primaryField.name);
// => 'Name'
```

## Methods

### `checkPermissionToExpandRecords()`

Checks whether records in this table can be expanded.

Returns `{hasPermission: true}` if records can be expanded,
`{hasPermission: false, reasonDisplayString: string}` otherwise.

**Returns:** `PermissionCheckResult`

```js
const expandRecordsCheckResult = table.checkPermissionToExpandRecords();
if (!expandRecordsCheckResult.hasPermission) {
    alert(expandRecordsCheckResult.reasonDisplayString);
}
```

### `checkPermissionsForCreateRecord(fields?)`

Checks whether the current user has permission to create the specified record.

Accepts partial input, in the same format as `createRecordAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can create the specified record,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `fields?` (`ObjectMap<FieldId | string, unknown | void>`) — object mapping `FieldId` or field name to value for that field.

**Returns:** `PermissionCheckResult`

```js
// Check if user can create a specific record, when you already know what
// fields/cell values will be set for the record.
const createRecordCheckResult = table.checkPermissionsForCreateRecord({
    'Project Name': 'Advertising campaign',
    'Budget': 100,
});
if (!createRecordCheckResult.hasPermission) {
    alert(createRecordCheckResult.reasonDisplayString);
}

// Like createRecordAsync, you can use either field names or field IDs.
const checkResultWithFieldIds = table.checkPermissionsForCreateRecord({
    [projectNameField.id]: 'Cat video',
    [budgetField.id]: 200,
});

// Check if user could potentially create a record.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating a record.)
const createUnknownRecordCheckResult =
    table.checkPermissionsForCreateRecord();
```

### `checkPermissionsForCreateRecords(records?)`

Checks whether the current user has permission to create the specified records.

Accepts partial input, in the same format as `createRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can create the specified records,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `records?` (`ReadonlyArray<object>`) — Array of objects mapping `FieldId` or field name to value for that field.

**Returns:** `PermissionCheckResult`

```js
// Check if user can create specific records, when you already know what
// fields/cell values will be set for the records.
const createRecordsCheckResult = table.checkPermissionsForCreateRecords([
    // Like createRecordsAsync, fields can be specified by name or ID
    {
         fields: {
             'Project Name': 'Advertising campaign',
             'Budget': 100,
         },
    },
    {
         fields: {
             [projectNameField.id]: 'Cat video',
             [budgetField.id]: 200,
         },
    },
    {},
]);
if (!createRecordsCheckResult.hasPermission) {
    alert(createRecordsCheckResult.reasonDisplayString);
}

// Check if user could potentially create records.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating records.)
// Equivalent to table.checkPermissionsForCreateRecord()
const createUnknownRecordCheckResult =
    table.checkPermissionsForCreateRecords();
```

### `checkPermissionsForDeleteRecord(recordOrRecordId?)`

Checks whether the current user has permission to delete the specified record.

Accepts optional input, in the same format as `deleteRecordAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can delete the specified record,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `recordOrRecordId?` (`Record | RecordId`) — the record to be deleted

**Returns:** `PermissionCheckResult`

```js
// Check if user can delete a specific record
const deleteRecordCheckResult =
    table.checkPermissionsForDeleteRecord(record);
if (!deleteRecordCheckResult.hasPermission) {
    alert(deleteRecordCheckResult.reasonDisplayString);
}

// Check if user could potentially delete a record.
// Use when you don't know the specific record you want to delete yet (for
// example, to show/hide UI controls that let you select a record to delete).
const deleteUnknownRecordCheckResult =
    table.checkPermissionsForDeleteRecord();
```

### `checkPermissionsForDeleteRecords(recordsOrRecordIds?)`

Checks whether the current user has permission to delete the specified records.

Accepts optional input, in the same format as `deleteRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can delete the specified records,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `recordsOrRecordIds?` (`ReadonlyArray<Record | RecordId>`) — the records to be deleted

**Returns:** `PermissionCheckResult`

```js
// Check if user can delete specific records
const deleteRecordsCheckResult =
    table.checkPermissionsForDeleteRecords([record1, record2]);
if (!deleteRecordsCheckResult.hasPermission) {
    alert(deleteRecordsCheckResult.reasonDisplayString);
}

// Check if user could potentially delete records.
// Use when you don't know the specific records you want to delete yet (for
// example, to show/hide UI controls that let you select records to delete).
// Equivalent to table.hasPermissionToDeleteRecord()
const deleteUnknownRecordsCheckResult =
    table.checkPermissionsForDeleteRecords();
```

### `checkPermissionsForUpdateRecord(recordOrRecordId?, fields?)`

Checks whether the current user has permission to perform the given record update.

Accepts partial input, in the same format as `updateRecordAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can update the specified record,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `recordOrRecordId?` (`Record | RecordId`) — the record to update
- `fields?` (`ObjectMap<FieldId | string, unknown | void>`) — cell values to update in that record, specified as object mapping `FieldId` or field name to value for that field.

**Returns:** `PermissionCheckResult`

```js
// Check if user can update specific fields for a specific record.
const updateRecordCheckResult =
    table.checkPermissionsForUpdateRecord(record, {
        'Post Title': 'How to make: orange-mango pound cake',
        'Publication Date': '2020-01-01',
    });
if (!updateRecordCheckResult.hasPermission) {
    alert(updateRecordCheckResult.reasonDisplayString);
}

// Like updateRecordAsync, you can use either field names or field IDs.
const updateRecordCheckResultWithFieldIds =
    table.checkPermissionsForUpdateRecord(record, {
        [postTitleField.id]: 'Cake decorating tips & tricks',
        [publicationDateField.id]: '2020-02-02',
    });

// Check if user could update a given record, when you don't know the
// specific fields that will be updated yet (e.g. to check whether you should
// allow a user to select a certain record to update).
const updateUnknownFieldsCheckResult =
    table.checkPermissionsForUpdateRecord(record);

// Check if user could update specific fields, when you don't know the
// specific record that will be updated yet. (for example, if the field is
// selected by the user and you want to check if your extension can write to it).
const updateUnknownRecordCheckResult =
    table.checkPermissionsForUpdateRecord(undefined, {
        'My field name': 'updated value',
        // You can use undefined if you know you're going to update a field,
        // but don't know the new cell value yet.
        'Another field name': undefined,
    });

// Check if user could perform updates within the table, without knowing the
// specific record or fields that will be updated yet (e.g., to render your
// extension in "read only" mode).
const updateUnknownRecordAndFieldsCheckResult =
    table.checkPermissionsForUpdateRecord();
```

### `checkPermissionsForUpdateRecords(records?)`

Checks whether the current user has permission to perform the given record updates.

Accepts partial input, in the same format as `updateRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

Returns `{hasPermission: true}` if the current user can update the specified records,
`{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
used to display an error message to the user.

**Parameters:**
- `records?` (`ReadonlyArray<object>`) — Array of objects containing recordId and fields/cellValues to update for that record (specified as an object mapping `FieldId` or field name to cell value)

**Returns:** `PermissionCheckResult`

```js
const recordsToUpdate = [
    {
        // Validating a complete record update
        id: record1.id,
        fields: {
            'Post Title': 'How to make: orange-mango pound cake',
            'Publication Date': '2020-01-01',
        },
    },
    {
        // Like updateRecordsAsync, fields can be specified by name or ID
        id: record2.id,
        fields: {
            [postTitleField.id]: 'Cake decorating tips & tricks',
            [publicationDateField.id]: '2020-02-02',
        },
    },
    {
        // Validating an update to a specific record, not knowing what
        // fields will be updated
        id: record3.id,
    },
    {
        // Validating an update to specific cell values, not knowing what
        // record will be updated
        fields: {
            'My field name': 'updated value for unknown record',
            // You can use undefined if you know you're going to update a
            // field, but don't know the new cell value yet.
            'Another field name': undefined,
        },
    },
];

const updateRecordsCheckResult =
    table.checkPermissionsForUpdateRecords(recordsToUpdate);
if (!updateRecordsCheckResult.hasPermission) {
    alert(updateRecordsCheckResult.reasonDisplayString);
}

// Check if user could potentially update records.
// Equivalent to table.checkPermissionsForUpdateRecord()
const updateUnknownRecordAndFieldsCheckResult =
    table.checkPermissionsForUpdateRecords();
```

### `createRecordAsync(fields)`

Creates a new record with the specified cell values.

Throws an error if the user does not have permission to create the given records, or
if invalid input is provided (eg. invalid cell values).

Refer to `FieldType` for cell value write formats.

This action is asynchronous: `await` the returned promise if you wish to wait for the new
record to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

The returned promise will resolve to the RecordId of the new record once it is persisted.

**Parameters:**
- `fields` (`ObjectMap<FieldId | string, unknown>`) — object mapping `FieldId` or field name to value for that field.

**Returns:** `Promise<RecordId>`

```js
function createNewRecord(recordFields) {
    if (table.hasPermissionToCreateRecord(recordFields)) {
        table.createRecordAsync(recordFields);
    }
    // You can now access the new record in your extension (eg
    // `table.selectRecords()`) but it is still being saved to Airtable
    // servers (e.g. other users may not be able to see it yet).
}

async function createNewRecordAsync(recordFields) {
    if (table.hasPermissionToCreateRecord(recordFields)) {
        const newRecordId = await table.createRecordAsync(recordFields);
    }
    // New record has been saved to Airtable servers.
    alert(`new record with ID ${newRecordId} has been created`);
}

// Fields can be specified by name or ID
createNewRecord({
    'Project Name': 'Advertising campaign',
    'Budget': 100,
});
createNewRecord({
    [projectNameField.id]: 'Cat video',
    [budgetField.id]: 200,
});

// Cell values should generally have format matching the output of
// record.getCellValue() for the field being updated
createNewRecord({
    'Project Name': 'Cat video 2'
    'Category (single select)': {name: 'Video'},
    'Tags (multiple select)': [{name: 'Cats'}, {id: 'someChoiceId'}],
    'Assets (attachment)': [{url: 'http://mywebsite.com/cats.mp4'}],
    'Related projects (linked records)': [{id: 'someRecordId'}],
});
```

### `createRecordsAsync(records)`

Creates new records with the specified cell values.

Throws an error if the user does not have permission to create the given records, or
if invalid input is provided (eg. invalid cell values).

Refer to `FieldType` for cell value write formats.

You may only create up to 50 records in one call to `createRecordsAsync`.
See [Write back to Airtable](https://airtable.com/developers/interface-extensions/guides/write-back-to-airtable.md#size-limits-rate-limits) for
more information about write limits.

This action is asynchronous: `await` the returned promise if you wish to wait for the new
record to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

The returned promise will resolve to an array of RecordIds of the new records once the new
records are persisted.

**Parameters:**
- `records` (`ReadonlyArray<object>`) — Array of objects with a `fields` key mapping `FieldId` or field name to value for that field.

**Returns:** `Promise<Array<RecordId>>`

```js
const recordDefs = [
    // Fields can be specified by name or ID
    {
         fields: {
             'Project Name': 'Advertising campaign',
             'Budget': 100,
         },
    },
    {
         fields: {
             [projectNameField.id]: 'Cat video',
             [budgetField.id]: 200,
         },
    },
    // Specifying no fields will create a new record with no cell values set
    {
         fields: {},
    },
    // Cell values should generally have format matching the output of
    // record.getCellValue() for the field being updated
    {
         fields: {
             'Project Name': 'Cat video 2'
             'Category (single select)': {name: 'Video'},
             'Tags (multiple select)': [{name: 'Cats'}, {id: 'choiceId'}],
             'Assets (attachment)': [{url: 'http://mywebsite.com/cats.mp4'}],
             'Related projects (linked records)': [{id: 'someRecordId'}],
         },
    },
];

function createNewRecords() {
    if (table.hasPermissionToCreateRecords(recordDefs)) {
        table.createRecordsAsync(recordDefs);
    }
    // You can now access the new records in your extension (e.g.
    // `table.selectRecords()`) but they are still being saved to Airtable
    // servers (e.g. other users may not be able to see them yet.)
}

async function createNewRecordsAsync() {
    if (table.hasPermissionToCreateRecords(recordDefs)) {
        const newRecordIds = await table.createRecordsAsync(recordDefs);
    }
    // New records have been saved to Airtable servers.
    alert(`new records with IDs ${newRecordIds} have been created`);
}
```

### `deleteRecordAsync(recordOrRecordId)`

Delete the given record.

Throws an error if the user does not have permission to delete the given record.

This action is asynchronous: `await` the returned promise if you wish to wait for the
delete to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

**Parameters:**
- `recordOrRecordId` (`Record | RecordId`) — the record to be deleted

**Returns:** `Promise<void>`

```js
function deleteRecord(record) {
    if (table.hasPermissionToDeleteRecord(record)) {
        table.deleteRecordAsync(record);
    }
    // The record is now deleted within your extension (eg will not be returned
    // in `table.selectRecords`) but it is still being saved to Airtable
    // servers (e.g. it may not look deleted to other users yet).
}

async function deleteRecordAsync(record) {
    if (table.hasPermissionToDeleteRecord(record)) {
        await table.deleteRecordAsync(record);
    }
    // Record deletion has been saved to Airtable servers.
    alert('record has been deleted');
}
```

### `deleteRecordsAsync(recordsOrRecordIds)`

Delete the given records.

Throws an error if the user does not have permission to delete the given records.

You may only delete up to 50 records in one call to `deleteRecordsAsync`.
See [Write back to Airtable](https://airtable.com/developers/interface-extensions/guides/write-back-to-airtable.md#size-limits-rate-limits) for
more information about write limits.

This action is asynchronous: `await` the returned promise if you wish to wait for the
delete to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

**Parameters:**
- `recordsOrRecordIds` (`ReadonlyArray<Record | RecordId>`) — Array of Records and RecordIds

**Returns:** `Promise<void>`

```js
function deleteRecords(records) {
    if (table.hasPermissionToDeleteRecords(records)) {
        table.deleteRecordsAsync(records);
    }
    // The records are now deleted within your extension (eg will not be
    // returned in `table.selectRecords()`) but are still being saved to
    // Airtable servers (e.g. they may not look deleted to other users yet).
}

async function deleteRecordsAsync(records) {
    if (table.hasPermissionToDeleteRecords(records)) {
        await table.deleteRecordsAsync(records);
    }
    // Record deletions have been saved to Airtable servers.
    alert('records have been deleted');
}
```

### `getField(fieldIdOrName)`

The field matching the given ID or name. Throws if no matching field exists within this table.
Use `getFieldIfExists` instead if you are unsure whether a field exists with the given
name/ID.

This method is convenient when building an extension for a specific base, but for more generic
extensions the best practice is to use the `getFieldById` or `getFieldByName` methods
instead.

**Parameters:**
- `fieldIdOrName` (`FieldId | string`) — The ID or name of the field you're looking for.

**Returns:** `Field`

### `getFieldById(fieldId)`

Gets the field matching the given ID. Throws if that field does not exist in this table. Use
`getFieldByIdIfExists` instead if you are unsure whether a field exists with the given
ID.

**Parameters:**
- `fieldId` (`FieldId`) — The ID of the field.

**Returns:** `Field`

```js
const fieldId = 'fldxxxxxxxxxxxxxx';
const field = myTable.getFieldById(fieldId);
console.log(field.name);
// => 'Name'
```

### `getFieldByIdIfExists(fieldId)`

Gets the field matching the given ID, or `null` if that field does not exist in this table.

**Parameters:**
- `fieldId` (`FieldId`) — The ID of the field.

**Returns:** `Field | null`

```js
const fieldId = 'fldxxxxxxxxxxxxxx';
const field = myTable.getFieldByIdIfExists(fieldId);
if (field !== null) {
    console.log(field.name);
} else {
    console.log('No field exists with that ID');
}
```

### `getFieldByName(fieldName)`

Gets the field matching the given name. Throws if no field exists with that name in this
table. Use `getFieldByNameIfExists` instead if you are unsure whether a field exists
with the given name.

**Parameters:**
- `fieldName` (`string`) — The name of the field you're looking for.

**Returns:** `Field`

```js
const field = myTable.getFieldByName('Name');
console.log(field.id);
// => 'fldxxxxxxxxxxxxxx'
```

### `getFieldByNameIfExists(fieldName)`

Gets the field matching the given name, or `null` if no field exists with that name in this
table.

**Parameters:**
- `fieldName` (`string`) — The name of the field you're looking for.

**Returns:** `Field | null`

```js
const field = myTable.getFieldByNameIfExists('Name');
if (field !== null) {
    console.log(field.id);
} else {
    console.log('No field exists with that name');
}
```

### `getFieldIfExists(fieldIdOrName)`

The field matching the given ID or name. Returns `null` if no matching field exists within
this table.

This method is convenient when building an extension for a specific base, but for more generic
extensions the best practice is to use the `getFieldByIdIfExists` or
`getFieldByNameIfExists` methods instead.

**Parameters:**
- `fieldIdOrName` (`FieldId | string`) — The ID or name of the field you're looking for.

**Returns:** `Field | null`

### `hasPermissionToCreateRecord(fields?)`

An alias for `checkPermissionsForCreateRecord(fields).hasPermission`.

Checks whether the current user has permission to create the specified record.

Accepts partial input, in the same format as `createRecordAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `fields?` (`ObjectMap<FieldId | string, unknown | void>`) — object mapping `FieldId` or field name to value for that field.

**Returns:** `boolean`

```js
// Check if user can create a specific record, when you already know what
// fields/cell values will be set for the record.
const canCreateRecord = table.hasPermissionToCreateRecord({
    'Project Name': 'Advertising campaign',
    'Budget': 100,
});
if (!canCreateRecord) {
    alert('not allowed!');
}

// Like createRecordAsync, you can use either field names or field IDs.
const canCreateRecordWithFieldIds = table.hasPermissionToCreateRecord({
    [projectNameField.id]: 'Cat video',
    [budgetField.id]: 200,
});

// Check if user could potentially create a record.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating a record.)
const canCreateUnknownRecord = table.hasPermissionToCreateRecord();
```

### `hasPermissionToCreateRecords(records?)`

An alias for `checkPermissionsForCreateRecords(records).hasPermission`.

Checks whether the current user has permission to create the specified records.

Accepts partial input, in the same format as `createRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `records?` (`ReadonlyArray<object>`) — Array of objects mapping `FieldId` or field name to value for that field.

**Returns:** `boolean`

```js
// Check if user can create specific records, when you already know what fields/cell values
// will be set for the records.
const canCreateRecords = table.hasPermissionToCreateRecords([
    // Like createRecordsAsync, fields can be specified by name or ID
    {
         fields: {
             'Project Name': 'Advertising campaign',
             'Budget': 100,
         }
    },
    {
         fields: {
             [projectNameField.id]: 'Cat video',
             [budgetField.id]: 200,
         }
    },
    {},
]);
if (!canCreateRecords) {
    alert('not allowed');
}

// Check if user could potentially create records.
// Use when you don't know the specific fields/cell values yet (for example,
// to show or hide UI controls that let you start creating records).
// Equivalent to table.hasPermissionToCreateRecord()
const canCreateUnknownRecords = table.hasPermissionToCreateRecords();
```

### `hasPermissionToDeleteRecord(recordOrRecordId?)`

An alias for `checkPermissionsForDeleteRecord(recordOrRecordId).hasPermission`.

Checks whether the current user has permission to delete the specified record.

Accepts optional input, in the same format as `deleteRecordAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `recordOrRecordId?` (`Record | RecordId`) — the record to be deleted

**Returns:** `boolean`

```js
// Check if user can delete a specific record
const canDeleteRecord = table.hasPermissionToDeleteRecord(record);
if (!canDeleteRecord) {
    alert('not allowed');
}

// Check if user could potentially delete a record.
// Use when you don't know the specific record you want to delete yet (for
// example, to show/hide UI controls that let you select a record to delete).
const canDeleteUnknownRecord = table.hasPermissionToDeleteRecord();
```

### `hasPermissionToDeleteRecords(recordsOrRecordIds?)`

An alias for `checkPermissionsForDeleteRecords(recordsOrRecordIds).hasPermission`.

Checks whether the current user has permission to delete the specified records.

Accepts optional input, in the same format as `deleteRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `recordsOrRecordIds?` (`ReadonlyArray<Record | RecordId>`) — the records to be deleted

**Returns:** `boolean`

```js
// Check if user can delete specific records
const canDeleteRecords =
    table.hasPermissionToDeleteRecords([record1, record2]);
if (!canDeleteRecords) {
    alert('not allowed!');
}

// Check if user could potentially delete records.
// Use when you don't know the specific records you want to delete yet (for
// example, to show/hide UI controls that let you select records to delete).
// Equivalent to table.hasPermissionToDeleteRecord()
const canDeleteUnknownRecords = table.hasPermissionToDeleteRecords();
```

### `hasPermissionToExpandRecords()`

An alias for `checkPermissionsForExpandRecords().hasPermission`.

Whether records in this table can be expanded.

**Returns:** `boolean`

```js
const isRecordExpansionEnabled = table.hasPermissionToExpandRecords();
if (isRecordExpansionEnabled) {
    expandRecord(record);
}
```

### `hasPermissionToUpdateRecord(recordOrRecordId?, fields?)`

An alias for `checkPermissionsForUpdateRecord(recordOrRecordId, fields).hasPermission`.

Checks whether the current user has permission to perform the given record update.

Accepts partial input, in the same format as `updateRecordAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `recordOrRecordId?` (`Record | RecordId`) — the record to update
- `fields?` (`ObjectMap<FieldId | string, unknown | void>`) — cell values to update in that record, specified as object mapping `FieldId` or field name to value for that field.

**Returns:** `boolean`

```js
// Check if user can update specific fields for a specific record.
const canUpdateRecord = table.hasPermissionToUpdateRecord(record, {
    'Post Title': 'How to make: orange-mango pound cake',
    'Publication Date': '2020-01-01',
});
if (!canUpdateRecord) {
    alert('not allowed!');
}

// Like updateRecordAsync, you can use either field names or field IDs.
const canUpdateRecordWithFieldIds =
    table.hasPermissionToUpdateRecord(record, {
        [postTitleField.id]: 'Cake decorating tips & tricks',
        [publicationDateField.id]: '2020-02-02',
    });

// Check if user could update a given record, when you don't know the
// specific fields that will be updated yet (e.g. to check whether you should
// allow a user to select a certain record to update).
const canUpdateUnknownFields = table.hasPermissionToUpdateRecord(record);

// Check if user could update specific fields, when you don't know the
// specific record that will be updated yet (e.g. if the field is selected
// by the user and you want to check if your extension can write to it).
const canUpdateUnknownRecord =
    table.hasPermissionToUpdateRecord(undefined, {
        'My field name': 'updated value',
        // You can use undefined if you know you're going to update a field,
        // but don't know the new cell value yet.
        'Another field name': undefined,
    });

// Check if user could perform updates within the table, without knowing the
// specific record or fields that will be updated yet. (for example, to
// render your extension in "read only" mode)
const canUpdateUnknownRecordAndFields = table.hasPermissionToUpdateRecord();
```

### `hasPermissionToUpdateRecords(records?)`

An alias for `checkPermissionsForUpdateRecords(records).hasPermission`.

Checks whether the current user has permission to perform the given record updates.

Accepts partial input, in the same format as `updateRecordsAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `records?` (`ReadonlyArray<object>`) — Array of objects containing recordId and fields/cellValues to update for that record (specified as an object mapping `FieldId` or field name to cell value)

**Returns:** `boolean`

```js
const recordsToUpdate = [
    {
        // Validating a complete record update
        id: record1.id,
        fields: {
            'Post Title': 'How to make: orange-mango pound cake',
            'Publication Date': '2020-01-01',
        },
    },
    {
        // Like updateRecordsAsync, fields can be specified by name or ID
        id: record2.id,
        fields: {
            [postTitleField.id]: 'Cake decorating tips & tricks',
            [publicationDateField.id]: '2020-02-02',
        },
    },
    {
        // Validating an update to a specific record, not knowing what
        // fields will be updated
        id: record3.id,
    },
    {
        // Validating an update to specific cell values, not knowing what
        // record will be updated
        fields: {
            'My field name': 'updated value for unknown record',
            // You can use undefined if you know you're going to update a
            // field, but don't know the new cell value yet.
            'Another field name': undefined,
        },
    },
];

const canUpdateRecords = table.hasPermissionToUpdateRecords(recordsToUpdate);
if (!canUpdateRecords) {
    alert('not allowed');
}

// Check if user could potentially update records.
// Equivalent to table.hasPermissionToUpdateRecord()
const canUpdateUnknownRecordsAndFields =
    table.hasPermissionToUpdateRecords();
```

### `toString()`

A string representation of the model for use in debugging.

**Returns:** `string`

### `unwatch(keys, callback, context?)`

Unwatch keys watched with `.watch`.

Should be called with the same arguments given to `.watch`.

Returns the array of keys that were unwatched.

**Parameters:**
- `keys` (`WatchableTableKeyCore | WatchableKeys | ReadonlyArray<WatchableTableKeyCore | WatchableKeys>`) — the keys to unwatch
- `callback` (`object`) — the function passed to `.watch` for these keys
- `context?` (`FlowAnyObject | null`) — the context that was passed to `.watch` for this `callback`

**Returns:** `Array<WatchableTableKeyCore | WatchableKeys>`

### `updateRecordAsync(recordOrRecordId, fields)`

Updates cell values for a record.

Throws an error if the user does not have permission to update the given cell values in
the record, or if invalid input is provided (eg. invalid cell values).

Refer to `FieldType` for cell value write formats.

This action is asynchronous: `await` the returned promise if you wish to wait for the updated
cell values to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

**Parameters:**
- `recordOrRecordId` (`Record | RecordId`) — the record to update
- `fields` (`ObjectMap<FieldId | string, unknown>`) — cell values to update in that record, specified as object mapping `FieldId` or field name to value for that field.

**Returns:** `Promise<void>`

```js
function updateRecord(record, recordFields) {
    if (table.hasPermissionToUpdateRecord(record, recordFields)) {
        table.updateRecordAsync(record, recordFields);
    }
    // The updated values will now show in your extension (eg in
    // `table.selectRecords()` result) but are still being saved to Airtable
    // servers (e.g. other users may not be able to see them yet).
}

async function updateRecordAsync(record, recordFields) {
    if (table.hasPermissionToUpdateRecord(record, recordFields)) {
        await table.updateRecordAsync(record, recordFields);
    }
    // New record has been saved to Airtable servers.
    alert(`record with ID ${record.id} has been updated`);
}

// Fields can be specified by name or ID
updateRecord(record1, {
    'Post Title': 'How to make: orange-mango pound cake',
    'Publication Date': '2020-01-01',
});
updateRecord(record2, {
    [postTitleField.id]: 'Cake decorating tips & tricks',
    [publicationDateField.id]: '2020-02-02',
});

// Cell values should generally have format matching the output of
// record.getCellValue() for the field being updated
updateRecord(record1, {
    'Category (single select)': {name: 'Recipe'},
    'Tags (multiple select)': [{name: 'Desserts'}, {id: 'someChoiceId'}],
    'Images (attachment)': [{url: 'http://mywebsite.com/cake.png'}],
    'Related posts (linked records)': [{id: 'someRecordId'}],
});
```

### `updateRecordsAsync(records)`

Updates cell values for records.

Throws an error if the user does not have permission to update the given cell values in
the records, or if invalid input is provided (eg. invalid cell values).

Refer to `FieldType` for cell value write formats.

You may only update up to 50 records in one call to `updateRecordsAsync`.
See [Write back to Airtable](https://airtable.com/developers/interface-extensions/guides/write-back-to-airtable.md) for more information
about write limits.

This action is asynchronous: `await` the returned promise if you wish to wait for the
updates to be persisted to Airtable servers.
Updates are applied optimistically locally, so your changes will be reflected in your extension
before the promise resolves.

**Parameters:**
- `records` (`ReadonlyArray<object>`) — Array of objects containing recordId and fields/cellValues to update for that record (specified as an object mapping `FieldId` or field name to cell value)

**Returns:** `Promise<void>`

```js
const recordsToUpdate = [
    // Fields can be specified by name or ID
    {
        id: record1.id,
        fields: {
            'Post Title': 'How to make: orange-mango pound cake',
            'Publication Date': '2020-01-01',
        },
    },
    {
        id: record2.id,
        fields: {
            // Sets the cell values to be empty.
            'Post Title': '',
            'Publication Date': '',
        },
    },
    {
        id: record3.id,
        fields: {
            [postTitleField.id]: 'Cake decorating tips & tricks',
            [publicationDateField.id]: '2020-02-02',
        },
    },
    // Cell values should generally have format matching the output of
    // record.getCellValue() for the field being updated
    {
        id: record4.id,
        fields: {
            'Category (single select)': {name: 'Recipe'},
            'Tags (multiple select)': [{name: 'Desserts'}, {id: 'choiceId'}],
            'Images (attachment)': [{url: 'http://mywebsite.com/cake.png'}],
            'Related posts (linked records)': [{id: 'someRecordId'}],
        },
    },
];

function updateRecords() {
    if (table.hasPermissionToUpdateRecords(recordsToUpdate)) {
        table.updateRecordsAsync(recordsToUpdate);
    }
    // The records are now updated within your extension (eg will be reflected in
    // `table.selectRecords()`) but are still being saved to Airtable servers
    // (e.g. they may not be updated for other users yet).
}

async function updateRecordsAsync() {
    if (table.hasPermissionToUpdateRecords(recordsToUpdate)) {
        await table.updateRecordsAsync(recordsToUpdate);
    }
    // Record updates have been saved to Airtable servers.
    alert('records have been updated');
}
```

### `watch(keys, callback, context?)`

Get notified of changes to the model.

Every call to `.watch` should have a matching call to `.unwatch`.

Returns the array of keys that were watched.

**Parameters:**
- `keys` (`WatchableTableKeyCore | WatchableKeys | ReadonlyArray<WatchableTableKeyCore | WatchableKeys>`) — the keys to watch
- `callback` (`object`) — a function to call when those keys change
- `context?` (`FlowAnyObject | null`) — an optional context for `this` in `callback`.

**Returns:** `Array<WatchableTableKeyCore | WatchableKeys>`