Field

The Field object is a column in a NocoDB table. It gives access to the configuration and metadata of the column. Fields set the structure of tables. They control how data is stored, validated, and shown.

Overview

NocoDB has many field types for different kinds of data. They go from simple text and numbers to complex types, for example attachments, links to other tables, and formulas. Use the Field object to:

Get field properties, for example 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 (for example, SingleLineText, Number, Date)
`description`	`string \| null`	The description of the field (if any)
`isComputed`	`boolean`	Whether the field value is computed, not directly editable
`options`	`object \| null`	Type-specific options for the field

Common Methods

All Field objects provide these methods:

updateOptionsAsync

Updates the options of the field.

Parameters:

options (object): The new options. The structure depends on the 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): The new description text, or null to remove the 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

The UITypes object in NocoDB Scripts has a constant for each field type:

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

Each NocoDB field type has its own properties and behavior. These are 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. It can also 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

Each field type stores and returns values in a specific format. Know these formats before you work 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('c123456');

// 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 check the type of a field before you use type-specific options.
Handle null values - Almost all fields can have a null/empty value. Add null checks to your code.
Use appropriate update methods - Use updateOptionsAsync() for field options, updateNameAsync() for field names, and updateDescriptionAsync() for descriptions.
Be careful with system fields - The system controls some fields. You can change only some parts of these fields.
Consider field dependencies - Some fields (for example, Lookup and Rollup) depend on other fields. Think about the effect of your changes.
Check field existence - Always make sure that a field exists before you use it.
Use field IDs for stability - If a script must keep working when field names change, refer to fields by ID, not by name.
Await async operations - Always use await when you call async methods. This makes sure that the steps run in the correct order.