Scripts

Overview

NocoDB Scripts is a powerful automation engine that allows you to write JavaScript code to interact with your NocoDB bases. Scripts enable you to automate workflows, perform complex operations, transform data, and integrate with external services - all without leaving the NocoDB interface.

Key Features

• JavaScript Environment: Write and run JavaScript code directly in NocoDB
• Database Access: Query tables and views, create, update, and delete records
• User Interaction: Collect input from users with interactive prompts
• External Integration: Connect to third-party services via HTTP requests
• Visual Output: Display results in formatted tables, markdown, and more
• TypeScript Support: Enjoy code completion and type checking in the script editor

Getting Started

To create your first script:

1. Click on + Create New on left sidebar
2. Select Script from the dropdown menu. Optionally, you can also select a template to start with a predefined structure.
3. In the pop-up modal, give your script a name and description to help identify its purpose.
4. Write your JavaScript code in the script editor. You can use the built-in API to interact with your NocoDB base, tables, and records. Changes are saved automatically.
5. Run your script with the ▶️ button

Script Structure

A typical NocoDB script follows this pattern:

// 1. Get input from user for interactive scripts
const table = await input.tableAsync('Select a table to analyze:');
const field = await input.fieldAsync('Which field would you like to analyze?', table);

// 2. Perform operations with enhanced query capabilities
const query = await table.selectRecordsAsync({
  fields: [field.name],
  sorts: [{ field: field.name, direction: 'asc' }],
  pageSize: 100
});

// 3. Process records with rich cell value handling
let count = 0;
let totalRecords = query.records.length;

// Handle pagination if there are more records
while (query.hasMoreRecords) {
  await query.loadMoreRecords();
  totalRecords = query.records.length;
}

// Count non-empty values
for (const record of query.records) {
  const value = record.getCellValue(field.name);
  if (value !== null && value !== undefined && value !== '') {
    count++;
  }
}

// 4. Display formatted output with progress
output.markdown(`# Field Analysis Results`);
output.text(`Field: ${field.name} (${field.type})`);
output.text(`Total records analyzed: ${totalRecords}`);
output.text(`Records with values: ${count}`);
output.text(`Empty records: ${totalRecords - count}`);
output.text(`Fill rate: ${((count / totalRecords) * 100).toFixed(1)}%`);

// 5. Show sample values in a table
if (count > 0) {
  const sampleData = query.records
    .filter(record => record.getCellValue(field.name) !== null)
    .slice(0, 5)
    .map(record => ({
      'Record ID': record.id,
      'Value': record.getCellValueAsString(field.name)
    }));
  
  output.markdown('## Sample Values');
  output.table(sampleData);
}

Core Concepts

• Base Object: The entry point to your database (base)
• Tables and Views: Access your base structure
• Records: Work with individual data entries
• Fields: Define the structure of your tables
• RecordQueryResult: Handle paginated query results with advanced loading capabilities
• Collaborators: Work with user data
• Session: Access current user context and session information
• Input: Collect user input with interactive prompts and file uploads
• Output: Display formatted results with text, markdown, tables, and progress indicators
• API Integration: Connect to external services and NocoDB's REST APIs