Scripting
Model

Table

Table represents each table in your base. You can use it to find all of the views, fields, and records it contains. Each base has at least one table.

Get tables using base.getTable.

id

typedef
string

The ID of this table.

Example
// Show the ID of a table:
let table = base.getTable("Tasks");
console.log(`Table id: ${table.id}`);

name

typedef
string

The name of the table.

Example
// Show the names of every table in the base
for (let table of base.tables) {
console.log(`Your base has a table called '${table.name}'.`);
}

description

typedef
string | null

The description of this table, if it has one.

Example
// Show the description (if there is one) of every table in the base
for (let table of base.tables) {
console.log(`## ${table.name} description:`);
if (table.description) {
console.log(table.description);
} else {
console.log('No description');
}
}

url

typedef
string

The URL for the table. You can visit this URL in the browser to be taken to the table in the Airtable UI.

Example
// Show a link to open every table in the base
for (let table of base.tables) {
console.log(`[Click to open ${table.name}](${table.url})`);
}

fields

typedef
Array<Field>

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

Example
// Show an interactive inspector for every field in "Projects"
let table = base.getTable("Projects");
for (let field of table.fields) {
console.log(field);
}

views

typedef
Array<View>

The views in this table.

Example
// Show an interactive inspector for every view in "Projects"
let table = base.getTable("Projects");
for (let view of table.views) {
console.log(view);
}

getField

function
function (idOrName: string) => Field;
Parameter nameDescription
idOrNameThe ID or name of the field you want to retrieve.

Get a field in the table according to its id or name.

Example
// Get a field by id:
let field1 = base.getTable("Projects").getField("fldN19YsVtTznY5Xw");
console.log(field1);
// Get a field by name:
let field2 = base.getTable("People").getField("Role");
console.log(field2);

getView

function
function (idOrName: string) => View;
Parameter nameDescription
idOrNameThe ID or name of the view you want to retrieve.

Get a view in the table according to its id or name.

Example
// Get a view by id:
let view1 = base.getTable("Tasks").getView("viw5Z4u0SBwthps8r");
console.log(view1);
// Get a view by name:
let view2 = base.getTable("Projects").getView("By Category");
console.log(view2);

createFieldAsync
Scripting Extension only

function
(name: string, type: FieldType, options?: {[key: string]: unknown} | null, description?: string | null) => Promise<string>
Parameter nameDescription
nameName for the field. Must be case-insensitive unique.
typeType for the field. See Field.type definition for valid values.
optionsOptions for the field. Omit for fields without writable options. See Cell values & field options for the options structure of each field type.
descriptionDescription for the field. Is optional and will be '' if not specified or if specified as null.

Creates a new field.

The following field types can be created:

  • checkbox
  • singleSelect
  • multipleSelects
  • singleCollaborator
  • multipleCollaborators
  • number
  • percent
  • currency
  • duration
  • singleLineText
  • email
  • url
  • multilineText
  • phoneNumber
  • richText
  • barcode
  • multipleAttachments
  • date
  • dateTime
  • rating
  • multipleRecordLinks

The following field types cannot be created:

  • formula
  • createdTime
  • rollup
  • count
  • multipleLookupValues
  • autoNumber
  • lastModifiedTime
  • button
  • createdBy
  • lastModifiedBy
  • externalSyncSource
  • aiText

Similar to creating a field from the Airtable UI, the new field will not be visible in views that have other hidden fields and views that are publicly shared.

Throws an error if the user does not have permission to create a field, if invalid name, type, options or description is provided, or if creating fields of this type is not supported. See Cell values & field options for the options format for each field type.

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
const table = base.getTable("Tasks");
const fieldId = await table.createFieldAsync("Notes", "multilineText");

selectRecordsAsync

function
async function (options?: {
sorts?: Array<{
field: Field | string,
direction?: 'asc' | 'desc',
}>,
fields?: Array<Field | string>,
recordIds?: Array<string>,
}) => Promise<RecordQueryResult>;
Parameter nameDescription
optionsOptional. Options for the query.
options.sortsOptional. Pass an array of sorts to control the order of records within the query result. The first sort in the array has the highest priority. If you don't specify sorts, the query result will use an arbitrary (but stable) order.
options.fieldsOptional. Generally, it's a good idea to load as little data into your script as possible - Airtable bases can get pretty big. The fields option lets you make sure that only data relevant to you is loaded. You can specify fields by passing in a Field, ID, or name. Leaving out this option is discouraged, but will be supported for now. Before this changes, we will post a potential deprecation timeline. Note: primary field is not included by default.
options.recordIdsOptional. The IDs of the records to return. If provided, only the records identified in this array will be returned. If none of the IDs are found, an empty result will be returned. A maximum of 100 records can be requested at a time.

Select records from the table. This action is asynchronous: you must add await before each call to this method.

Example
// query for every record in "People"
let table = base.getTable("People");
let query = await table.selectRecordsAsync({fields: []});
console.log(query);
Example
// query for given fields from every record in "Tasks".
let table = base.getTable("Tasks");
let query = await table.selectRecordsAsync({
fields: ["Priority", "Status"],
sorts: [
// sort by "Priority" in ascending order...
{field: "Priority"},
// then by "Status" in descending order.
{field: "Status", direction: "desc"},
]
});
// print ID & "Priority" from each record:
for (let record of query.records) {
console.log(`
**${record.id}**
${record.getCellValueAsString("Priority")}
`);
}

selectRecordAsync

function
async function (
recordId: string,
options?: {
fields?: Array<Field | string>,
},
) => Promise<Record | null>;
Parameter nameDescription
recordIdThe ID of the record to return.
optionsOptional. Options for the query.
options.fieldsOptional. The fields option lets you make sure that only data relevant to you is loaded. You can specify fields by passing in a Field, ID, or name. When selecting a single record, requesting all fields doesn't have the potential problem of loading large amounts of data.

Select a single record from the table. This action is asynchronous: you must add await before each call to this method. If the specified record cannot be found, null will be returned.

createRecordAsync

function
async function (fields: {[fieldNameOrId: string]: unknown}) => Promise<string>;
Parameter nameDescription
fieldsAn object mapping field names or IDs to the cell values for those fields.

Creates a new record with the specified cell values. See cell values & field options for the cell value format for each field type.

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

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Create a record in the Tasks table
let table = base.getTable("Tasks");
let recordId = await table.createRecordAsync({
"Description": "Hello world!",
});
console.log("Created a record!");

createRecordsAsync

function
async function (records: Array{fields: {[fieldNameOrId: string]: unknown}}) => Promise<Array<string>>;
Parameter nameDescription
recordsAn array of objects mapping field names or IDs to the cell values for those fields.

Creates multiple new records with the specified cell values. See cell values & field options for the cell value format for each field type.

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).

You may only create up to 50 records in one call to createRecordsAsync.

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Create three records in the Tasks table
let table = base.getTable("Tasks");
let recordIds = await table.createRecordsAsync([
{
fields: {
"Description": "Alice",
},
},
{
fields: {
"Description": "Bob",
},
},
// Specifying an empty fields object will create a new record with no cell values set
{
fields: {},
},
]);
console.log("Created " + recordIds.length + " records!");

updateRecordAsync

function
async function (
recordOrRecordId: Record | string,
fields: {[fieldNameOrId: string]: unknown}
) => Promise<void>;
Parameter nameDescription
recordOrRecordIdThe record to update.
fieldsAn object mapping field names or IDs to the updated cell values for those fields.

Updates cell values for a record. See cell values & field options for the cell value format for each field type.

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).

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Update a record in the Tasks table
let table = base.getTable("Tasks");
let query = await table.selectRecordsAsync({fields: []});
let recordId = query.records[0].id;
await table.updateRecordAsync(recordId, {
"Description": "Hello again!",
})
console.log("Updated a record!");

updateRecordsAsync

function
async function (records: Array<{
id: string,
fields: {[fieldNameOrId: string]: unknown},
}>) => Promise<void>;
Parameter nameDescription
recordOrRecordIdThe record to update.
fieldsAn array of objects mapping field names or IDs to the updated cell values for those fields.

Updates cell values for multiple records. See cell values & field options for the cell value format for each field type.

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).

You may only update up to 50 records in one call to updateRecordsAsync.

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Update two records in the Tasks table
let table = base.getTable("Tasks");
let query = await table.selectRecordsAsync({fields: []});
let records = query.records;
await table.updateRecordsAsync([
{
id: records[0].id,
fields: {
"Description": "Update one",
},
},
{
id: records[1].id,
fields: {
"Description": "Update two",
},
},
]);
console.log("Updated 2 records!");

deleteRecordAsync

function
async function (recordOrRecordId: Record | string) => Promise<void>;
Parameter nameDescription
recordOrRecordIdThe record to be deleted.

Delete a single record.

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

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Delete a record in the Tasks table
let table = base.getTable("Tasks");
let query = await table.selectRecordsAsync({fields: []});
let recordId = query.records[0].id;
await table.deleteRecordAsync(recordId);
console.log("Deleted a record!");

deleteRecordsAsync

function
async function (recordsOrRecordIds: Array<Record | string>) => Promise<void>;
Parameter nameDescription
recordsOrRecordIdsThe record to be deleted.

Delete multiple 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.

This action is asynchronous: you must add await before each call to this method to ensure it takes effect.

Example
// Delete two records in the Tasks table
let table = base.getTable("Tasks");
let query = await table.selectRecordsAsync({fields: []});
let records = query.records;
await table.deleteRecordsAsync([
records[0].id,
records[1].id,
]);
console.log("Deleted two records!");