Field

The Field object represents a column in a NocoDB table and provides access to its configuration and metadata. Fields define the structure of tables and determine how data is stored, validated, and displayed.

Overview

NocoDB supports a wide variety of field types to accommodate different kinds of data, from simple text and numbers to more complex types like attachments, links to other tables, formulas, and more. The Field object enables you to:

Access field properties such as name, type, and description
Check if a field is computed or a system field
Update field configuration and options
Work with field-specific options and behaviors

Common Properties

All Field objects share these common properties:

Property	Type	Description
`id`	`string`	The unique identifier of the field
`name`	`string`	The display name of the field
`type`	`UITypes`	The type of the field (e.g., SingleLineText, Number, Date)
`description`	`string \| null`	The description of the field (if any)
`isComputed`	`boolean`	Whether the field value is computed rather than directly editable
`options`	`object \| null`	Type-specific options for the field

Common Methods

All Field objects provide these methods:

updateOptionsAsync

Updates the field's options configuration.

Parameters:

options (object): New options configuration. Structure depends on field type.

Returns: Promise<void> - A promise that resolves when the update is complete

Example:

// Get a SingleSelect field
const statusField = projectsTable.getField('Status');

// Update its choices
await statusField.updateOptionsAsync({
  choices: [
    { title: 'Not Started', color: '#808080' },
    { title: 'In Progress', color: '#3366FF' },
    { title: 'Under Review', color: '#FF9900' },
    { title: 'Completed', color: '#33CC33' },
    { title: 'Cancelled', color: '#FF3333' }
  ]
});

output.text('Field options updated successfully.');

updateDescriptionAsync

Updates the description of the field.

Parameters:

description (string | null): New description text, or null to remove description

Returns: Promise<Field> - A promise that resolves to the updated Field

Example:

// Get a field
const budgetField = projectsTable.getField('Budget');

// Update its description
await budgetField.updateDescriptionAsync('Budget in USD. Must be approved for amounts over $10,000.');

output.text('Field description updated successfully.');

updateNameAsync

Updates the display name of the field.

Parameters:

name (string): New field name

Returns: Promise<Field> - A promise that resolves to the updated Field object

Example:

// Get a field
const oldField = projectsTable.getField('Project Lead');

// Update its name
const updatedField = await oldField.updateNameAsync('Project Manager');

output.text(`Field name updated from "${oldField.name}" to "${updatedField.name}"`);

UITypes Constants

NocoDB Scripts provides a comprehensive set of field type constants through the UITypes object:

const UITypes = {
  LinkToAnotherRecord: 'LinkToAnotherRecord',
  Lookup: 'Lookup',
  SingleLineText: 'SingleLineText',
  LongText: 'LongText',
  Attachment: 'Attachment',
  Checkbox: 'Checkbox',
  MultiSelect: 'MultiSelect',
  SingleSelect: 'SingleSelect',
  Date: 'Date',
  Year: 'Year',
  Time: 'Time',
  PhoneNumber: 'PhoneNumber',
  GeoData: 'GeoData',
  Email: 'Email',
  URL: 'URL',
  Number: 'Number',
  Decimal: 'Decimal',
  Currency: 'Currency',
  Percent: 'Percent',
  Duration: 'Duration',
  Rating: 'Rating',
  Formula: 'Formula',
  Rollup: 'Rollup',
  DateTime: 'DateTime',
  CreatedTime: 'CreatedTime',
  LastModifiedTime: 'LastModifiedTime',
  Geometry: 'Geometry',
  JSON: 'JSON',
  Barcode: 'Barcode',
  QrCode: 'QrCode',
  Button: 'Button',
  Links: 'Links',
  User: 'User',
  CreatedBy: 'CreatedBy',
  LastModifiedBy: 'LastModifiedBy'
};

Field Types

NocoDB supports a wide range of field types, each with its own specific properties and behaviors. Here's an overview of the most common field types:

Text Fields

Single Line Text

Basic text field for short content.

// Create a Single Line Text field
await projectsTable.createFieldAsync({
  name: 'Project Code',
  type: UITypes.SingleLineText,
  description: 'Unique project identifier code'
});

Long Text

Multi-line text field that can optionally support rich text formatting.

// Create a Long Text field with rich text enabled
await projectsTable.createFieldAsync({
  name: 'Description',
  type: UITypes.LongText,
  description: 'Detailed project description',
  options: {
    rich_text: true,
    generate_text_using_ai: false
  }
});

Number Fields

Number

Whole number field.

// Create a Number field
await projectsTable.createFieldAsync({
  name: 'Sequence',
  type: UITypes.Number,
  options: {
    locale_string: true
  }
});

Decimal

Number with decimal places.

// Create a Decimal field
await projectsTable.createFieldAsync({
  name: 'Score',
  type: UITypes.Decimal,
  options: {
    locale_string: true,
    precision: 2
  }
});

Currency

Monetary values with currency symbol.

// Create a Currency field
await projectsTable.createFieldAsync({
  name: 'Budget',
  type: UITypes.Currency,
  options: {
    locale: 'en-US',
    code: 'USD'
  }
});

Percent

Percentage values.

// Create a Percent field
await projectsTable.createFieldAsync({
  name: 'Completion',
  type: UITypes.Percent,
  options: {
    show_as_progress: true
  }
});

Rating

Visual rating representation.

// Create a Rating field
await projectsTable.createFieldAsync({
  name: 'Priority',
  type: UITypes.Rating,
  options: {
    icon: 'star',
    max_value: 5,
    color: '#FFCC00'
  }
});

Date and Time Fields

Date

Date values without time.

// Create a Date field
await projectsTable.createFieldAsync({
  name: 'Due Date',
  type: UITypes.Date,
  options: {
    date_format: 'YYYY-MM-DD'
  }
});

DateTime

Date and time values.

// Create a DateTime field
await projectsTable.createFieldAsync({
  name: 'Last Updated',
  type: UITypes.DateTime,
  options: {
    date_format: 'YYYY-MM-DD',
    time_format: 'HH:mm',
    '12hr_format': false,
    timezone: 'UTC',
    display_timezone: true,
    use_same_timezone_for_all: true
  }
});

Time

Time values without date.

// Create a Time field
await projectsTable.createFieldAsync({
  name: 'Start Time',
  type: UITypes.Time,
  options: {
    '12hr_format': false
  }
});

Duration

Time duration values.

// Create a Duration field
await projectsTable.createFieldAsync({
  name: 'Estimated Hours',
  type: UITypes.Duration,
  options: {
    duration_format: 'h:mm:ss'
  }
});

Boolean Fields

Checkbox

True/false values represented as checkboxes.

// Create a Checkbox field
await projectsTable.createFieldAsync({
  name: 'Approved',
  type: UITypes.Checkbox,
  options: {
    icon: 'square',
    color: '#33CC33'
  }
});

Selection Fields

Single Select

Selection from a predefined list of options (only one can be selected).

// Create a Single Select field
await projectsTable.createFieldAsync({
  name: 'Status',
  type: UITypes.SingleSelect,
  options: {
    choices: [
      { title: 'Not Started', color: '#808080' },
      { title: 'In Progress', color: '#3366FF' },
      { title: 'Under Review', color: '#FF9900' },
      { title: 'Completed', color: '#33CC33' },
      { title: 'Cancelled', color: '#FF3333' }
    ]
  }
});

Multi Select

Selection from a predefined list of options (multiple can be selected).

// Create a Multi Select field
await projectsTable.createFieldAsync({
  name: 'Tags',
  type: UITypes.MultiSelect,
  options: {
    choices: [
      { title: 'Urgent', color: '#FF0000' },
      { title: 'Bug', color: '#FFA500' },
      { title: 'Feature', color: '#0000FF' },
      { title: 'Documentation', color: '#008000' },
      { title: 'Enhancement', color: '#800080' }
    ]
  }
});

Relationship Fields

Link to Another Record

Creates relationships between tables.

// Create a Link to Another Record field
await tasksTable.createFieldAsync({
  name: 'Project',
  type: UITypes.LinkToAnotherRecord,
  options: {
    relation_type: 'mm',
    related_table_id: projectsTable.id,
    limit_record_selection_view_id: null
  }
});

Lookup

Looks up values from linked records.

// First, ensure we have a link field to the Projects table
const projectField = tasksTable.getField('Project');

// Create a Lookup field to get the Project's manager
await tasksTable.createFieldAsync({
  name: 'Project Manager',
  type: UITypes.Lookup,
  options: {
    related_field_id: projectField.id, // The link field
    related_table_lookup_field_id: projectsTable.getField('Project Manager').id // The field to look up
  }
});

Rollup

Performs calculations on linked records.

// Assuming we have a link from Projects to Tasks (one-to-many)
const tasksField = projectsTable.getField('Tasks');
const estimatedHoursField = tasksTable.getField('Estimated Hours');

// Create a Rollup field to sum the estimated hours of all tasks
await projectsTable.createFieldAsync({
  name: 'Total Estimated Hours',
  type: UITypes.Rollup,
  options: {
    related_field_id: tasksField.id, // The link field
    related_table_rollup_field_id: estimatedHoursField.id, // The field to roll up
    rollup_function: 'sum' // The function to apply
  }
});

Computed Fields

Formula

Calculated value based on a formula.

// Create a Formula field
await projectsTable.createFieldAsync({
  name: 'Days Until Due',
  type: UITypes.Formula,
  options: {
    formula: 'ADD(33, 43)'
  }
});

Created Time

Automatically stores the record creation time.

// Create a Created Time field
await projectsTable.createFieldAsync({
  name: 'Created At',
  type: UITypes.CreatedTime,
  options: {
    date_format: 'YYYY-MM-DD',
    time_format: 'HH:mm:ss',
    '12hr_format': false,
    timezone: 'UTC',
    display_timezone: true,
    use_same_timezone_for_all: true
  }
});

Last Modified Time

Automatically updates with the last record modification time.

// Create a Last Modified Time field
await projectsTable.createFieldAsync({
  name: 'Updated At',
  type: UITypes.LastModifiedTime,
  options: {
    date_format: 'YYYY-MM-DD',
    time_format: 'HH:mm:ss',
    '12hr_format': false,
    timezone: 'UTC',
    display_timezone: true,
    use_same_timezone_for_all: true
  }
});

Special Fields

Attachment

Stores file attachments.

// Create an Attachment field
await projectsTable.createFieldAsync({
  name: 'Documents',
  type: UITypes.Attachment
});

User

References users/collaborators of the base.

// Create a User field
await projectsTable.createFieldAsync({
  name: 'Assigned To',
  type: UITypes.User,
  options: {
    allow_multiple_users: false,
    notify_user_when_added: true
  }
});

Cell Values for Different Field Types

Different field types store and return values in specific formats. Understanding these formats is crucial when working with field values:

Text Fields

// Single Line Text & Long Text
const title = record.getCellValue('Title'); // string or null

Number Fields

// Number, Decimal, Currency, Percent
const amount = record.getCellValue('Amount'); // number or null

Boolean Fields

// Checkbox
const isCompleted = record.getCellValue('Completed'); // boolean or null

Date and Time Fields

// Date, DateTime, Time
const dueDate = record.getCellValue('Due Date'); // string in ISO format or null
// e.g., "2023-08-15" for Date, "2023-08-15T14:30:00.000Z" for DateTime

Selection Fields

// Single Select
const status = record.getCellValue('Status'); // string or null

// Multi Select
const tags = record.getCellValue('Tags'); // array of strings or empty array
// e.g., ["Urgent", "Bug"]

Relationship Fields

// Link to Another Record (single) One to One, Belongs to
const project = record.getCellValue('Project'); // Record object or null

// Link to Another Record (multiple) Many to Many, Has many
const team = record.getCellValue('Team Members'); // RecordQueryResult object or null

// Lookup (single value)
const manager = record.getCellValue('Project Manager'); // value or null

// Lookup (multiple values)
const skills = record.getCellValue('Skills'); // Array of values or empty array

Attachment Field

// Attachment
const documents = record.getCellValue('Documents');
// Array of attachment objects or empty array
// Each attachment has: { title, url, mimetype, size, ... }

// Example: List all attachments
if (documents && documents.length > 0) {
  for (const doc of documents) {
    output.text(`- ${doc.title} (${doc.mimetype}, ${doc.size} bytes)`);
  }
}

User Field

// User (single)
const assignee = record.getCellValue('Assigned To');
// Collaborator object or null with { id, name, email }

// User (multiple)
const reviewers = record.getCellValue('Reviewers');
// Array of Collaborator objects or empty array

Working with Fields

Getting a Field from a Table

// Get a field by name
const statusField = projectsTable.getField('Status');

// Get a field by ID
const titleField = projectsTable.getField('fld123456');

// Check field properties
if (statusField) {
  output.text(`Field: ${statusField.name}`);
  output.text(`Type: ${statusField.type}`);
  output.text(`Description: ${statusField.description || 'No description'}`);
  output.text(`Is computed: ${statusField.isComputed}`);
} else {
  output.text('Field not found');
}

Creating a New Field

// Create a new field
const newField = await projectsTable.createFieldAsync({
  name: 'Risk Level',
  type: UITypes.SingleSelect,
  description: 'Assessed risk level of the project',
  options: {
    choices: [
      { title: 'Low', color: '#00FF00' },
      { title: 'Medium', color: '#FFFF00' },
      { title: 'High', color: '#FF0000' }
    ]
  }
});

output.text(`Created new field: ${newField.name} (${newField.id})`);

Updating Field Options

// Get a Rating field
const priorityField = projectsTable.getField('Priority');

// Update its options
await priorityField.updateOptionsAsync({
  icon: 'star',
  max_value: 10, // Change from 5 to 10
  color: '#FFA500' // Change color
});

output.text('Field options updated successfully');

Working with Select Field Choices

// Get a Select field and its current choices
const categoryField = projectsTable.getField('Category');
const currentChoices = categoryField.options?.choices || [];

// Add a new choice
const updatedChoices = [
  ...currentChoices,
  { title: 'New Category', color: '#800080' }
];

// Update the field
await categoryField.updateOptionsAsync({
  choices: updatedChoices
});

output.text(`Added new category option. Now ${updatedChoices.length} categories available.`);

Best Practices

Check field type - Always verify a field's type before trying to work with type-specific options.
Handle null values - Remember that almost any field can have a null/empty value, so include null checks in your code.
Use appropriate update methods - Use updateOptionsAsync() for field options, updateNameAsync() for field names, and updateDescriptionAsync() for descriptions.
Be cautious with system fields - Some fields are system-controlled and have limitations on what you can modify.
Consider field dependencies - Remember that some fields (like Lookup and Rollup) depend on other fields, so consider the impact of changes.
Check field existence - Always verify a field exists before trying to access it.
Use field IDs for stability - When possible, reference fields by ID rather than name for scripts that need to be robust against field name changes.
Await async operations - Always use await when calling async methods to ensure proper execution flow.

Field

Base

Cursor