Base

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

Overview

Every script has a global base object. This object is the current NocoDB base, where the script runs. Use it to:

Get the tables in 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 that have access to this base (with read-only properties)

Methods

getTable

Gets a table from the base by its ID or name.

Parameters:

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

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('m123456789');

// 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

Gets a collaborator from the base by 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

Rules for fields:

fields can be an empty array. The new table then has only system fields.
The first field in the fields array becomes the display value field.
Field names must be unique. Names are case-sensitive.
All field types are allowed, except 'Button'.

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('u123456789'); // Replace with actual ID
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 you call async methods. This makes sure that the steps run in the correct order.