Base

The base object is the primary entry point to your database in NocoDB Scripts. It provides access to tables, views, records, and collaborators within your base.

Overview

In every script, you have access to a global base object that represents the current NocoDB base where your script is running. This object lets you:

Access tables within your base
List collaborators
Create new tables (in supported environments)

Properties

Property	Type	Description
`id`	`string`	The unique identifier of the base
`name`	`string`	The name of the base
`tables`	`Table[]`	Array of all tables in the base with their fields and views
`activeCollaborators`	`Collaborator[]`	Array of active collaborators having access to this base (with read-only properties)

Methods

getTable

Retrieves a table from the base using its ID or name.

Parameters:

idOrName (string): The ID or name of the table to retrieve

Both the table name and table ID are case-sensitive.

Returns:

Table object if a match is found
null if no table matches the provided input

Example:

// Get a table by name
const projects = base.getTable('Projects');

// Get a table by ID
const tasks = base.getTable('tbl123456789');

// Check if a table exists
const tableName = 'Customers';
const table = base.getTable(tableName);
if (table) {
  output.text(`Table ${tableName} found!`);
} else {
  output.text(`Table ${tableName} not found.`);
}

getCollaborator

Retrieves a collaborator from the base by their ID, email, or name.

Parameters:

idOrEmailOrName (string): The collaborator’s ID, email address, or display name.

Email addresses are case-insensitive. ID and name are case-sensitive.

Returns:

Collaborator object if a match is found.
null if no collaborator matches the provided input.

Example:

// Get a collaborator by email
const user = base.getCollaborator('user@example.com');

// Check if a user has access to the base
if (user) {
  output.text(`User ${user.name} (${user.email}) has access to this base.`);
} else {
  output.text('User not found in collaborators.');
}

createTableAsync

Creates a new table in the base with the specified name and fields.

Parameters:

name (string): The name for the new table
fields (Array): Array of field configurations where each field should have:
- name (string): The field name
- type (UITypes): The field type
- options (Object, optional): Field-specific options

Returns: Promise<Table> - A promise that resolves to the newly created table

Note that, fields can be an empty array. A table with only system fields will be created. The first field in the fields array will be marked as display value field. Fields must have case sensitive unique names. Fields of all type except 'Button' are allowed.

Example:

try {
  const newTable = await base.createTableAsync('Orders', [
    {
      name: 'Order ID',
      type: UITypes.SingleLineText
    },
    {
      name: 'Customer',
      type: UITypes.SingleLineText
    },
    {
      name: 'Order Date',
      type: UITypes.Date,
      options: {
        date_format: 'YYYY-MM-DD'
      }
    },
    {
      name: 'Status',
      type: UITypes.SingleSelect,
      options: {
        choices: [
          { title: 'Pending', color: '#FFC107' },
          { title: 'Processing', color: '#007BFF' },
          { title: 'Shipped', color: '#28A745' },
          { title: 'Delivered', color: '#6F42C1' },
          { title: 'Cancelled', color: '#DC3545' }
        ]
      }
    }
  ]);
  
  output.text(`Table ${newTable.name} created successfully!`);
} catch (error) {
  output.text(`Error creating table: ${error.message}`);
}

Examples

Getting All Tables

// Print all tables in the base
output.markdown('# Tables in this base:');

for (const table of base.tables) {
  output.text(`- ${table.name} (${table.id}): ${table.fields.length} fields, ${table.views.length} views`);
}

Checking for a Specific Table

// Check if a specific table exists and create it if it doesn't
const inventoryTableName = 'Inventory';
let inventoryTable = base.getTable(inventoryTableName);

if (!inventoryTable) {
  output.text(`${inventoryTableName} table not found. Creating it now...`);
  
  try {
    inventoryTable = await base.createTableAsync(inventoryTableName, [
      { name: 'Item ID', type: UITypes.SingleLineText },
      { name: 'Item Name', type: UITypes.SingleLineText },
      { name: 'Quantity', type: UITypes.Number },
      { 
        name: 'Category', 
        type: UITypes.SingleSelect, 
        options: {
          choices: [
            { title: 'Electronics', color: '#FFC107' },
            { title: 'Clothing', color: '#007BFF' },
            { title: 'Home & Garden', color: '#28A745' },
            { title: 'Books', color: '#6F42C1' },
            { title: 'Sports', color: '#DC3545' }
          ]
        }
      }
    ]);
    output.text(`${inventoryTableName} table created successfully!`);
  } catch (error) {
    output.text(`Error creating table: ${error.message}`);
  }
} else {
  output.text(`${inventoryTableName} table already exists.`);
}

Working with Collaborators

// List all collaborators
output.markdown('# Active Collaborators:');

for (const collaborator of base.activeCollaborators) {
  const displayName = collaborator.name || 'Unnamed User';
  output.text(`- ${displayName} (${collaborator.email}) - ID: ${collaborator.id}`);
}

// Find the current user
const currentUser = session.currentUser;
const currentUserName = currentUser.name || currentUser.email;
output.markdown(`## Current User: ${currentUserName} (${currentUser.email})`);

// Check if a specific user has access using getCollaborator method
const userEmail = 'team@example.com';
const teamMember = base.getCollaborator(userEmail);

if (teamMember) {
  const memberName = teamMember.name || 'Unnamed User';
  output.text(`${memberName} has access to this base.`);
} else {
  output.text(`No collaborator found with email ${userEmail}.`);
}

// You can also search by ID or name
const memberById = base.getCollaborator('usr_123456');
const memberByName = base.getCollaborator('John Doe');

// getCollaborator returns null if no match is found
if (memberById) {
  output.text(`Found collaborator by ID: ${memberById.name || memberById.email}`);
}

Best Practices

Await async operations - Always use await when calling async methods to ensure proper execution flow.

Base

Cursor

Table