Product Docs
Self Hosting
Changelog (EE)

Scripts

NocoDB Scripts Documentation

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. Navigate to the Scripts tab in your NocoDB base
  2. Click + New Script
  3. Write your JavaScript code in the editor
  4. 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

API Reference

Learn about the available objects and methods:

Core Objects

  • Base Object - Access tables, collaborators, and create new structures
  • Table Object - Query, create, update, and delete records with advanced options
  • View Object - Work with filtered and sorted table perspectives
  • Record Object - Individual data entries with rich cell value handling
  • Field Object - Table structure with comprehensive field type support
  • RecordQueryResult - Paginated query results with load-more capabilities

User and Session Management

  • Collaborator - User information and permissions
  • Session - Current user context and session data

Input and Output

  • Input Methods - Interactive prompts, file uploads, and user selections
  • Output Methods - Text, markdown, tables, progress indicators, and debugging

External Integration