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

PropertyTypeDescription
idstringThe unique identifier of the table
namestringThe name of the table
descriptionstring | nullThe description of the table (if any)
fieldsField[]Array of user-defined fields in the table (no system fields)
viewsView[]Array of all views defined for the table
baseBaseReference 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:

  • Field object if a match is found
  • null if 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:

  • View object if a match is found
  • null if 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 options
    • recordIds (Array<string | number>): Specific record IDs to retrieve
    • pageSize (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 give where, 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 retrieve
  • options (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:
    • where (string): A where filter string. See Filters.
    • filter (NcFilter): A structured filter. See Filters.

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 a fields property 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 object
  • data (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 update
  • options (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 from
  • field (Field | string): A Links field of this table
  • records (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 from
  • field (Field | string): A Links field of this table
  • records (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 into
  • field (Field | string): An Attachment field of this table
  • file: The file content. One of:
    • string: text, sent as UTF-8
    • Uint8Array (this includes a Node.js Buffer) or ArrayBuffer: bytes
    • Blob or File, for example the file from input.fileAsync
  • options (optional):
    • filename (string): The file name. Default: the name of the File, else file.
    • contentType (string): The MIME type. Default: the type of the Blob, else a type from the file name extension (.csv gives text/csv), else application/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 field
    • type (UITypes): Type of field to create
    • description (string, optional): Description for the field
    • options (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 a Field object
  • operator: the comparison
  • sub_operator: for date fields only
  • value: depends on the operator:
    • blank, notblank, checked, notchecked, null, notnull, empty and notempty take no value.
    • anyof, nanyof, allof, nallof and in take a list.
    • btw and nbtw take [from, to], both included. They do not work on date fields: use gte and lte in 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

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

  2. Paginate large queries: For large tables, use pagination with the pageSize option and the loadMoreRecords() method. This prevents memory issues.

  3. Error handling: Always put async operations in try/catch blocks to handle errors gracefully.

  4. Optimize field selection: Use the fields option in queries to request only the fields that you need. This improves performance.

Last updated on

Latest product updates?See Changelog
Stay in the loop? Follow us onLinkedInLinkedInYouTubeYouTubeXX