Table
The Table object represents a table in your NocoDB base. Its methods let you get, query, and change the records in that table.
Overview
You usually get Table objects through the base object. Table objects are the primary way to:
- Query records using various filters and conditions
- Create, update, and delete records
- Access and modify table fields and views
- Perform bulk operations on table data
Properties
| Property | Type | Description |
|---|---|---|
id | string | The unique identifier of the table |
name | string | The name of the table |
description | string | null | The description of the table (if any) |
fields | Field[] | Array of user-defined fields in the table (no system fields) |
views | View[] | Array of all views defined for the table |
base | Base | Reference to the parent base that this table belongs to |
Methods
getField
Gets a field from the table by its ID or name. This method searches user-defined fields and system fields.
Parameters:
idOrName(string): The ID or name of the field to retrieve
Returns:
Fieldobject if a match is foundnullif no field matches the provided input
Note: The fields property includes only user-defined fields. getField() can get user fields and system fields (for example Created Time, Last Modified Time, etc.)
Example:
// Get a field by name
const titleField = projectsTable.getField('Title');
// Get a field by ID
const statusField = projectsTable.getField('c12345');
// Check if a field exists
if (titleField) {
output.text(`Field "${titleField.name}" found with type: ${titleField.type}`);
} else {
output.text('Field not found.');
}getView
Gets a view from the table by its ID or name.
Parameters:
idOrName(string): The ID or name of the view to retrieve
Returns:
Viewobject if a match is foundnullif no view matches the provided input
Example:
// Get a view by name
const activeProjectsView = projectsTable.getView('Active Projects');
// Get a view by ID
const completedTasksView = projectsTable.getView('viw12345');
// Check if a view exists
if (activeProjectsView) {
output.text(`View "${activeProjectsView.name}" found with type: ${activeProjectsView.type}`);
} else {
output.text('View not found.');
}selectRecordsAsync
Queries records from the table. Filtering and sorting are optional.
Parameters:
options(optional): Object with the following properties:fields(Array<Field | string>): Specific fields to include in the result. If you do not specify fields, the result includes all fields.sorts(Array<{field: Field | string, direction: 'asc' | 'desc'}>): Sorting optionsrecordIds(Array<string | number>): Specific record IDs to retrievepageSize(number): Maximum number of records to return per page (default: 50)page(number): Page number for pagination (default: 1)where(string): A where filter string, for example(Status,eq,Open)~and(Amount,gt,5). See Filters.filter(NcFilter): A structured filter. If you also givewhere, a record must match both. See Filters.
Returns: Promise<RecordQueryResult>: A promise that resolves to a RecordQueryResult object with pagination support
Example:
// Query records with options
const queryResult = await tasksTable.selectRecordsAsync({
fields: ['Task Name', 'Status', 'Due Date'],
sorts: [
{field: 'Due Date', direction: 'asc'},
{field: 'Status', direction: 'desc'}
],
pageSize: 100
});
output.text(`Retrieved ${queryResult.records.length} records.`);
// Process the records
for (const record of queryResult.records) {
const taskName = record.getCellValue('Task Name');
const status = record.getCellValue('Status');
output.text(`- ${taskName}: ${status}`);
}
// Check if there are more records
if (queryResult.hasMoreRecords) {
// Load the next page of records
const nextPage = await queryResult.loadMoreRecords();
output.text(`Loaded ${nextPage.records.length} more records.`);
}selectRecordAsync
Gets one record from the table by its ID.
Parameters:
recordId(string): The ID of the record to retrieveoptions(optional): Object with the following properties:fields(Array<Field | string>): Specific fields to include in the result
Returns: Promise<Record | null>: A promise that resolves to the Record object if a match is found
Example:
// Get a specific record by ID
const recordId = '123';
const record = await contactsTable.selectRecordAsync(recordId, {
fields: ['Name', 'Email', 'Phone']
});
if (record) {
output.text(`Contact: ${record.getCellValue('Name')}`);
output.text(`Email: ${record.getCellValue('Email')}`);
output.text(`Phone: ${record.getCellValue('Phone')}`);
} else {
output.text(`Record with ID ${recordId} not found.`);
}countRecordsAsync
Counts the records that match a filter. Use it instead of selecting records only to count them.
Parameters:
options(optional): Object with the following properties:
Returns: Promise<number>: The number of matching records. Without options, the number of records in the table.
Example:
const ordersTable = base.getTable('Orders');
const open = await ordersTable.countRecordsAsync({
filter: { field: 'Status', operator: 'eq', value: 'Open' }
});
output.text(`${open} open orders`);createRecordAsync
Creates a new record in the table with the specified field values.
Parameters:
data(Object): An object that maps field names or IDs to their values.
Note: NocoDB writes every field that you name, so 0 and false are stored as given. A null stores an empty value, and on Number, Decimal, Currency, Percent, Rating, Duration and Year fields an empty string does the same.
Returns: Promise<string>: A promise that resolves to the ID of the created record
Example:
// Create a new record
const newRecordId = await contactsTable.createRecordAsync({
'Name': 'John Doe',
'Email': 'john.doe@example.com',
'Phone': '(555) 123-4567',
'Status': 'Active'
});
output.text(`New record created with ID: ${newRecordId}`);
// Create a record with field IDs
const newRecordId2 = await contactsTable.createRecordAsync({
'c123456': 'Jane Smith', // Name field
'c456789': 'jane@example.com' // Email field
});createRecordsAsync
Creates multiple records in the table.
Parameters:
data(Array<{fields: Object}>): An array of objects. Each object has afieldsproperty that maps field names or IDs to their values.
Note: createRecordAsync takes a flat object. Here, each entry must put its values in fields. NocoDB ignores values outside fields and creates blank records.
Note: Field values follow the same rules as createRecordAsync.
Batches: You may pass any number of records. NocoDB sends them 10 per request. The requests are not atomic together: if one fails, the records of the earlier requests stay created, and error.details.completedIds lists their IDs. See Errors.
Returns: Promise<Array<string>>: A promise that resolves to an array of IDs of the created records
Example:
// Create multiple records at once
const newRecordIds = await contactsTable.createRecordsAsync([
{ fields: {
'Name': 'John Doe',
'Email': 'john.doe@example.com',
'Status': 'Active'
}},
{ fields: {
'Name': 'Jane Smith',
'Email': 'jane.smith@example.com',
'Status': 'Pending'
}},
{ fields: {
'Name': 'Bob Johnson',
'Email': 'bob.johnson@example.com',
'Status': 'Active'
}}
]);
output.text(`Created ${newRecordIds.length} new records.`);updateRecordAsync
Updates a record with the specified field values.
Parameters:
recordId(string | NocoDBRecord): The ID of the record to update or a NocoDBRecord objectdata(Object): An object that maps field names or IDs to their new values.
Note: NocoDB writes every field that you name, so 0 and false are stored as given. To clear a field, pass null. On Number, Decimal, Currency, Percent, Rating, Duration and Year fields, an empty string also clears the field.
Returns: Promise<NocoDBRecord | null>: The record as saved. null if you cannot read the record after the update, for example because of row-level security.
Example:
// Update a record by ID, and use the saved record
const saved = await contactsTable.updateRecordAsync('123', {
'Status': 'Inactive',
'Last Contact Date': new Date().toISOString()
});
output.text(`Status is now ${saved?.getCellValue('Status')}`);
// Update a record using a Record object
const record = await contactsTable.selectRecordAsync('123');
if (record) {
await contactsTable.updateRecordAsync(record, {
'Notes': 'Customer requested follow-up next quarter.'
});
output.text('Record updated successfully.');
}updateRecordsAsync
Updates multiple records with the specified field values.
Parameters:
records(Array<{id: string | NocoDBRecord, fields: Object}>): An array of objects. Each object has a record ID (or a NocoDBRecord object) and the field values to update.
Batches: You may pass any number of records. NocoDB sends them 10 per request. The requests are not atomic together: if one fails, error.details.completedIds lists the records already updated.
Note: Field values follow the same rules as updateRecordAsync.
Returns: Promise<Array<NocoDBRecord>>: The records as saved
Example:
// Update multiple records at once
await contactsTable.updateRecordsAsync([
{
id: '123',
fields: {
'Status': 'Active',
'Last Contact Date': new Date().toISOString()
}
},
{
id: 'rec67890',
fields: {
'Status': 'Inactive',
'Notes': 'Customer no longer interested.'
}
}
]);
output.text('Records updated successfully.');deleteRecordAsync
Deletes a record from the table.
Parameters:
recordIdOrRecord(string | NocoDBRecord): The ID of the record to delete or a NocoDBRecord object
Returns: Promise<boolean>: A promise that resolves to true when the deletion is complete
Example:
// Delete a record by ID
await tasksTable.deleteRecordAsync('123');
output.text('Record deleted successfully.');
// Delete a record using a Record object
const record = await tasksTable.selectRecordAsync('678');
if (record) {
await tasksTable.deleteRecordAsync(record);
output.text(`Record "${record.name}" deleted successfully.`);
}deleteRecordsAsync
Deletes multiple records from the table.
Parameters:
recordIds(Array<string>): Array of record IDs to delete
Batches: You may pass any number of records. NocoDB sends them 10 per request. The requests are not atomic together: if one fails, error.details.completedIds lists the records already deleted.
Returns: Promise<boolean>: A promise that resolves to true when all deletions are complete
Example:
// Delete multiple records by ID
await tasksTable.deleteRecordsAsync(['123', '678', '246']);
output.text('Records deleted successfully.');
// Delete records using a query result
const completedTasks = await tasksTable.selectRecordsAsync({
fields: ['Status'],
where: '(Status, eq, Completed)',
});
const recordsToDelete = completedTasks.records.map(record => record.id);
await tasksTable.deleteRecordsAsync(recordsToDelete);
output.text(`Deleted ${recordsToDelete.length} completed tasks.`);upsertRecordsAsync
Creates or updates records. NocoDB looks for an existing record whose matchOn fields have the same values. If it finds one, it updates that record. Otherwise it creates a new record.
Parameters:
records(Array<{fields: Object}>): The records to create or updateoptions(Object):matchOn(Array<Field | string>): One to three fields that identify a record, for example an email address
Batches: You may pass any number of records. NocoDB sends them 10 per request. The requests are not atomic together: if one fails, error.details.completedIds lists the records already written.
Returns: Promise<Array<{id: string, status: 'inserted' | 'updated', record: NocoDBRecord}>>: One entry for each record, in the order you gave them
Example:
const contactsTable = base.getTable('Contacts');
const results = await contactsTable.upsertRecordsAsync(
[
{ fields: { 'Email': 'ana@example.com', 'Name': 'Ana' } },
{ fields: { 'Email': 'bo@example.com', 'Name': 'Bo' } }
],
{ matchOn: ['Email'] }
);
for (const { id, status } of results) {
output.text(`${id}: ${status}`);
}linkRecordsAsync
Links records to a record through a Links field. Links that the record already has stay.
Parameters:
record(string | number | NocoDBRecord): The record to link fromfield(Field | string): A Links field of this tablerecords(string | number | NocoDBRecord | Array<string | number | NocoDBRecord>): The records to link
Returns: Promise<void>
Note: To replace all links of a record, update the Links field with updateRecordAsync instead.
Example:
const projectsTable = base.getTable('Projects');
// Link tasks 7 and 8 to project 3. Other tasks of project 3 stay linked.
await projectsTable.linkRecordsAsync('3', 'Tasks', ['7', '8']);unlinkRecordsAsync
Removes the given links from a record. Other links stay.
Parameters:
record(string | number | NocoDBRecord): The record to unlink fromfield(Field | string): A Links field of this tablerecords(string | number | NocoDBRecord | Array<string | number | NocoDBRecord>): The records to unlink
Returns: Promise<void>
Example:
await base.getTable('Projects').unlinkRecordsAsync('3', 'Tasks', '8');uploadAttachmentAsync
Uploads a file into an Attachment field of a record. NocoDB adds the file after the files that the cell already has.
Parameters:
record(string | number | NocoDBRecord): The record to upload intofield(Field | string): An Attachment field of this tablefile: The file content. One of:string: text, sent as UTF-8Uint8Array(this includes a Node.jsBuffer) orArrayBuffer: bytesBloborFile, for example the file from input.fileAsync
options(optional):filename(string): The file name. Default: the name of theFile, elsefile.contentType(string): The MIME type. Default: the type of theBlob, else a type from the file name extension (.csvgivestext/csv), elseapplication/octet-stream.
Returns: Promise<NocoDBRecord>: The record as saved
Limits: The maximum file size is set for each deployment (20 MB by default). The number of files a cell can hold depends on your plan. If the upload fails, the method throws a NocoDBError with the HTTP status. NocoDB does not retry uploads.
Note: To replace or remove files, update the Attachment field with updateRecordAsync.
Example:
const reportsTable = base.getTable('Reports');
// Make a CSV file in the script, and attach it to record 12
const csv = 'Name,Total\nAna,120\nBo,95';
const saved = await reportsTable.uploadAttachmentAsync('12', 'Exports', csv, {
filename: 'march.csv'
});
output.text(`Files: ${saved.getCellValue('Exports').length}`);createFieldAsync
Creates a new field in the table with the specified configuration.
Parameters:
field(Object): Field configuration object with:name(string): Name for the new fieldtype(UITypes): Type of field to createdescription(string, optional): Description for the fieldoptions(Object, optional): Type-specific options for the field
Returns: Promise<Field>: A promise that resolves to the created Field object
Example:
// Create a new field
const ratingField = await projectsTable.createFieldAsync({
name: 'Priority',
type: UITypes.Rating,
description: 'Project priority from 1-5',
options: {
icon: 'star',
max_value: 5,
color: '#FFCC00'
}
});
output.text(`Created new field: ${ratingField.name}`);
// Create a select field
const statusField = await tasksTable.createFieldAsync({
name: 'Status',
type: UITypes.SingleSelect,
options: {
choices: [
{ title: 'Not Started', color: '#808080' },
{ title: 'In Progress', color: '#3366FF' },
{ title: 'Review', color: '#FF9900' },
{ title: 'Completed', color: '#33CC33' }
]
}
});Filters
selectRecordsAsync and countRecordsAsync, on tables and on views, accept two kinds of filter. If you give both, a record must match both.
filter
A structured filter has the same shape as filters in the NocoDB API v3. NocoDB puts quotes around field names and values for you, so commas, parentheses and quotes in them are safe.
// One condition
{ field: 'Status', operator: 'eq', value: 'Open' }
// A group. Groups can contain groups.
{
group_operator: 'AND',
filters: [
{ field: 'Status', operator: 'anyof', value: ['Open', 'In progress'] },
{ group_operator: 'OR', filters: [
{ field: 'Amount', operator: 'btw', value: [100, 500] },
{ field: 'Priority', operator: 'checked' }
] }
]
}A condition has these properties:
field: the field name (not case sensitive), the field ID, or aFieldobjectoperator: the comparisonsub_operator: for date fields onlyvalue: depends on the operator:blank,notblank,checked,notchecked,null,notnull,emptyandnotemptytake no value.anyof,nanyof,allof,nallofandintake a list.btwandnbtwtake[from, to], both included. They do not work on date fields: usegteandltein two conditions.- All other operators take one value.
A comparison on a date field needs a sub_operator:
// A calendar date
{ field: 'Due', operator: 'lt', sub_operator: 'exactDate', value: '2026-06-01' }
// A relative date
{ field: 'Due', operator: 'eq', sub_operator: 'today' }
{ field: 'Due', operator: 'gt', sub_operator: 'daysAgo', value: 7 }
// A period
{ field: 'Due', operator: 'isWithin', sub_operator: 'thisCalendarMonth' }
{ field: 'Due', operator: 'isWithin', sub_operator: 'dateRange', value: ['2026-06-01', '2026-06-30'] }Values are compared as written: the text "null" matches the text, not an empty cell. Use blank or null to find empty cells.
If a filter is not valid, or names a Lookup, Rollup or Formula field that has an error, the method throws a NocoDBError that tells you what to change. NocoDB does not send the request.
where
A where string uses the syntax of the where parameter of the NocoDB API v3: (field,operator,value) conditions joined with ~and, ~or and ~not.
await tasksTable.selectRecordsAsync({
where: '(Status,eq,Open)~and((Amount,gt,5)~or(Done,checked))'
});Put quotes around a field name or a value that contains a comma, a parenthesis or a quote: ("Name, full",eq,"O'Brien"). On a date field, give a sub-operator after the operator: (Due,gt,exactDate,2026-06-01).
In the script editor, NocoDB checks where strings against the table as you type. It marks an unknown field or an operator that does not suit the field, for example ✖ "eq3" is not an operator for Title. Use one of: eq, neq, like, ….
Examples
Querying and Filtering Records
// Get the "Tasks" table
const tasksTable = base.getTable('Tasks');
// Get all tasks
const allTasks = await tasksTable.selectRecordsAsync();
output.text(`Total tasks: ${allTasks.records.length}`);
// Use a view to get filtered records
const inProgressView = tasksTable.getView('In Progress Tasks');
if (inProgressView) {
const inProgressTasks = await inProgressView.selectRecordsAsync();
output.text(`In-progress tasks: ${inProgressTasks.records.length}`);
}
// Get specific fields and sort by due date
const upcomingTasks = await tasksTable.selectRecordsAsync({
fields: ['Task Name', 'Due Date', 'Status', 'Assigned To'],
sorts: [
{ field: 'Due Date', direction: 'asc' }
],
pageSize: 10
});
// Display the upcoming tasks
output.markdown('# Upcoming Tasks');
for (const task of upcomingTasks.records) {
const name = task.getCellValue('Task Name');
const dueDate = task.getCellValue('Due Date');
const status = task.getCellValue('Status');
const assignee = task.getCellValue('Assigned To');
const assigneeName = assignee ? assignee.name : 'Unassigned';
output.text(`- ${name} (${status}) due on ${dueDate} - Assigned to: ${assigneeName}`);
}Creating and Updating Records
// Get the "Projects" table
const projectsTable = base.getTable('Projects');
// Create a new project
const newProjectId = await projectsTable.createRecordAsync({
'Project Name': 'Website Redesign',
'Start Date': new Date().toISOString(),
'Status': 'Planning',
'Budget': 15000,
'Description': 'Complete overhaul of company website.'
});
output.text(`Created new project with ID: ${newProjectId}`);
// Retrieve the created project
const newProject = await projectsTable.selectRecordAsync(newProjectId);
if (newProject) {
output.text(`New project: ${newProject.getCellValue('Project Name')}`);
// Update the project after creation
await projectsTable.updateRecordAsync(newProjectId, {
'Project Lead': session.currentUser.id,
'Team Size': 5
});
output.text('Project updated with lead and team size.');
}
// Create multiple tasks for the project
const tasksTable = base.getTable('Tasks');
const tasks = [
{ fields: {
'Task Name': 'Requirements Gathering',
'Project': newProjectId,
'Status': 'Not Started',
'Due Date': new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
}},
{ fields: {
'Task Name': 'Wireframes',
'Project': newProjectId,
'Status': 'Not Started',
'Due Date': new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toISOString()
}},
{ fields: {
'Task Name': 'Design Mockups',
'Project': newProjectId,
'Status': 'Not Started',
'Due Date': new Date(Date.now() + 21 * 24 * 60 * 60 * 1000).toISOString()
}}
];
const taskIds = await tasksTable.createRecordsAsync(tasks);
output.text(`Created ${taskIds.length} tasks for the project.`);Bulk Processing with Pagination
// Get the "Contacts" table
const contactsTable = base.getTable('Contacts');
// Function to process all records with pagination
async function processAllRecords() {
let queryResult = await contactsTable.selectRecordsAsync({
fields: ['Name', 'Email', 'Last Contact Date'],
pageSize: 100 // Process in batches of 100
});
let processedCount = 0;
let updatedCount = 0;
while (queryResult.hasMoreRecords) {
await queryResult.loadMoreRecords();
}
// Process first batch
let recordsToUpdate = [];
for (const record of queryResult.records) {
processedCount++;
const lastContactDate = record.getCellValue('Last Contact Date');
// If no contact in the last 90 days, mark for update
if (!lastContactDate || new Date(lastContactDate) < new Date(Date.now() - 90 * 24 * 60 * 60 * 1000)) {
recordsToUpdate.push({
id: record.id,
fields: {
'Status': 'Needs Follow-up',
'Notes': 'No contact in the last 90 days.'
}
});
}
}
// updateRecordsAsync accepts at most 10 records per call, so send in chunks
for (let i = 0; i < recordsToUpdate.length; i += 10) {
const chunk = recordsToUpdate.slice(i, i + 10);
await contactsTable.updateRecordsAsync(chunk);
updatedCount += chunk.length;
}
output.text(`Processing complete! Processed ${processedCount} total records, updated ${updatedCount}.`);
}
// Run the process
await processAllRecords();Best Practices
-
Batch operations: To create or update many records, use the bulk methods (
createRecordsAsync,updateRecordsAsync), not individual calls. This gives better performance. Each call accepts at most 10 records, so split larger sets into chunks of 10. -
Paginate large queries: For large tables, use pagination with the
pageSizeoption and theloadMoreRecords()method. This prevents memory issues. -
Error handling: Always put async operations in try/catch blocks to handle errors gracefully.
-
Optimize field selection: Use the
fieldsoption in queries to request only the fields that you need. This improves performance.
Related
Last updated on