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
string
The ID of this table.
// Show the ID of a table:let table = base.getTable("Tasks");console.log(`Table id: ${table.id}`);
name
string
The name of the table.
// Show the names of every table in the basefor (let table of base.tables) {console.log(`Your base has a table called '${table.name}'.`);}
description
string | null
The description of this table, if it has one.
// Show the description (if there is one) of every table in the basefor (let table of base.tables) {console.log(`## ${table.name} description:`);if (table.description) {console.log(table.description);} else {console.log('No description');}}
url
string
The URL for the table. You can visit this URL in the browser to be taken to the table in the Airtable UI.
// Show a link to open every table in the basefor (let table of base.tables) {console.log(`[Click to open ${table.name}](${table.url})`);}
fields
Array<Field>
The fields in this table. The order is arbitrary, since fields are only ordered in the context of a specific view.
// Show an interactive inspector for every field in "Projects"let table = base.getTable("Projects");for (let field of table.fields) {console.log(field);}
views
Array<View>
The views in this table.
// 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 (idOrName: string) => Field;
Parameter name | Description |
---|---|
idOrName | The ID or name of the field you want to retrieve. |
Get a field in the table according to its id or name.
// 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 (idOrName: string) => View;
Parameter name | Description |
---|---|
idOrName | The ID or name of the view you want to retrieve. |
Get a view in the table according to its id or name.
// 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
(name: string, type: FieldType, options?: {[key: string]: unknown} | null, description?: string | null) => Promise<string>
Parameter name | Description |
---|---|
name | Name for the field. Must be case-insensitive unique. |
type | Type for the field. See Field.type definition for valid values. |
options | Options for the field. Omit for fields without writable options. See Cell values & field options for the options structure of each field type. |
description | Description 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
- 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.
const table = base.getTable("Tasks");const fieldId = await table.createFieldAsync("Notes", "multilineText");
selectRecordsAsync
async function (options?: {sorts?: Array<{field: Field | string,direction?: 'asc' | 'desc',}>,fields?: Array<Field | string>,recordIds?: Array<string>,}) => Promise<RecordQueryResult>;
Parameter name | Description |
---|---|
options | Optional. Options for the query. |
options.sorts | Optional. 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.fields | Optional. 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.recordIds | Optional. 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.
// query for every record in "People"let table = base.getTable("People");let query = await table.selectRecordsAsync({fields: []});console.log(query);
// 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
async function (recordId: string,options?: {fields?: Array<Field | string>,},) => Promise<Record | null>;
Parameter name | Description |
---|---|
recordId | The ID of the record to return. |
options | Optional. Options for the query. |
options.fields | Optional. 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
async function (fields: {[fieldNameOrId: string]: unknown}) => Promise<string>;
Parameter name | Description |
---|---|
fields | An 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.
// Create a record in the Tasks tablelet table = base.getTable("Tasks");let recordId = await table.createRecordAsync({"Description": "Hello world!",});console.log("Created a record!");
createRecordsAsync
async function (records: Array‹{fields: {[fieldNameOrId: string]: unknown}}›) => Promise<Array<string>>;
Parameter name | Description |
---|---|
records | An 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.
// Create three records in the Tasks tablelet 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
async function (recordOrRecordId: Record | string,fields: {[fieldNameOrId: string]: unknown}) => Promise<void>;
Parameter name | Description |
---|---|
recordOrRecordId | The record to update. |
fields | An 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.
// Update a record in the Tasks tablelet 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
async function (records: Array<{id: string,fields: {[fieldNameOrId: string]: unknown},}>) => Promise<void>;
Parameter name | Description |
---|---|
recordOrRecordId | The record to update. |
fields | An 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.
// Update two records in the Tasks tablelet 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
async function (recordOrRecordId: Record | string) => Promise<void>;
Parameter name | Description |
---|---|
recordOrRecordId | The 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.
// Delete a record in the Tasks tablelet 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
async function (recordsOrRecordIds: Array<Record | string>) => Promise<void>;
Parameter name | Description |
---|---|
recordsOrRecordIds | The 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.
// Delete two records in the Tasks tablelet 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!");