# Field

> Part of the NocoDB documentation (Workflows > Scripts > API Reference). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.

URL: https://nocodb.com/docs/workflows/scripts/api-reference/field
Last updated: 2026-10-03

The Field object in NocoDB Scripts gives access to the configuration of a table column, and the field types and their cell values.

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:**

```javascript
// 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:**

```javascript
// 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:**

```javascript
// 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:

```javascript
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.

```javascript
// 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.

```javascript
// 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.

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

#### Decimal

Number with decimal places.

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

#### Currency

Monetary values with currency symbol.

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

#### Percent

Percentage values.

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

#### Rating

Visual rating representation.

```javascript
// 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.

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

#### DateTime

Date and time values.

```javascript
// 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.

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

#### Duration

Time duration values.

```javascript
// 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.

```javascript
// 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).

```javascript
// 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).

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

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

#### User

References users/collaborators of the base.

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

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

### Number Fields

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

### Boolean Fields

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

### Date and Time Fields

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

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

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

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

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

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

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

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

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

1. **Check field type** - Always check the type of a field before you use type-specific options.

2. **Handle null values** - Almost all fields can have a null/empty value. Add null checks to your code.

3. **Use appropriate update methods** - Use `updateOptionsAsync()` for field options, `updateNameAsync()` for field names, and `updateDescriptionAsync()` for descriptions.

4. **Be careful with system fields** - The system controls some fields. You can change only some parts of these fields.

5. **Consider field dependencies** - Some fields (for example, Lookup and Rollup) depend on other fields. Think about the effect of your changes.

6. **Check field existence** - Always make sure that a field exists before you use it.

7. **Use field IDs for stability** - If a script must keep working when field names change, refer to fields by ID, not by name.

8. **Await async operations** - Always use `await` when you call async methods. This makes sure that the steps run in the correct order.

## Related

* [Base](/docs/workflows/scripts/api-reference/base)
* [Table](/docs/workflows/scripts/api-reference/table)
* [Record](/docs/workflows/scripts/api-reference/record)

---

## Related pages

- [Base](https://nocodb.com/docs/workflows/scripts/api-reference/base.md): The base object in NocoDB Scripts gives access to the tables and collaborators of the current base.
- [Cursor](https://nocodb.com/docs/workflows/scripts/api-reference/cursor.md): The cursor object in NocoDB Scripts tells a script which base, table, view and row are active.
- [Table](https://nocodb.com/docs/workflows/scripts/api-reference/table.md): The Table object in NocoDB Scripts represents a table and gives methods to query, create, update, and delete its records.
- [View](https://nocodb.com/docs/workflows/scripts/api-reference/view.md): The View object in NocoDB Scripts represents a view of a table and lets you query its records.
- [RecordQueryResult](https://nocodb.com/docs/workflows/scripts/api-reference/record-query-result.md): The RecordQueryResult object in NocoDB Scripts holds the records from a query and supports pagination.
- [Record](https://nocodb.com/docs/workflows/scripts/api-reference/record.md): The NocoDBRecord object in NocoDB Scripts represents one table row and gives methods to read its cell values.
- [Session](https://nocodb.com/docs/workflows/scripts/api-reference/session.md): The session object in NocoDB Scripts gives information about the user who runs the script.
- [Collaborator](https://nocodb.com/docs/workflows/scripts/api-reference/collaborator.md): The Collaborator object in NocoDB Scripts holds the ID, name and email of a user who has access to a base.