# FAQs
URL: /docs/product-docs/FAQs

General FAQs





## How to upgrade NocoDB ?

* Please see [here](/docs/self-hosting/upgrading)

## What is available in free version ?

* [Detailed comparison of Community Edition vs Enterprise Edition is here](/docs/product-docs/cloud-enterprise-edition/community-vs-paid-editions).
* NocoDB has just one community edition version which is free forever.
* In it you will notice advanced features are all available for free.
  * ACL
  * Collaboration
  * Advanced Views : Form View, Gallery View & Kanban View
  * Share View
  * Embed View
  * Password protected View
  * Automations
  * API Token Support
* And we would never move these features from free to an enterprise version of NocoDB.
* There is no limitations to number of bases, records or fields either.

## Is NocoDB available on the cloud?

Yes! NocoDB is currently available in technical preview.
You can simply signup by clicking [here](https://app.nocodb.com/#/signin?utm_source=OSS\&utm_medium=OSS\&utm_campaign=OSS\&utm_content=OSS).

## Why is the feature I need not in Community Edition?

We know it can be disappointing when a feature you need isn’t available in community edition.
But before we react, let’s reflect: NocoDB community edition is empowering over 20,000 companies — for free without any cost.

In the sector of software that often takes, we choose to give. Yet, to continue serving with integrity,
some capabilities are part of our paid plans — not as a barrier, but as a way to sustain the service for all.
Should you need these features, you’re welcome to support us through the cloud or a self-hosted license.

## Scrollbar disappears, how should I make it visible always?

NocoDB follows the system settings for scrollbars. If you have configured your system to always show scrollbars,
NocoDB will respect that setting. If you want to change this behavior, you can adjust your system settings accordingly.

<img alt="image" src={__img0} placeholder="blur" />

## How to check my Base info in the community edition ?

* You can open `Base context menu` and click `Copy Base Info`.

<img alt="image" src={__img1} placeholder="blur" />

You should see the similar result as below.

```
Node: **v20.15.1**
Arch: **x64**
Platform: **linux**
Docker: **true**
RootDB: **pg**
PackageVersion: **0.258.2**
```

## What are the official socials for NocoDB?

* Youtube: [https://www.youtube.com/@nocodb](https://www.youtube.com/@nocodb)
* Twitter: [https://twitter.com/nocodb](https://twitter.com/nocodb)
* Discord: [http://discord.nocodb.com/](http://discord.nocodb.com/)
* GitHub: [https://github.com/nocodb/nocodb](https://github.com/nocodb/nocodb)
* Community Forums: [https://community.nocodb.com/](https://community.nocodb.com/)
* LinkedIn: [https://www.linkedin.com/company/nocodb](https://www.linkedin.com/company/nocodb)
* Reddit: [https://www.reddit.com/r/NocoDB/](https://www.reddit.com/r/NocoDB/)

## SSO (Single Sign-On) FAQs

For all questions related to SSO, please see the dedicated SSO FAQ section: [SSO FAQs](/docs/product-docs/account-settings/authentication/FAQs)


# Welcome
URL: /docs/product-docs

NocoDB Documentation



<img alt="image" src={__img0} placeholder="blur" />

NocoDB is a no-code database platform that allows teams to collaborate and build processes with ease of a familiar and intuitive spreadsheet interface.
This allows even non-developers or business users to become software creators.

## Features

### Rich Spreadsheet Interface

* Basic Operations: Create, Read, Update and Delete on Tables, Fields, and Records
* Fields Operations: Sort, Filter, Group By, Search, Hide / Reorder Fields
* Rich Field Types: Text, Number, Date/Time, Select, Attachment, Formula, Links, Lookup, Rollup and more
* Multiple View Types: Grid (default), Form, Gallery, Kanban, Calendar, Timeline, List and Map
* View Permissions: Collaborative Views, Locked Views, and Personal Views
* Share Bases / Views: Public or Private (with Password Protection)
* Access Control with Roles: Fine-grained access control at Workspace, Base, Table, Field, and Record levels

### Automation & Scripting

* Workflows: Visual workflow builder with triggers, actions, conditions, and loops (beta)
* Scripts: JavaScript-based automation with full API access to bases, tables, fields, and records
* Webhooks: Event-driven notifications on record create, update, and delete

### Dashboards & Extensions

* Dashboards: Build visual dashboards with chart widgets (Bar, Line, Pie, Donut), numbers, text, and iframes
* Extensions: Bulk Update, Data Exporter, Dedupe, Org Chart, Page Designer, URL Preview, and more

### AI & Integrations

* NocoAI: AI-assisted creation of bases, tables, fields, views, filters, formulas, and select options
* NocoDocs: Built-in document editor with rich text, comments, AI assistant, and permissions
* NocoSync: Sync data from GitHub, GitLab, Bitbucket, and Linear
* Integrations: Connect external data sources (PostgreSQL, MySQL, SQL Server, and more)

### Programmatic Access

* REST APIs
* MCP Server: Model Context Protocol server for AI agent integration

## Why are we building this?

Most internet businesses equip themselves with either spreadsheet or a database to solve their business needs.
Spreadsheets are used by a Billion+ humans collaboratively every single day.
However, we are way off working at similar speeds on databases which are way more powerful tools when it comes to computing.
Attempts to solve this with SaaS offerings has meant horrible access controls, vendor lockin, data lockin, abrupt price changes
& most importantly a glass ceiling on what's possible in the future.

## Our Mission

Our mission is to provide the most powerful no-code interface for databases, accessible to every internet business across the world. By making this capability broadly available under a fair and sustainable model, we aim to democratise access to powerful computing tools and enable a billion-plus people to develop radical tinkering and building abilities on the internet.

Follow us for updates, content, and other activities with our community:

* [Youtube](https://www.youtube.com/@nocodb)
* [Twitter](https://twitter.com/nocodb)
* [Discord](http://discord.nocodb.com/)
* [GitHub](https://github.com/nocodb/nocodb)
* [Community Forums](https://community.nocodb.com/)
* [LinkedIn](https://www.linkedin.com/company/nocodb)
* [Reddit](https://www.reddit.com/r/NocoDB/)


# MCP Server
URL: /docs/product-docs/mcp

Connect NocoDB to Large Language Models (LLMs) via the Model Context Protocol (MCP).



































The **Model Context Protocol (MCP) Server** lets you connect NocoDB with LLMs that support MCP, such as Claude, Cursor, or Windsurf. With this integration, LLMs can interact directly with your NocoDB base to create, query, update, and manage records.

## Desktop LLM Clients

Each MCP endpoint in NocoDB provides a secure URL that can be linked to an MCP-compatible client.
Once configured, the LLM can execute database operations in your workspace through natural language prompts.

MCP server exposes standard CRUD operations. These can be triggered conversationally, without writing SQL or scripts.

| Action | Purpose              | Sample Prompt                                                 |
| ------ | -------------------- | ------------------------------------------------------------- |
| Create | Add new records      | Create a task named ‘Review Documentation’                    |
| Read   | Look up information  | Show me all projects with deadlines this week                 |
| Update | Change existing data | Mark the status of Project X as completed & re-assign to John |
| Delete | Remove records       | Remove all tasks assigned to John                             |

<Callout type="note">
   NocoDB MCP supports only record-level operations and does not handle table, field, or other metadata changes. 
</Callout>

### Server Configuration (NocoDB)

1. Click on the **Overview** button in the left sidebar.
2. Select the **Settings** tab.
3. Select the **Model Context Protocol**
4. Click on the **New MCP Endpoint** to create a new MCP config JSON for your base.
5. Provide a name for the MCP endpoint
6. Click **Create** to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

<img alt="MCP Config" src={__img0} placeholder="blur" />

<img alt="MCP Config" src={__img1} placeholder="blur" />

### Client Configuration

#### Claude

1. Open **Claude Desktop Preferences** (`⌘+,`).
2. Under **Develop**, click **Edit Config**.
3. Insert the JSON block copied [here](#server-configuration-nocodb) as `claude_desktop_config.json`.
4. Save the file and restart Claude Desktop.

#### Cursor

1. Go to **Cursor Settings** (`⇧+⌘+J`).
2. Open the **MCP** tab and select **Add Custom MCP**.
3. Paste the JSON block copied [here](#server-configuration-nocodb). Save.

<Callout type="info">
   On success, you will see 

  `11 tools enabled`

   below the MCP Server just installed. If you see an error, double-check the JSON configuration. 
</Callout>

<img alt="Cursor MCP Settings" src={__img2} placeholder="blur" />

#### Windsurf

1. Open **Windsurf Settings** (`⌘+,`).
2. In the **Cascade** section > `Plugins (MCP Server)` > Click **Manage Plugins**
3. Paste the JSON block copied [here](#server-configuration-nocodb). Save.

<img alt="Windsurf MCP Settings" src={__img3} placeholder="blur" />

<img alt="Windsurf MCP Settings" src={__img4} placeholder="blur" />

### JSON Example

```json
{
  "mcpServers": {
    "NocoDB MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/mcp/<ncId>",
        "--header",
        "xc-mcp-token: <ncToken>"
      ]
    }
  }
}

```

<Callout type="warning">
   Your MCP configurations generated above functions as a set of access credentials, granting full control over your NocoDB base. Ensure it remains confidential, never include it in source control, and store it only in secure, protected locations.
</Callout>

***

## Web based LLM Clients (OAuth)

Connect NocoDB to web-based LLM applications using OAuth, enabling seamless database access directly from the browser without requiring desktop client setup. This approach grants granular permission controls and eliminates the need for manual JSON configuration.

### Claude Web

OAuth-based integration allows Claude web users to access NocoDB databases through the connectors interface.

#### Setup Steps

1. Click [here](https://claude.ai/settings/connectors) to open Claude Web Settings in a new tab.
   * Alternatively, navigate to **Settings** > **Connectors** from the Claude Web app.
2. Click **Add custom connector**.
   <img alt="open-connectors" src={__img5} placeholder="blur" />
3. In the "Add custom connector" dialog:
   * Provide a connector name of your choice
   * Enter the MCP endpoint URL: `https://app.nocodb.com/mcp`
   * Click `Add`
     <img alt="add-connector-dialog" src={__img6} placeholder="blur" />
4. NocoDB Connector will now be listed in "Disconnected" state. Click **Connect** to initiate the OAuth authorization flow (Opens in a new tab).
   <img alt="add-connector" src={__img7} placeholder="blur" />
5. Authorize Access
   * You will be asked to log in to your NocoDB account (if not already logged in)
   * Select the workspace and base you want to connect
   * Confirm the permissions Claude will have
     * Access the selected base
     * Read / create / update / delete records in the selected base
     * Act on your behalf within the selected resources
   * Click **Authorize** to grant access
     <img alt="authorize-access" src={__img8} placeholder="blur" />

With this, the NocoDB connector will move to "Connected" state in Claude Web. You can now interact with your NocoDB data through Claude web application.

<Callout type="note">
   On-prem enterprise users should replace 

  [https://app.nocodb.com](https://app.nocodb.com)

   with their NocoDB instance URL
</Callout>

#### Configure Tool Permissions

By default, all tools are set to "Always ask permission" to ensure you have control over each operation Claude performs. You can modify these settings as needed.

Click [here](https://claude.ai/settings/connectors) to open Claude Web Settings in a new tab. Click **Configure** on the NocoDB connector to manage tool permissions. Set each tool's permission level using the dropdown menu:

* **Always ask permission** — Your approval is required every time Claude uses this tool
* **Allow unsupervised** — Claude can use this tool without requesting approval

<img alt="tool-permissions" src={__img9} placeholder="blur" />
<img alt="tool-permissions" src={__img10} placeholder="blur" />

To retrieve Workspace & Base information that this connector has access to, use the "Get Base Info" tool.
<img alt="get-base-info" src={__img11} placeholder="blur" />

#### Using NocoDB Tools in Claude Web

Once configured, you can interact with your NocoDB data conversationally. For example:

* "Show me all projects with deadlines this week"
* "Create a task named 'Review Documentation'"
* "Mark the status of Project X as completed and reassign to John"
* "Provide details of our top 3 sponsors"

Claude will execute these requests using the enabled NocoDB tools, reading from and writing to your database based on the permissions you've granted.

<img alt="connected-connector" src={__img12} placeholder="blur" />

<Callout type="warning">
  OAuth authorization functions as a set of access credentials granting Claude control over your NocoDB base within the selected workspace. Only authorize access to bases and operations you trust Claude to perform on your behalf.
</Callout>

### ChatGPT

OAuth-based integration enables OpenAI web users (ChatGPT) to securely connect with NocoDB databases through the MCP connector, directly from their browser environment. This provides the same granular access control and eliminates the need for manual configuration or desktop client setup.

#### Prerequisites

Enable Developer Mode in ChatGPT settings to allow custom connector additions.

1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
   * Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. Click **Advanced Settings** & enable **Developer Mode**.

<img alt="open-connectors" src={__img13} placeholder="blur" />

#### Setup Steps

1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
   * Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. Click **Create** button in top right corner of the **Connectors** modal.
3. In the "New connector" dialog:
   * Provide a connector name of your choice. Optionally, add a description / icon.
   * Enter the MCP Server URL: `https://app.nocodb.com/mcp`
   * Check the box for **I trust this application**.
   * Click `Create`
     <img alt="new-connector" src={__img14} placeholder="blur" />
4. Authorize Access:
   * Log in to your NocoDB account if prompted
   * Select the workspace and base you want to connect
   * Review and confirm the permissions being requested:
     * Access to the selected base
     * Read / create / update / delete records
     * Act on your behalf within the selected resources
   * Click **Authorize**

Once authorization completes, you will see a confirmation message in ChatGPT Web indicating the NocoDB connector is now connected.
<img alt="connected" src={__img15} placeholder="blur" />

<Callout type="note">
  For on-prem enterprise users, replace 

  `https://app.nocodb.com`

   with your NocoDB instance URL.
</Callout>

#### Using NocoDB Tools in OpenAI Web

On the ChatGPT interface, start a new conversation and

* Click the **+** icon to open the "Tools" menu, enable `Developer Mode` if not already enabled.
* Click `More` to find and select the NocoDB connector you created. Toggle to enable it.
  <img alt="using-connector" src={__img16} placeholder="blur" />

Once configured, you can query or update your NocoDB data conversationally. For example:

* “List all open support tickets assigned to me”
* “Add a new contact named ‘Alice Chen’ to the CRM base”
* “Update the status of Order #2456 to ‘Shipped’”
* “Summarize total revenue by month from the Sales base”

ChatGPT executes these actions using the connected NocoDB tools according to the permissions granted.

<Callout type="warning">
  OAuth authorization provides ChatGPT controlled access to your NocoDB base within the selected workspace. Only authorize operations and bases you trust ChatGPT to manage on your behalf.
</Callout>

***


# Skills
URL: /docs/product-docs/skills

Extend Claude's capabilities with the NocoDB skill for managing nocodb bases through natural language.

#### Setup

* Download the [NocoDB Skill](/nocodb-skills.zip)
* Get your API token from NocoDB
* Upload the skill to Claude
* Configure environment variables

#### Usage

Claude automatically uses the skill when relevant. Interact with your databases using natural language:

| Action          | Sample Prompt                                     |
| --------------- | ------------------------------------------------- |
| List workspaces | "Show me all my NocoDB workspaces"                |
| View tables     | "List all tables in my Sales base"                |
| Query records   | "Show me all customers from New York"             |
| Create records  | "Add a new task called 'Review Documentation'"    |
| Update records  | "Mark order #123 as shipped"                      |
| Delete records  | "Remove all completed tasks from last month"      |
| Filter data     | "Find all high-priority tickets that are overdue" |

#### Supported Operations

* **Workspaces**: List, create, update, delete, manage members
* **Bases**: List, create, update, delete
* **Tables**: List, create, update, delete
* **Fields**: List, create, update, delete (all field types)
* **Views**: List, create, update, delete (grid, gallery, kanban, calendar)
* **Records**: List, get, create, update, delete, count with filtering
* **Linked Records**: List, add, remove relationships
* **Filters & Sorts**: Create view-level filters and sorts
* **Attachments**: Upload files to records

#### Related

* [MCP Server](/docs/product-docs/mcp) - Connect NocoDB to LLMs via Model Context Protocol


# Table details
URL: /docs/product-docs/table-details

Manage fields, relations, APIs, and webhooks for your table













`Table Details` helps **creators** manage table structure and integrate with external systems. Access it using the `Data-Details` toggle in the top navbar.

<img alt="image" src={__img0} placeholder="blur" />

## Fields

Manage all your fields in one place — add, edit, delete, or reorder using the multi-field editor.
Learn more about the [multi-field editor](/docs/product-docs/fields/multi-fields-editor).

<img alt="image" src={__img1} placeholder="blur" />

## Permissions

Control who can add / delete records in your table & who can edit fields. Refer to the [Table permissions](/docs/product-docs/roles-and-permissions/table-permissions) and [Field permissions](/docs/product-docs/roles-and-permissions/field-permissions) documentation for more details.

<img alt="image" src={__img2} placeholder="blur" />

## Relations

Visualize and manage how tables connect using the Entity Relationship Diagram (ERD). This helps in:

* Designing your schema
* Ensuring data integrity
* Improving query performance

<Callout type="note">
  Drag-and-drop to rearrange tables in the ERD. Layout changes aren’t saved across sessions.
</Callout>

<img alt="image" src={__img3} placeholder="blur" />

## API Snippet

Use prebuilt REST API examples to interact with your table programmatically — in Shell, JavaScript, Python, and more. Ideal for quickly connecting NocoDB to your applications.

<img alt="image" src={__img4} placeholder="blur" />

### Supported languages

* **Shell:** cURL, wget
* **JavaScript:** Axios, Fetch, jQuery, XHR
* **Node:** Axios, Fetch, Request, Native, Unirest
* **NocoDB SDK:** JavaScript, Node
* **Python:** http.client, requests
* **PHP**, **Ruby**, **Java**, **C**

## Webhooks

Set up real-time triggers when records change. Use webhooks to:

* Send instant alerts
* Automate external workflows
* Sync data across platforms
* Handle batch updates efficiently

<img alt="image" src={__img5} placeholder="blur" />

<Callout type="note">
  Webhooks are defined per table. More details 

  [here](/docs/product-docs/automation/webhook)

  .
</Callout>

***


# API tokens
URL: /docs/product-docs/account-settings/api-tokens

This article explains how to create and work with API Tokens, including fine-grained tokens with scoped permissions.































NocoDB supports two types of API tokens:

* **Fine-grained tokens** — Scoped to specific bases with granular permission categories. Recommended for all new integrations.
* **Legacy tokens** — Org-wide tokens that inherit the creator's full role permissions.

***

## Fine-Grained API Tokens

Fine-grained API tokens give you precise control over what external integrations, scripts, and CI/CD pipelines can do in NocoDB. Unlike legacy tokens, fine-grained tokens let you restrict access to specific bases with granular permission categories.

<Callout type="info">
  Fine-grained tokens are available on all tiers. Granular scope and permission controls (base selection, permission categories) are available on 

  **Business**

   and above plans (Cloud) and 

  **licensed Self-hosted**

  . On Community Edition and unlicensed Self-hosted, tokens default to all-resources access.
</Callout>

### Key Concepts

* **Intersection model** — A token can only *restrict* what your role already allows. It never grants additional permissions beyond your role.
* **Deny by default** — Only permission categories you explicitly add are granted. Everything else is denied.
* **Show-once token** — The token string is displayed only at creation time and cannot be retrieved later. The token is stored as a SHA-256 hash — the plaintext is never persisted.

### Create a Fine-Grained Token

Navigate to **Account Settings** > **API Tokens** and click **Create new token**. This opens a single-page form with four sections.

<img alt="Create token form" src={__img0} placeholder="blur" />

#### Name

Give your token a descriptive name that identifies its purpose (e.g., "CI/CD Pipeline", "Zapier Integration"). The name must be between 1 and 255 characters.

#### Scopes (Permissions)

Define what operations this token can perform. Permissions use an additive model — start with no permissions and add only the categories you need.

Click **+ Add permission** to open a dropdown listing all available permission categories. Select a category to add it.

<img alt="Add permission dropdown" src={__img1} placeholder="blur" />

Each added category appears as a row with an access-level pill that defaults to **Read only**. Click the pill to switch between:

<img alt="Access level dropdown" src={__img2} placeholder="blur" />

* **Read only** — Read-level access for that category
* **Read & write** — Full read and write access for that category

To remove a category, click the **×** button on its row. Any category not explicitly added will have no access.

The eight permission categories are:

| Category                                            | Read only                | Read & write                 |
| --------------------------------------------------- | ------------------------ | ---------------------------- |
| **Records** — record CRUD, data export, aggregation | List, read, export       | Create, update, delete       |
| **Comments** — record comments                      | View comments            | Post, edit, delete           |
| **Tables** — table management                       | List, read               | Create, update, delete       |
| **Fields** — column/field management                | List columns             | Create, update, delete       |
| **Views** — views, sorts, filters, sharing          | List views and config    | Create, update, delete       |
| **Webhooks** — webhook triggers and logs            | List, view logs          | Create, update, delete, test |
| **Base** — base settings, sources, jobs             | View info, swagger, jobs | Create sources, delete base  |
| **Users** — base and workspace members              | List members             | Invite, update roles, remove |

#### Access (Resource Scope)

Define which resources this token can access. Two options are available:

* **Add all resources** — Token can access all current and future bases across all workspaces.
* **Add a base** — Opens a searchable dropdown with bases grouped by workspace. Select individual bases to grant access.

<img alt="Add a base dropdown" src={__img3} placeholder="blur" />

You can add multiple bases. Selected resources appear in a bordered list where each item can be removed with the **×** button. If you add "All resources", any previously selected individual bases are cleared.

<img alt="All resources selected" src={__img4} placeholder="blur" />

<Callout type="info">
  At least one resource must be selected on licensed plans. Use 

  **Add all resources**

   for org-wide access, or 

  **Add a base**

   to restrict to specific bases. On Community Edition and unlicensed Self-hosted, tokens automatically have all-resources access.
</Callout>

#### Expiration

Choose an expiration period from the dropdown:

* **7 days**, **30 days**, **60 days**, **90 days** (default), **1 year** — preset options
* **Custom** — pick a specific date
* **No expiration** — the token never expires

<Callout type="info">
  We recommend setting an expiration for better security. Expired tokens are automatically rejected.
</Callout>

Here is an example of a completed form with permissions and base scope configured:

<img alt="Filled create token form" src={__img5} placeholder="blur" />

Click **Create Token** to generate the token.

#### Copy Your Token

After creation, a modal displays the token string **once**. Copy it immediately and store it securely.

The token format is `nc_pat_` followed by 40 random characters:

```
nc_pat_V1StGXR8_Z5jdHi2B-xoMwDqE3G4n5p6q7r8s
```

The **Done** button is only enabled after you copy the token.

<img alt="Token created modal" src={__img6} placeholder="blur" />

<Callout type="warn">
  This token will not be displayed again after you close this dialog. If you lose it, you must delete the token and create a new one.
</Callout>

### Manage Tokens

The token list shows all your API tokens with columns: **Active** (toggle), **Token Name**, **Creator** (with avatar and email), **Expires On**, and **Actions**.

<img alt="Token list" src={__img7} placeholder="blur" />

Fine-grained tokens display an **Expired** badge (red) when past their expiry date, and an **SSO** badge (orange) if created through SSO authentication.

#### Token Actions

Each token row provides action icons:

* **Edit** (pencil icon) — Opens the edit form inline, replacing the list view.
* **Delete** (trash icon) — Opens a confirmation dialog to permanently delete the token.

#### Edit a Token

Clicking edit opens the same form used for creation, pre-filled with the token's current values. You can update:

* **Token name** — Change the descriptive name
* **Scopes (Permissions)** — Add, remove, or change permission categories and their access levels
* **Access (Resource Scope)** — Add or remove bases, or switch to all resources
* **Expiration** — Extend or set a new expiry date. A **Keep** option preserves the current expiry.

<img alt="Expiration dropdown in edit mode" src={__img8} placeholder="blur" />

Click **Save** to apply changes, or **Cancel** to return to the token list.

#### Enable / Disable a Token

Use the **Active** toggle on any token row to enable or disable it. A disabled token receives `401 Unauthorized` on all requests. Re-enable it at any time to restore access. This is useful for:

* Investigating suspicious activity without permanently revoking access
* Temporarily pausing an integration during maintenance

### Permission Enforcement

For each API request, the system checks:

1. **Is the token valid?** — exists, not expired, enabled
2. **Does the scope match?** — if base-scoped, the requested base must be in the token's scope
3. **Does the user's role allow this operation?** — standard role-based ACL check
4. **Does the token's permission level allow this operation?** — operation mapped to a category and checked against the token's level

All four checks must pass. The effective permission is the **intersection** of the user's role and the token's granted permissions.

| Scenario                                      | HTTP Status |
| --------------------------------------------- | ----------- |
| Token is valid and has sufficient permissions | `200`       |
| Token is expired                              | `401`       |
| Token is disabled                             | `401`       |
| Token does not exist or is malformed          | `401`       |
| Token scope does not match the requested base | `401`       |
| Token permission level is insufficient        | `403`       |

***

## Legacy API Tokens

<Callout type="warn">
  Legacy token creation is no longer available in the UI. The V1 API still supports creating them for backward compatibility, but we recommend using fine-grained tokens for all new integrations.
</Callout>

Legacy tokens are org-scoped and inherit the creator's full role permissions. They remain functional for backward compatibility but we recommend migrating to fine-grained tokens for better security and control.

### Create a Legacy Token (Deprecated)

1. Click on `User menu` in the bottom left corner of the sidebar
2. Select `Account Settings` from the dropdown

<img alt="profile page" src={__img9} placeholder="blur" />

3. Click on `Tokens` tab in the `Account Settings` page
4. Click on `Add New API Token`
5. Enter the name for the API Token
6. Click on `Save` button to save the changes
7. Copy the API Token by clicking on `Copy` button displayed under `Actions` menu

<img alt="Create API Token" src={__img10} placeholder="blur" />

<img alt="Create API Token" src={__img11} placeholder="blur" />

<Callout type="info">
  Legacy API tokens do not expire, but can be deleted anytime.
</Callout>

API Token created will get added to the list. Copy API token by clicking on `Copy` button displayed under `Actions` menu.

<img alt="Create API Token" src={__img12} placeholder="blur" />

### Delete a Token

<Callout type="warn">
  All services using the API token will stop working once the token is deleted.
</Callout>

1. Click on `User menu` in the bottom left corner of the sidebar
2. Select `Account Settings` from the dropdown
3. Click on `Tokens` tab in the `Account Settings` page
4. From the `Actions` menu, click on `Delete` button associated with the API token to be deleted

<img alt="Delete API Token" src={__img13} placeholder="blur" />

***

## Authentication

Both fine-grained and legacy tokens support two authentication methods:

### Method 1: xc-token Header

```bash
curl -H "xc-token: nc_pat_..." https://your-nocodb.com/api/v3/...
```

### Method 2: Authorization Header

```bash
curl -H "Authorization: Bearer nc_pat_..." https://your-nocodb.com/api/v3/...
```

Both methods are equivalent. Choose the one that best fits your application's authentication patterns.

***

## Security Best Practices

1. **Set an expiration** — Use the shortest expiry that meets your needs. 90 days is a good default.
2. **Use the least permissions necessary** — A read-only dashboard only needs `Records: Read`.
3. **Scope to specific bases** — Avoid "All resources" when the integration only needs access to one base.
4. **Rotate tokens regularly** — Create a new token, update your integration, then delete the old one.
5. **Disable before deleting** — If you suspect a token is compromised, disable it immediately via the Active toggle to investigate before deleting.
6. **Store tokens securely** — Use environment variables or a secrets manager. Never hardcode tokens in source code.
7. **Audit your tokens** — Periodically review your token list. Delete tokens that are no longer needed.

***

## API Token Access with SSO-Enabled Workspaces

If a workspace is configured to enforce Single Sign-On (SSO), API access to that workspace is restricted to tokens that are created **after authenticating via SSO**.

<Callout type="warn">
  **Tokens created before SSO was enabled**

   do not have the necessary identity context and 

  **will not work**

   for SSO-enforced workspaces.
</Callout>

To access an SSO-enforced workspace via API, users must:

1. Sign in using SSO.
2. Generate a new API token from their authenticated session.

<Callout type="info">
  Tokens created before SSO enforcement may still work for other workspaces that do not require SSO.
</Callout>

For ease of identification, tokens created after SSO is enabled will have a badge indicating they were generated through SSO authentication.

<img alt="API Token SSO Badge" src={__img14} placeholder="blur" />

### What Happens When SSO is Disabled?

If SSO is later disabled for a workspace:

* API tokens that were created via SSO authentication will **continue to work** as long as the user is still active and has the required permissions.
* Tokens created prior to enabling SSO will continue to function & can now access the workspace without SSO authentication.
* No tokens are automatically revoked when SSO is disabled.


# Appearance
URL: /docs/product-docs/account-settings/appearance

This article explains how to customize the appearance of the NocoDB interface, including switching between Light and Dark modes.





NocoDB allows you to customize the visual appearance of the interface to suit your working preferences and environment.

## Dark mode

Dark mode reduces screen glare and can be more comfortable for extended usage, especially in low-light environments.

### Switching between modes

You can quickly switch between **Light** and **Dark** modes using the mode switch icon available in the left-side mini bar.

1. Locate the **Appearance** (sun/moon) icon in the left mini bar.
2. Click the icon to toggle between **Light** and **Dark** modes.

<img alt="Appearance mode switch" src={__img0} placeholder="blur" />

<img alt="Appearance mode switch" src={__img1} placeholder="blur" />

<Callout type="info">
  Appearance settings are applied instantly and stored in the browser’s local storage. This means that the selected mode will persist across sessions on the same browser.
</Callout>

***


# Experimental Features
URL: /docs/product-docs/account-settings/experimental-features

Learn how to enable or disable experimental features in NocoDB to try out new capabilities before they are generally available.

NocoDB includes an **Experimental Features** panel that lets you try out new capabilities before they are generally available. These features are still under development and may change or be removed in future releases.

## Accessing Experimental Features

1. Click on your **profile picture** in the bottom-left corner of the sidebar.
2. Select **Experimental Features** from the menu.

<img src="/img/v2/account-settings/ef-1.png" alt="Experimental Features menu" width="312" />

A panel opens listing all available experimental features, each with a toggle to enable or disable it and a brief description of what it does.

<img src="/img/v2/account-settings/ef-2.png" alt="Experimental Features panel" width="450" />

## Available Experimental Features

| Feature                    | Description                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| **Bases V3**               | Experience the next generation of NocoDB with Bases V3 with enhanced performance and optimizations. |
| **Infinite Scrolling**     | Effortlessly browse large datasets with infinite scrolling.                                         |
| **Link To Another Record** | Show linked record display value in Link fields.                                                    |
| **Cross Base Link**        | Enables link creation between tables in different bases.                                            |
| **Custom Link**            | Allows user to create custom links using existing fields.                                           |
| **Templates**              | Enable templates feature to browse and use templates.                                               |
| **Optimized Kanban View**  | Optimized Kanban view with optimised API for better performance.                                    |
| **Map View**               | Enable map view to visualize geo data fields on an interactive map.                                 |
| **Timeline View**          | Enable timeline view to visualize date-based data on a timeline.                                    |

<Callout type="info">
  The list of experimental features may vary across NocoDB versions as new features are added and existing ones are promoted to general availability. Additionally, the available features can differ depending on your deployment type — NocoDB Cloud, self-hosted licensed (Enterprise), or self-hosted OSS.
</Callout>

## Toggle All Features

Use the **toggle all** switch at the top of the panel to enable or disable all experimental features at once. You can also use the **search bar** to quickly find a specific feature.

<Callout type="warning">
  Experimental features may be unstable or incomplete. Use them with caution in production environments.
</Callout>

***


# Language settings
URL: /docs/product-docs/account-settings/language

This article explains how to change the language settings in NocoDB.



<Callout type="warning">
  Language support is currently in beta. Some parts of the interface may still appear in English, as translations might be incomplete or missing.
</Callout>

NocoDB supports multiple languages for its user interface to help users work in their preferred language.

You can change the language directly from the app:

1. Click on your profile picture in the bottom-left corner.
2. Select **Language** from the dropdown menu.
3. Choose from the list of available languages.

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="info">
  The translations in NocoDB are community-driven and enhanced using AI-generated translations. As a result, some phrases or words may be inaccurate or not fully localized. We appreciate your help in improving translations!
</Callout>

## Contribute to Translations

You can help improve translations or add support for new languages through our community translation platform on [Crowdin](https://crowdin.com).

* NocoDB Project link: [https://crowdin.com/project/nocodb](https://crowdin.com/project/nocodb)

To contribute:

* Sign up or log in to Crowdin.
* Join the NocoDB project.
* Select your language and start translating or reviewing existing translations.

For more details, refer [here](/docs/product-docs/engineering/translation)

Every contribution helps make NocoDB more accessible across the world!

***


# In Community Edition
URL: /docs/product-docs/account-settings/oss-specific-details

This article explains Account settings specifics in Community Edition NocoDB.





Some of the Account settings features are available only in Community Edition NocoDB. This article explains details about such specifics.

## Enable / Disable Signup

Signup without an invitation is disabled by default and can be managed from UI by a super admin.

<img alt="Invite only signup" src={__img0} placeholder="blur" />

## App Store

App store lists available integrations for NocoDB. You can install and configure these integrations from the App store.

<img alt="App Store" src={__img1} placeholder="blur" />
We provide different integrations in three main categories.

| Category    | App Name                                                                                                                                                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chat**    | Microsoft Teams <br /> Discord <br /> Twilio <br /> Whatsapp Twilio<br /> Mattermost<br /> Slack                                                                                                                                       |
| **Email**   | SMTP<br /> MailerSend<br /> AWS SES                                                                                                                                                                                                    |
| **Storage** | AWS S3 <br /> Minio <br /> Google Cloud Storage <br /> Spaces <br /> Backblaze B2 <br /> Vultr Object Storage <br /> OvhCloud Object Storage <br /> Linode Object Storage <br /> UpCloud Object Storage <br /> Scaleway Object Storage |


# Profile page
URL: /docs/product-docs/account-settings/profile-page

This article explains how to manage your profile page.











Profile page is the place where you can manage your profile information. Currently, only a custom username can be setup as part of profile configuration. To access your profile page,

1. Click on `User menu` in the bottom left corner of the sidebar,
2. Select `Account Settings` from the dropdown
3. Change `Profile name`
4. Click on `Save` button to save the changes

<img alt="delete account" src={__img0} placeholder="blur" />

<img alt="profile page" src={__img1} placeholder="blur" />

## Delete Account

<Callout>
  This option is available currently only for the cloud users.
</Callout>

To delete your account permanently,

1. Click on `User menu` in the bottom left corner of the sidebar,
2. Select `Account Settings` from the dropdown
3. In the section for delete account, click on `Delete Account` button
4. Confirmation modal displays the Workspaces, Bases & Tokens that will be invalidated upon deletion. As a confirmation step, you will be asked to enter your email address associated with the account.
5. Click on `Delete Account` button to delete the account permanently.

<img alt="delete account" src={__img2} placeholder="blur" />

<img alt="delete account" src={__img3} placeholder="blur" />

<img alt="delete account" src={__img4} placeholder="blur" />

<Callout type="warn">
  * Deleting the account is irreversible and all the data associated with the account will be lost permanently.
  * All the workspaces & bases for which you are the sole owner will be deleted. For all other workspaces & bases, you access permissions will be revoked.
  * All the tokens associated with the account will be invalidated.
  * You will be allowed to re-register with the same email address. However, you will require invite from the existing workspace owner to access the workspaces & bases.
</Callout>


# Admin Panel
URL: /docs/product-docs/cloud-enterprise-edition/admin-panel

This article explains how to use the Admin Panel in Cloud & Self hosted Enterprise Edition.



























The Admin Panel in NocoDB provides organization-level oversight and control. It allows administrators to monitor usage metrics, manage workspaces and bases, provision and track users, configure Single Sign-On (SSO), and update branding settings. This guide walks through each section available within the Admin Panel to help administrators maintain governance, enforce security, and keep user and workspace configurations aligned with organizational standards.

## Navigation Overview

Admin panel is accessible for users with administrative privileges. To access the Admin Panel, click on the **Admin Panel** option located in the user menu in the bottom-left corner of the NocoDB interface.

<img alt="image" src={__img0} placeholder="blur" />

The Admin Panel interface includes a sidebar menu with persistent access to the following sections:

* Dashboard
* Workspaces
* Bases
* User Management
* Single Sign-On (SSO)
* Teams
* SCIM
* Settings

Use the **Back** button in the top-left corner to return to the main NocoDB application interface.

### Dashboard

The Dashboard offers a high-level overview of key metrics across your NocoDB deployment. It acts as a basic control center for admins to monitor system usage and understand the scale of their organization’s data and user base. While the current functionality is limited, the visual summaries make it easy to track a few critical numbers at a glance.

<img alt="image" src={__img1} placeholder="blur" />

**Displayed Metrics:**

* **Workspaces** – Number of workspaces created within the organization.
* **Users** – Count of unique users who are part of the organization.
* **Bases** – Total number of bases created across all workspaces.
* **Editors** – Number of users with Editor-level access or above.

### Workspaces

The **Workspaces** section lists all active workspaces within your organization. Each workspace displays its name, number of members, and number of bases. This view helps admins monitor workspace-level participation and data volume.

<img alt="image" src={__img2} placeholder="blur" />

**Actions:**

* **Add Member** – Invite new users to the workspace.
* **Rename** – Edit the workspace name.
* **Manage Users** – Modify user roles or remove users from the workspace.

### Bases

The **Bases** section displays all databases across the organization, regardless of the workspace they belong to. Each base shows its name, the workspace it belongs to, and the number of members. This provides a centralized view to help admins maintain visibility over base creation and ownership.

<img alt="image" src={__img3} placeholder="blur" />

**Actions:**

* **Rename** – Update the base name.
* **Manage Users** – Add or remove collaborators, or change their roles.

### User Management

The **User Management** section lists all users who are part of the organization. Each member is shown with their **Org Role** (Org-Admin, Org-Creator, or Org-Viewer) and the date they joined. The Org Admin can manage organization membership, assign org-level roles, and provision workspace access.

<img alt="image" src={__img4} placeholder="blur" />

**Changing Org Roles:**

Click the role dropdown next to any member to change their org role. The available roles are:

* **Org-Viewer** – Can access workspaces and bases they are invited to, but cannot create new workspaces
* **Org-Creator** – Same as Org-Viewer, plus can create new workspaces within the organization. Cannot manage org membership.
* **Org-Admin** – Complete access to the organization, including member management, SSO, SCIM, domains, billing, and all org-level settings

The Org Admin's role is displayed as a distinct badge. See [Organization-level Roles](/docs/product-docs/roles-and-permissions#organization-level-roles) for details on org role constraints.

<img alt="image" src={__img5} placeholder="blur" />

**Actions menu:**

Click the **Actions** (three dots) menu beside a member to access:

* **Resend Invite E-mail** – Resend the invitation email to the user.
* **Copy Invite URL** – Copy the invitation link to clipboard.
* **Copy password reset URL** – Generate and copy a password reset link.
* **Remove User** – Remove the user from the organization. This also removes them from all workspaces, bases, and teams within the organization.

<img alt="image" src={__img6} placeholder="blur" />

Use the **+ Invite User** button to add new users to the organization.

For more details about organization-level roles, see [Organization-level Roles](/docs/product-docs/roles-and-permissions#organization-level-roles).

### Teams

The **Teams** section allows Org Admins to create and manage organization-level teams. Unlike workspace teams, org teams are available across all workspaces within the organization — they can be assigned roles in any workspace or base.

The teams list displays each team's name, badge, member count, creator, and an actions menu. Teams with sub-teams show an expand/collapse toggle. You can switch between tree view and flat view using the toggle buttons in the toolbar.

<img alt="image" src={__img7} placeholder="blur" />

Click the **+ New Team** button to create a new team. You can optionally select a parent team to create it as a sub-team.

<img alt="image" src={__img8} placeholder="blur" />

Click the **Actions** (three dots) menu beside a team to access:

* **Edit** – Open the team to manage its members and settings.
* **Add sub-team** – Create a nested sub-team under this team.
* **Move team** – Move the team under a different parent.
* **Delete team** – Remove the team from the organization.

<img alt="image" src={__img9} placeholder="blur" />

For detailed team management instructions, see [Organization Teams](/docs/product-docs/collaboration/teams#organization-teams).

### Single Sign-On (SSO)

The **Single Sign-On (SSO)** section allows organizations to configure centralized authentication for their users. SSO reduces the burden of managing individual credentials and ensures that user authentication adheres to enterprise security policies.

<img alt="image" src={__img10} placeholder="blur" />

Refer to the [SSO documentation](/docs/product-docs/account-settings/authentication#single-sign-on-sso) for detailed setup instructions.

### SCIM

The **SCIM** section allows Org Admins to configure SCIM v2.0 provisioning for automatic user and group management from an identity provider (IdP). When enabled, user onboarding, offboarding, and group membership changes in your IdP are automatically synced to NocoDB.

<img alt="image" src={__img11} placeholder="blur" />

From this section, you can:

* Enable or disable SCIM provisioning
* Configure the default org role for provisioned users
* Copy the SCIM endpoint URL and provisioning token for IdP configuration
* Regenerate the provisioning token if compromised
* Remove the SCIM configuration entirely

Refer to the [SCIM Provisioning documentation](/docs/product-docs/account-settings/authentication/scim) for detailed setup instructions.

### Settings

The **Settings** section allows administrators to define the visual identity and branding of their NocoDB instance.

<img alt="image" src={__img12} placeholder="blur" />

**Editable Fields:**

* **Organisation Name** – The display name for the organisation.
* **Organisation Logo** – Upload or update the logo for the organisation.

***

## Additional Notes

* Only users with the **Org Admin** role can access the Admin Panel. Org Creators and Org Viewers do not have access.
* Actions in the Admin Panel are scoped at the **organization level**, affecting all workspaces and bases.
* Any updates made in this panel reflect immediately and globally across your NocoDB deployment.


# Community Edition vs Enterprise Edition
URL: /docs/product-docs/cloud-enterprise-edition/community-vs-paid-editions

Complete overview of the differences between NocoDBs Community vs Enterprise Edition.

| **Section**         | **Sub-section**                                                                                                             | **Community Edition** | **Enterprise Edition** | **Comments**                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------- | ----------------------------------------- |
| **Usage**           | [Workspaces](/docs/product-docs/workspaces)                                                                                 | Only one              | Unlimited              |                                           |
|                     | [Bases](/docs/product-docs/bases)                                                                                           | Unlimited             | Unlimited              |                                           |
|                     | [Audit: Workspace-level](/docs/product-docs/workspaces/workspace-audit)                                                     | ❌                     | ✅                      |                                           |
|                     | [Base snapshots](/docs/product-docs/bases/snapshots)                                                                        | ❌                     | ✅                      |                                           |
| **Views**           | [Grid](/docs/product-docs/views/view-types/grid)                                                                            | ✅                     | ✅                      |                                           |
|                     | [Gallery](/docs/product-docs/views/view-types/gallery)                                                                      | ✅                     | ✅                      |                                           |
|                     | [Form](/docs/product-docs/views/view-types/form)                                                                            | ✅                     | ✅                      |                                           |
|                     | [Calendar](/docs/product-docs/views/view-types/calendar)                                                                    | ✅                     | ✅                      |                                           |
|                     | [Kanban](/docs/product-docs/views/view-types/kanban)                                                                        | ✅                     | ✅                      |                                           |
|                     | [Map](/docs/product-docs/views/view-types/map)                                                                              | ✅                     | ✅                      |                                           |
|                     | [Timeline](/docs/product-docs/views/view-types/timeline)                                                                    | ❌                     | ✅                      |                                           |
|                     | [List](/docs/product-docs/views/view-types/list)                                                                            | ❌                     | ✅                      |                                           |
| **Expanded Record** | [Field layout](/docs/product-docs/records/expand-record#field-mode)                                                         | ✅                     | ✅                      |                                           |
|                     | [Files layout](/docs/product-docs/records/expand-record#file-preview-mode--)                                                | ❌                     | ✅                      |                                           |
|                     | [Discussion layout](/docs/product-docs/records/expand-record#discussion-mode--)                                             | ❌                     | ✅                      |                                           |
| **Form View**       | [Background theme](/docs/product-docs/views/view-types/form#change-background-color)                                        | ✅                     | ✅                      |                                           |
|                     | Forms                                                                                                                       | ✅                     | ✅                      |                                           |
|                     | [Email responses](/docs/product-docs/views/view-types/form#post-form-submission-settings)                                   | ✅                     | ✅                      |                                           |
|                     | [Prefilled forms](/docs/product-docs/views/view-types/form#post-form-submission-settings)                                   | ✅                     | ✅                      |                                           |
|                     | Custom logo & banner                                                                                                        | ❌                     | ✅                      |                                           |
|                     | [Hide NocoDB branding](/docs/product-docs/views/view-types/form#hide-branding)                                              | ❌                     | ✅                      |                                           |
|                     | [Form redirection](/docs/product-docs/views/view-types/form#redirect-url)                                                   | ❌                     | ✅                      |                                           |
|                     | [Customize & shorten shared URL](/docs/product-docs/views/share-view#custom-url)                                            | ❌                     | ✅                      |                                           |
|                     | [Field input validation](/docs/product-docs/views/view-types/form#field-validations-)                                       | ❌                     | ✅                      |                                           |
|                     | [Conditional field display](/docs/product-docs/views/view-types/form#field-show-on-conditions)                              | ❌                     | ✅                      |                                           |
|                     | [Form scheduling](/docs/product-docs/views/view-types/form#form-scheduling-)                                                | ❌                     | ✅                      |                                           |
| **Fields**          | AI button (Action)                                                                                                          | ❌                     | ✅                      |                                           |
|                     | AI prompt (Field)                                                                                                           | ❌                     | ✅                      |                                           |
|                     | [Single line text](/docs/product-docs/fields/field-types/text-based/single-line-text)                                       | ✅                     | ✅                      |                                           |
|                     | [Long text](/docs/product-docs/fields/field-types/text-based/long-text)                                                     | ✅                     | ✅                      |                                           |
|                     | [Rich text](/docs/product-docs/fields/field-types/text-based/long-text)                                                     | ✅                     | ✅                      |                                           |
|                     | [URL](/docs/product-docs/fields/field-types/text-based/url)                                                                 | ✅                     | ✅                      |                                           |
|                     | [Email](/docs/product-docs/fields/field-types/text-based/email)                                                             | ✅                     | ✅                      |                                           |
|                     | [Phone](/docs/product-docs/fields/field-types/text-based/phonenumber)                                                       | ✅                     | ✅                      |                                           |
|                     | [Single select](/docs/product-docs/fields/field-types/select-based/single-select)                                           | ✅                     | ✅                      |                                           |
|                     | [Multiple select](/docs/product-docs/fields/field-types/select-based/multi-select)                                          | ✅                     | ✅                      |                                           |
|                     | [Number](/docs/product-docs/fields/field-types/numerical/number)                                                            | ✅                     | ✅                      |                                           |
|                     | [Decimal](/docs/product-docs/fields/field-types/numerical/decimal)                                                          | ✅                     | ✅                      |                                           |
|                     | [Currency](/docs/product-docs/fields/field-types/numerical/currency)                                                        | ✅                     | ✅                      |                                           |
|                     | [Duration](/docs/product-docs/fields/field-types/date-time-based/duration)                                                  | ✅                     | ✅                      |                                           |
|                     | [Percent](/docs/product-docs/fields/field-types/numerical/percent)                                                          | ✅                     | ✅                      |                                           |
|                     | [Progress bar (Percent)](/docs/product-docs/fields/field-types/numerical/percent)                                           | ✅                     | ✅                      |                                           |
|                     | [Date](/docs/product-docs/fields/field-types/date-time-based/date)                                                          | ✅                     | ✅                      |                                           |
|                     | [Time](/docs/product-docs/fields/field-types/date-time-based/time)                                                          | ✅                     | ✅                      |                                           |
|                     | [DateTime](/docs/product-docs/fields/field-types/date-time-based/date-time)                                                 | ✅                     | ✅                      |                                           |
|                     | Year                                                                                                                        | ✅                     | ✅                      |                                           |
|                     | [Links](/docs/product-docs/fields/field-types/links-based/links)                                                            | ✅                     | ✅                      |                                           |
|                     | [Link to another record](/docs/product-docs/fields/field-types/links-based/links)                                           | ✅                     | ✅                      |                                           |
|                     | [Lookup](/docs/product-docs/fields/field-types/links-based/lookup)                                                          | ✅                     | ✅                      |                                           |
|                     | [Rollup](/docs/product-docs/fields/field-types/links-based/rollup)                                                          | ✅                     | ✅                      |                                           |
|                     | [Attachment](/docs/product-docs/fields/field-types/custom-types/attachment)                                                 | ✅                     | ✅                      |                                           |
|                     | [Rating](/docs/product-docs/fields/field-types/custom-types/rating)                                                         | ✅                     | ✅                      |                                           |
|                     | [Checkbox](/docs/product-docs/fields/field-types/custom-types/checkbox)                                                     | ✅                     | ✅                      |                                           |
|                     | [User](/docs/product-docs/fields/field-types/user-based/user)                                                               | ✅                     | ✅                      |                                           |
|                     | [QR code](/docs/product-docs/fields/field-types/custom-types/QR-code)                                                       | ✅                     | ✅                      |                                           |
|                     | [Barcode](/docs/product-docs/fields/field-types/custom-types/barcode)                                                       | ✅                     | ✅                      |                                           |
|                     | [Button](/docs/product-docs/fields/field-types/custom-types/button)                                                         | ✅                     | ✅                      |                                           |
|                     | [Formula](/docs/product-docs/fields/field-types/formula/formula)                                                            | ✅                     | ✅                      |                                           |
|                     | [Created at](/docs/product-docs/fields/field-types/date-time-based/created-time)                                            | ✅                     | ✅                      |                                           |
|                     | [Last modified at](/docs/product-docs/fields/field-types/date-time-based/last-modified-time)                                | ✅                     | ✅                      |                                           |
|                     | [Created by](/docs/product-docs/fields/field-types/user-based/created-by)                                                   | ✅                     | ✅                      |                                           |
|                     | [Last modified by](/docs/product-docs/fields/field-types/user-based/last-modified-by)                                       | ✅                     | ✅                      |                                           |
|                     | [UUID](/docs/product-docs/fields/field-types/identifier-types/uuid)                                                         | ❌                     | ✅                      | PostgreSQL only                           |
|                     | [Colour](/docs/product-docs/fields/field-types/custom-types/colour)                                                         | ❌                     | ✅                      |                                           |
|                     | [Auto-number](/docs/product-docs/fields/field-types/identifier-types/auto-number)                                           | ❌                     | ✅                      |                                           |
| **Features**        | [Filter](/docs/product-docs/table-operations/filter)                                                                        | ✅                     | ✅                      |                                           |
|                     | [Filter groups](/docs/product-docs/table-operations/filter#group-filters)                                                   | ✅                     | ✅                      |                                           |
|                     | [Pinned filters](/docs/product-docs/table-operations/filter#pinned-filters-)                                                | ❌                     | ✅                      |                                           |
|                     | [Toggle filters](/docs/product-docs/table-operations/filter#toggle-filters-)                                                | ❌                     | ✅                      |                                           |
|                     | [AI filters](/docs/product-docs/noco-ai/create-filter)                                                                      | ❌                     | ✅                      |                                           |
|                     | [Sort](/docs/product-docs/table-operations/sort)                                                                            | ✅                     | ✅                      |                                           |
|                     | [Group by](/docs/product-docs/table-operations/group-by)                                                                    | ✅                     | ✅                      |                                           |
|                     | [Row height](/docs/product-docs/table-operations/row-height)                                                                | ✅                     | ✅                      |                                           |
|                     | [Footer aggregations](/docs/product-docs/fields/field-summary-footer)                                                       | ✅                     | ✅                      |                                           |
|                     | [Group by aggregations](/docs/product-docs/table-operations/group-by#group-level-field-aggregations)                        | ✅                     | ✅                      |                                           |
|                     | Table & field description                                                                                                   | ✅                     | ✅                      |                                           |
|                     | [Unique fields](/docs/product-docs/fields#unique-fields-)                                                                   | ❌                     | ✅                      |                                           |
|                     | Undo / Redo                                                                                                                 | ✅                     | ✅                      |                                           |
|                     | [Quick navigation (Cmd + K)](/docs/product-docs/getting-started/keyboard-shortcuts#quick-actions)                           | ✅                     | ✅                      |                                           |
|                     | Search                                                                                                                      | Limited               | Limited                |                                           |
|                     | Templates                                                                                                                   | Limited               | Coming soon            |                                           |
|                     | [Record templates](/docs/product-docs/records/record-templates)                                                             | ❌                     | ✅                      |                                           |
|                     | [API snippets](/docs/product-docs/table-details#api-snippet)                                                                | ✅                     | ✅                      |                                           |
|                     | [Field manager (bulk edit)](/docs/product-docs/table-details#fields)                                                        | ✅                     | ✅                      |                                           |
|                     | Filter, Sort & Group re-order                                                                                               | ❌                     | ✅                      |                                           |
|                     | [Base relationship diagram (ERD)](/docs/product-docs/table-details)                                                         | ✅                     | ✅                      |                                           |
|                     | [Link field : Limit to view](/docs/product-docs/fields/field-types/links-based/links#limit-by-view)                         | ✅                     | ✅                      |                                           |
|                     | [Link field : Limit by filter](/docs/product-docs/fields/field-types/links-based/links#limit-by-filter-)                    | ❌                     | ✅                      |                                           |
|                     | [Conditional lookup](/docs/product-docs/fields/field-types/links-based/lookup#conditional-lookup-)                          | ❌                     | ✅                      |                                           |
|                     | [Conditional rollup](/docs/product-docs/fields/field-types/links-based/rollup#conditional-rollup-)                          | ❌                     | ✅                      |                                           |
|                     | [Conditional button fields](/docs/product-docs/fields/field-types/custom-types/button#conditional-buttons-)                 | ❌                     | ✅                      |                                           |
|                     | [Locked views](/docs/product-docs/views#locked-views)                                                                       | ✅                     | ✅                      |                                           |
|                     | [Personal views](/docs/product-docs/views#personal-views-)                                                                  | ❌                     | ✅                      |                                           |
|                     | [View sections](/docs/product-docs/views/view-sections)                                                                     | ❌                     | ✅                      |                                           |
|                     | [Calendar view with end date](/docs/product-docs/views/view-types/calendar#configuring-date-range)                          | ❌                     | ✅                      |                                           |
|                     | [Date dependencies](/docs/product-docs/tables/date-dependency)                                                              | ❌                     | ✅                      |                                           |
|                     | [Copy another view config](/docs/product-docs/views/actions-on-view#copy-another-views-configuration-)                      | ❌                     | ✅                      |                                           |
|                     | [Hide field labels](/docs/product-docs/table-operations/field-operations#hide-field-labels-)                                | ❌                     | ✅                      | Applicable for Gallery & Kanban views     |
|                     | [Row colouring](/docs/product-docs/table-operations/record-colouring)                                                       | ❌                     | ✅                      |                                           |
|                     | [Cell colouring](/docs/product-docs/table-operations/record-colouring#cell-colouring)                                       | ❌                     | ✅                      |                                           |
|                     | [Dashboards](/docs/product-docs/dashboards)                                                                                 | ❌                     | ✅                      |                                           |
|                     | [Private Bases](/docs/product-docs/bases/private-base)                                                                      | ❌                     | ✅                      |                                           |
|                     | [Extensions](/docs/product-docs/extensions)                                                                                 | ❌                     | ✅                      |                                           |
|                     | [MCP Server (desktop)](/docs/product-docs/mcp)                                                                              | ✅                     | ✅                      | Desktop apps for Claude, Cursor, Windsurf |
|                     | [MCP OAuth](/docs/product-docs/mcp)                                                                                         | ❌                     | ✅                      | ChatGPT, Claude                           |
| **Extensions**      | [Bulk update](/docs/product-docs/extensions/bulk-update)                                                                    | ❌                     | ✅                      |                                           |
|                     | [Data exporter](/docs/product-docs/extensions/data-exporter)                                                                | ❌                     | ✅                      |                                           |
|                     | [URL preview](/docs/product-docs/extensions/url-preview)                                                                    | ❌                     | ✅                      |                                           |
|                     | [World clock](/docs/product-docs/extensions/world-clock)                                                                    | ❌                     | ✅                      |                                           |
|                     | [Upload CSV with upsert](/docs/product-docs/extensions/upload-data-from-csv)                                                | ❌                     | ✅                      |                                           |
|                     | [Org chart](/docs/product-docs/extensions/org-chart)                                                                        | ❌                     | ✅                      |                                           |
|                     | [Page designer](/docs/product-docs/extensions/page-designer)                                                                | ❌                     | ✅                      |                                           |
|                     | [De-duplicate](/docs/product-docs/extensions/dedupe)                                                                        | ❌                     | ✅                      |                                           |
| **Import/Export**   | [Export: CSV, XLS](/docs/product-docs/table-operations/download#download-data)                                              | ✅                     | ✅                      |                                           |
|                     | [Import to new table: CSV, XLS, JSON](/docs/product-docs/tables/create-table-via-import#import-table-from-csv--excel--json) | ✅                     | ✅                      |                                           |
|                     | [Import: Airtable](/docs/product-docs/bases/import-base-from-airtable)                                                      | ✅                     | ✅                      |                                           |
|                     | [Import to existing table](/docs/product-docs/tables/import-data-into-existing-table)                                       | ✅                     | ✅                      |                                           |
| **Developers**      | [Core REST API](/docs/product-docs/developer-resources/rest-apis)                                                           | ✅                     | ✅                      |                                           |
|                     | [Advanced REST API](/docs/product-docs/developer-resources/rest-apis)                                                       | ❌                     | ✅                      | View, Script & Collaboration APIs         |
|                     | [Swagger specification](/docs/product-docs/developer-resources/rest-apis/accessing-apis#swagger-ui)                         | ✅                     | ✅                      |                                           |
|                     | [API tokens](/docs/product-docs/account-settings/api-tokens)                                                                | ✅                     | ✅                      |                                           |
|                     | [Fine-grained API tokens](/docs/product-docs/account-settings/api-tokens#fine-grained-api-tokens)                           | ❌                     | ✅                      |                                           |
| **Public Sharing**  | [Public view sharing](/docs/product-docs/views/share-view)                                                                  | ✅                     | ✅                      |                                           |
|                     | [Public view sharing with password](/docs/product-docs/views/share-view#password-protection)                                | ✅                     | ✅                      |                                           |
|                     | [Public view custom URL](/docs/product-docs/views/share-view#custom-url)                                                    | ❌                     | ✅                      |                                           |
|                     | Public base custom URL                                                                                                      | ❌                     | ✅                      |                                           |
| **Automations**     | [Webhooks](/docs/product-docs/automation/webhook)                                                                           | ✅                     | ✅                      |                                           |
|                     | [Webhooks with conditions](/docs/product-docs/automation/webhook/create-webhook#webhook-with-conditions)                    | ✅                     | ✅                      |                                           |
|                     | [Webhooks with custom payload](/docs/product-docs/automation/webhook/create-webhook#webhook-with-custom-payload)            | ✅                     | ✅                      |                                           |
|                     | [Webhooks on specific field changes](/docs/product-docs/automation/webhook/create-webhook#webhook-on-field-changes-)        | ❌                     | ✅                      |                                           |
|                     | [Webhooks view & field specific triggers](/docs/product-docs/automation/webhook/create-webhook#trigger-source-and-event)    | ❌                     | ✅                      |                                           |
|                     | [Webhook logs](/docs/product-docs/automation/webhook/actions-on-webhook#webhook-logs-)                                      | ❌                     | ✅                      |                                           |
|                     | [Scripts (Custom JS code)](/docs/scripts)                                                                                   | ❌                     | ✅                      |                                           |
|                     | [Run scripts via Button field](/docs/product-docs/fields/field-types/custom-types/button)                                   | ❌                     | ✅                      |                                           |
| **Workflows**       | [Workflows](/docs/workflows)                                                                                                | ❌                     | ✅                      |                                           |
| **Collaboration**   | [Workspace collaboration](/docs/product-docs/workspaces/workspace-collaboration)                                            | ✅                     | ✅                      | Community Edition supports 1 workspace    |
|                     | [Base collaboration](/docs/product-docs/bases/base-collaboration)                                                           | ✅                     | ✅                      |                                           |
|                     | [Role-based permissions](/docs/product-docs/roles-and-permissions)                                                          | ✅                     | ✅                      |                                           |
|                     | [Record-level security](/docs/product-docs/roles-and-permissions/record-level-security)                                     | ❌                     | ✅                      |                                           |
|                     | [Table permissions](/docs/product-docs/roles-and-permissions/table-permissions)                                             | ❌                     | ✅                      |                                           |
|                     | [Field permissions](/docs/product-docs/roles-and-permissions/field-permissions)                                             | ❌                     | ✅                      |                                           |
|                     | Notifications                                                                                                               | ✅                     | ✅                      |                                           |
|                     | [Row comments](/docs/product-docs/records/expand-record#record-comment)                                                     | ✅                     | ✅                      |                                           |
|                     | Row comments resolve                                                                                                        | ❌                     | ✅                      |                                           |
|                     | @Mentions in comments fields                                                                                                | ❌                     | ✅                      |                                           |
|                     | Realtime collaboration                                                                                                      | ❌                     | ✅                      |                                           |
|                     | [Teams (workspace-level)](/docs/product-docs/collaboration/teams)                                                           | ❌                     | ✅                      |                                           |
|                     | [Organization roles](/docs/product-docs/roles-and-permissions#organization-level-roles)                                     | ✅                     | ✅                      |                                           |
|                     | [Organization teams](/docs/product-docs/collaboration/teams#organization-teams)                                             | ❌                     | ✅                      |                                           |
| **Integrations**    | PostgreSQL                                                                                                                  | ✅                     | ✅                      |                                           |
|                     | MySQL                                                                                                                       | ✅                     | ✅                      |                                           |
|                     | SQLite                                                                                                                      | ✅                     | ❌                      |                                           |
|                     | OpenAI                                                                                                                      | ❌                     | ✅                      |                                           |
|                     | Claude                                                                                                                      | ❌                     | ✅                      |                                           |
|                     | Ollama                                                                                                                      | ❌                     | ✅                      |                                           |
|                     | Groq                                                                                                                        | ❌                     | ✅                      |                                           |
|                     | Private integrations                                                                                                        | ❌                     | ✅                      |                                           |
| **NocoDocs**        | [Documents](/docs/noco-docs)                                                                                                | ❌                     | ✅                      |                                           |
| **Sync**            | [Sync](/docs/product-docs/noco-sync)                                                                                        | ❌                     | ✅                      |                                           |
| **Admin**           | [Admin panel](/docs/product-docs/cloud-enterprise-edition/admin-panel)                                                      | ❌                     | ✅                      |                                           |
|                     | [SSO](/docs/product-docs/account-settings/authentication#single-sign-on-sso)                                                | ❌                     | ✅                      |                                           |
|                     | [Audit logs](/docs/product-docs/workspaces/workspace-audit)                                                                 | ❌                     | ✅                      |                                           |
|                     | Co-branding                                                                                                                 | ❌                     | ✅                      |                                           |
|                     | 2FA                                                                                                                         | ❌                     | Coming soon            | Q2 2026                                   |
|                     | [SCIM](/docs/product-docs/account-settings/authentication/scim)                                                             | ❌                     | ✅                      |                                           |
| **Support**         | Community support                                                                                                           | ✅                     | ✅                      |                                           |
|                     | Priority support                                                                                                            | ❌                     | ✅                      |                                           |
|                     | SLA-based support                                                                                                           | ❌                     | ✅                      |                                           |

***


# OSS to Enterprise Migration
URL: /docs/product-docs/cloud-enterprise-edition/oss-to-enterprise-migration

















This guide outlines the steps to migrate from the OSS version of NocoDB to the Enterprise Edition. Migration is supported for both **on-prem** and **cloud** deployments.

## Prerequisites

Before you begin, ensure the following:

* The OSS version of NocoDB (`Instance-1`) is accessible.
* You have access to the Enterprise Edition of NocoDB (`Instance-2`) — either self-hosted (on-prem) or provisioned via a cloud subscription on NocoDB.
  * If using the self-hosted (on-prem) Enterprise Edition, it must be running version v0.262.2 or higher.
* You have administrative access to both instances.

***

## Steps

The migration process consists of two parts:

### Part 1: Generate Migration URL

On the Enterprise Edition (**Instance-2**)

1. On the base homepage, click **Import Data**.
2. Choose **NocoDB** as the data source.
3. Click **Generate & Copy URL**.
4. The URL will be copied to your clipboard. The modal will now enter **listening mode**, waiting for a migration request from the OSS instance.

<img alt="Generate Migration URL" src={__img0} placeholder="blur" />
<img alt="Generate Migration URL" src={__img1} placeholder="blur" />
<img alt="Generate Migration URL" src={__img2} placeholder="blur" />
<img alt="Generate Migration URL" src={__img3} placeholder="blur" />

***

### Part 2: Migrate Base from Self hosted instance

On the OSS instance (**Instance-1**):

1. Open the base context menu and select **Settings**.
2. Navigate to the **Migrate** tab.
3. Paste the migration URL copied from Instance-2.
4. Click **Migrate**.

<img alt="Migrate Base from OSS" src={__img4} placeholder="blur" />
<img alt="Migrate Base from OSS" src={__img5} placeholder="blur" />

Once the migration is triggered, a status popup will appear on the OSS instance (Instance-1). Upon successful completion, a confirmation message will be displayed on the Enterprise Edition (Instance-2).

Click **Go to Base** to access the migrated base.

<img alt="Migration Complete" src={__img6} placeholder="blur" />

***


# NocoDB Pricing Guide
URL: /docs/product-docs/cloud-enterprise-edition/understanding-pricing

Transparent, Scalable, and Business-Friendly

## Executive Summary

NocoDB's pricing model is designed with growing businesses in mind. Our unique "**pay for 9, get unlimited**" approach means you'll never pay for more than 9 editor seats, regardless of your team size. This creates predictable costs and exceptional value as your organization scales.

**Key Benefits:**

* **Predictable costs** - Your bill caps at 9 editor seats automatically
* **Unlimited scale** - Add as many team members as needed without additional cost
* **Immediate value** - Start small and grow without pricing penalties
* **No surprises** - Transparent billing with no hidden fees

***

## Understanding User Roles and Billing

### Billable vs. Non-Billable Users

**Billable Users (Editors):** Team members who can create, modify, or delete data

* **Owner:** Full administrative control
* **Creator:** Can create new bases and modify data
* **Editor:** Can modify existing data and records

**Non-Billable Users (Always Free):** Team members with view-only or limited access

* **Commenter:** Can view records and add comments, but cannot edit data
* **Viewer:** Read-only access to data and dashboards

💡 **Pro Tip:** Maximize your investment by assigning Commenter or Viewer roles to stakeholders who only need to review data, not edit it.

***

## The "Pay for 9, Get Unlimited" Model

**How It Works**

1. **You pay for only the first 9 editor seats** - regardless of your actual number of editors
2. **Every editor beyond the 9th is completely free** - no limits, no restrictions
3. **Start with any number** - begin with 1-2 users and grow naturally
4. **Automatic billing cap** - NocoDB stops charging after the 9th editor

### Real-World Example

**Scenario:** Your company has 45 total users across different departments

* **25 editors** (Sales, Operations, Product teams who need to update data)
* **20 commenters/viewers** (Executives, stakeholders who review reports)

**What you pay for:**

* Only 9 editor seats (not all 25 editors)
* 0 seats for commenters/viewers

**Your cost:** Same as a 9-person team, but with 45 people using the platform.

***

## Pricing Plans Comparison

### Plus Plan

**Price:** $12 per editor/month (Annual)

**Best for:** Growing teams and departments

| Team Size (Editors) | Monthly Cost | Annual Cost | Cost Per User/Month |
| ------------------- | ------------ | ----------- | ------------------- |
| 5 editors           | $60          | $720        | **$12.00**          |
| 10 editors          | $108         | $1,296      | **$10.80**          |
| 25 editors          | $108         | $1,296      | **$4.32**           |
| 50 editors          | $108         | $1,296      | **$2.16**           |
| 100 editors         | $108         | $1,296      | **$1.08**           |

### Business Plan

**Price:** $24 per editor/month (Annual)

**Best for:** Enterprise teams requiring advanced features

| Team Size (Editors) | Monthly Cost | Annual Cost | Cost Per User/Month |
| ------------------- | ------------ | ----------- | ------------------- |
| 5 editors           | $120         | $1,440      | **$24.00**          |
| 10 editors          | $216         | $2,592      | **$21.60**          |
| 25 editors          | $216         | $2,592      | **$8.64**           |
| 50 editors          | $216         | $2,592      | **$4.32**           |
| 100 editors         | $216         | $2,592      | **$2.16**           |

***

## ROI Calculator

**Traditional Per-Seat Pricing vs. NocoDB**

Example: 40-person team needing editing access

| Pricing Model               | Monthly Cost | Annual Cost | Savings with NocoDB |
| --------------------------- | ------------ | ----------- | ------------------- |
| Traditional SaaS ($15/user) | $600         | $7,200      | -                   |
| **NocoDB Plus**             | $108         | $1,296      | **$5,904 saved**    |
| **NocoDB Business**         | $216         | $2,592      | **$4,608 saved**    |

*The larger your team, the greater your savings.*

## Changing plans

Note that, you can change your plan at any time from the billing dashboard. Upgrades take effect immediately, and you'll be billed on a prorated basis. Downgrades take effect at the end of your current billing cycle.

<Callout type="warning">
  Please ensure your workspace usage fits within the limits of the downgraded plan (record limits, storage, etc.).
</Callout>

The detailed steps for change plan are captured [here](/docs/product-docs/workspaces/billing#change-your-plan).

## Access your invoices

To view and download your invoices, go to the **Billing** tab in your workspace settings. You can access past invoices, their statuses, and download them for your records. Find more details [here](/docs/product-docs/workspaces/billing#download-invoices).

***

## Cancel your plan

You can cancel your paid plan anytime from the billing dashboard. Upon cancellation, your workspace remains on the current plan until the end of the billing period. After that, it automatically moves to the Free plan, and no further charges are made.

<Callout type="warning">
  Before canceling, ensure you’ve backed up any data or features available only in paid plans, as these may become unavailable after the downgrade.
</Callout>

Follow the detailed steps [here](/docs/product-docs/workspaces/billing#cancel-plan).

***

## Frequently Asked Questions

### Can I change user roles after setup?

Yes, you can promote Commenters to Editors or vice versa at any time. Billing adjusts automatically based on your current editor count (up to 9 paid seats).

### What happens if I temporarily need more than 9 editors?

Nothing changes with your billing. Add as many editors as needed - you'll still only pay for 9 seats.

### Do I need to commit to 9 seats upfront?

No. Start with the number of editors you need today. You'll only pay for active editor seats until you reach 9.

### How does annual vs. monthly billing work?

Annual billing provides the pricing shown above and helps you save 20% compared to monthly billing.

### Questions About Pricing?

Our sales team is here to help you understand how NocoDB's pricing model works for your specific situation. **[Book a consultation call →](https://cal.com/nocodb/sales/)**

***


# Base collaboration
URL: /docs/product-docs/collaboration/base-collaboration

This article explains how to invite members or teams to your base, manage their roles, and remove them when needed.













<Callout type="info">
  A comprehensive guide regarding roles and permissions can be accessed 

  [here](/docs/product-docs/roles-and-permissions)
</Callout>

<Callout type="info">
  Teams feature availability: 

  **Business**

   plan onwards in cloud and On-premise 

  **Enterprise**

   edition
</Callout>

## Invite Members to Base

Base-level member management allows you to control granular access to specific bases within your workspace. You can invite individual members directly to a base with specific role assignments.

1. Navigate to the **Overview** > **Members** tab within your base.
2. Click **Add Members**.
3. Enter one or more email addresses (comma-separated).
4. Select a role for the invited member(s) from the dropdown menu.
5. Click **Invite to Base**.

<Callout type="info">
  You can only assign roles that are at most equal to your own role on the base.
</Callout>

<Callout type="info">
  You can invite multiple members simultaneously by entering their email addresses separated by commas.
</Callout>

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

Members added to a workspace inherit the role assigned at the workspace level, unless a specific role is configured at the base level. Alternatively, you can invite users directly to a base with restricted workspace access. This allows you to grant access to a single base without exposing other workspace data — ideal for collaborating with external partners, clients, or temporary contributors in a controlled manner.

## Invite Teams to Base ☁

You can assign entire teams to a base for streamlined collaboration. Teams inherit the base-level role assigned to them, making it easier to manage access for department-wide or functional group permissions.

1. Navigate to the **Overview** > **Members** tab within your base.
2. Click on the **Add Teams** button.
3. From the dropdown, select one or multiple teams to add to the base. Teams already added to the base will be indicated as disabled in the dropdown.
4. Choose the appropriate base-level role from the dropdown menu. Note that:
   * Similar to individual members, you can only assign roles that are at most equal to your own role on the base.
   * Teams can't be assigned the **Owner** role at the base level.
5. Click on the **Add Teams** button to complete the process.

<Callout type="info">
  When a team is invited to the base, all users under that team inherit the assigned base-level role unless overridden by an individual explicit member role.
</Callout>

<img alt="image" src={__img2} placeholder="blur" />
<img alt="image" src={__img3} placeholder="blur" />

To learn more about creating and managing teams, refer to the [Teams documentation](/docs/product-docs/collaboration/teams).

Teams added to a workspace inherit the role assigned at the workspace level, unless a different role is configured at the base level. Alternatively, you can invite teams directly to a base with restricted workspace access. This allows team members to collaborate on a specific base without access to other workspace data — ideal for engaging external teams, partner organizations, or temporary project groups securely and efficiently.

## List Base Members and Teams

The `Members` tab displays all users and teams that have access to the base.

* Individual members appear with their email addresses and assigned base role.
* Teams are listed with their name, member count, and assigned base role.

<img alt="image" src={__img4} placeholder="blur" />

Inherited roles from workspace-level are displayed with `workspace` suffix to indicate their origin.

## Modify Roles for Members or Teams

Access permissions for both members and teams can be updated directly from the `Members` tab.

1. Click on the role dropdown next to the member or team.
2. Select a new role from the list of available options.
3. The role change takes effect immediately.

<img alt="image" src={__img5} placeholder="blur" />

<Callout type="info">
  You can only assign roles that are at most equal to your own role on the base. Teams cannot be assigned the 

  **Owner**

   role at the base level.
</Callout>

Learn more about [roles and permissions](/docs/product-docs/roles-and-permissions).

## Role Precedence

When a user has multiple role assignments through both team and individual access at the base level, NocoDB resolves the final permission using a clear precedence order.

* Individual explicit role takes precedence over team-assigned role.
* Base-level roles override workspace-level roles.
* In case of multiple team roles, the **highest** permission applies.

Learn more about [roles and permissions](/docs/product-docs/collaboration/teams#effective-role-resolution).

## Remove or Revoke Base Access

There are two ways to manage member or team access to a base:

### Deny Access

To prevent a user or team from accessing the base:

* Click on the role dropdown next to the member or team entry.
* Select `No Access` from the available roles.

The member or team will be blocked from accessing this base, regardless of their workspace or team-level permissions.

### Revoke Explicit Assignment

To remove an explicit base-level role assignment and allow the user to inherit their workspace or team-level role:

* Click on the role dropdown next to the member or team entry.
* Select `Inherit` from the available roles.

The member or team will now access the base based on their workspace-level or team-level permissions, rather than an explicit base-level assignment.

<Callout type="info">
  Use 

  **No Access**

   to explicitly block someone from a base. Use 

  **Inherit**

   to remove the base-level assignment and fall back to workspace or team inheritance.
</Callout>

## Best Practice

* Use base-level permissions to restrict access to sensitive data while maintaining broader workspace access.
* Assign teams to bases for departments or functional groups to manage access efficiently without individual invitations.
* Start by inviting teams to bases when possible, then add individual members for exceptions.
* Regularly audit base member lists to ensure access remains appropriate as team compositions change.

Learn more [here](/docs/product-docs/collaboration/teams#best-practices).

***


# Collaboration
URL: /docs/product-docs/collaboration

This article explains various collaboration features that NocoDB offers.

At NocoDB, teamwork is at the core of what we do. Our collaboration features make it easy to share work, assign tasks, and communicate effectively with your team.

In this section, we’ll explore the different collaboration tools available in NocoDB.

[Workspace collaboration](/docs/product-docs/collaboration/workspace-collaboration)\
[Base collaboration](/docs/product-docs/collaboration/base-collaboration)\
[Teams](/docs/product-docs/collaboration/teams)\
[Share base](/docs/product-docs/collaboration/share-base)\
[Share view](/docs/product-docs/collaboration/share-view)


# Notifications
URL: /docs/product-docs/collaboration/notifications

This article explains specifics of Notifications.



The Notifications feature in NocoDB helps you stay informed about important updates, invitations, and activities within your bases and workspaces. This feature allows you to easily manage and keep track of all your notifications in one place.

<img alt="Notifications" src={__img0} placeholder="blur" />

## Notification Center

The Notification Center is accessible via the bell icon located at the bottom of the sidebar in your NocoDB interface. Clicking on this icon opens a menu that displays all your recent notifications. Whenever someone mentions you in the comments or invites you to a workspace, you will receive a notification.

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/U5ZYVlpOGN8?start=58" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

<Callout type="info">
  A red dot on the bell icon indicates that you have new, unread notifications. This visual cue helps you quickly identify when there's something new that needs your attention
</Callout>

### Unread and Read Notifications

Notifications are categorized into two sections:

1. **Unread**: Displays all notifications that you haven't viewed yet.
2. **Read**: Displays notifications that you have already seen.

### Mark as Read/Unread

You can easily change the status of your notifications:

1. **Mark as Read**: Hover over any unread notification and click the checkmark to mark it as read. Alternatively, you can click the "Mark all as read" option at the top of the menu to mark all notifications as read.
2. **Mark as Unread**: If you need to revisit a notification later, simply hover over a read notification, click on the `⋮` menu, and select 'Mark as Unread'. This will move it back to the 'Unread' section.

### Delete Notifications

Read notifications can be deleted individually by clicking on the `⋮` menu and selecting 'Delete'. Once deleted, the notification will no longer appear in your list, ensuring that you only keep relevant information.

## Related Articles

* [Workspace Collaboration](/docs/product-docs/collaboration/workspace-collaboration)
* [Base Collaboration](/docs/product-docs/collaboration/base-collaboration)
* [Expanded Records](/docs/product-docs/records/expand-record)


# In Community Edition
URL: /docs/product-docs/collaboration/oss-specific-details

This article explains specifics of User management in Community Edition.

Community Edition of NocoDB includes a default workspace, and it does not allow the creation of additional workspaces. And hence, the user management on community edition is different from Cloud hosted solutions. This article details the specifics of User management in the Community Edition.


# Share base
URL: /docs/product-docs/collaboration/share-base

Procedures to share a base publicly & generating embedded iframe















To share a base, follow the steps below:

1. Navigate to the top right corner of the top navigation bar and click on the `Share` button.
2. In the `Shared base` section, toggle the switch to `Enable public access` in order to activate the shared base feature.
3. The generated link for the shared base will be displayed above and can be utilized to share this base with others. To copy the URL, simply click on the `Copy Link` option.

<img alt="Share base" src={__img0} placeholder="blur" />

<img alt="Share base" src={__img1} placeholder="blur" />

## Copy base

The `Copy base` feature allows users to create a copy of the base (import base) into their own Workspace. This feature is also useful for users who wish to utilize a base as a template for future bases. To copy a base, follow the steps below:

1. Access shared base URL that you wish to copy.
2. Click on the `Copy base` button located in the top right corner of the toolbar.
3. A modal will appear, prompting you to select the Workspace you wish to copy the base to. Select the desired Workspace
4. Configure if you wish to copy the base with or without data / views.
5. Click on the `Copy base` button to complete the process.

<img alt="Copy base" src={__img2} placeholder="blur" />
<img alt="Copy base" src={__img3} placeholder="blur" />

## Modify Share base

Amending the `Share base` setting will render the previously generated `Share base` link invalid and generate a new link in its place.
Here are the steps to modify it:

1. Click on the `Share` button located in the top right corner of the toolbar.
2. Toggle the option labeled `Enable public access` to deactivate the base share.
3. Toggle the same option, `Enable public access,` to reactivate the base share, subsequently generating a new link.

<img alt="Enable public access" src={__img4} placeholder="blur" />

## Disable Share base

Disabling `Share base` will render the previously generated `Share base` link invalid
Here are the steps to disable it:

1. Click on the 'Share' button located in the top right corner of the toolbar.
2. Toggle the option labeled `Enable public access` to deactivate the base share.

<img alt="Enable public access" src={__img5} placeholder="blur" />

## Share base Access Permissions

Users with the shared base link will have **read-only** access to the base data.

## Embeddable Frame

The NocoDB interface can be seamlessly integrated into existing applications through the utilization of the [HTML IFRAME](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) attribute. This feature empowers users to embed the NocoDB interface into their applications, allowing for a unified user experience. To generate the embeddable HTML code, follow these steps:

**To Generate Embeddable HTML Code:**

1. Click the `Share` button located in the top right corner of the toolbar.
2. Within the `Shared base link` tab, select the button to copy the `Embeddable HTML code` to your clipboard.

<img alt="Share base iFrame" src={__img6} placeholder="blur" />

Example:

```html
<iframe
        class="nc-embed"
        src="https://nocodb-nocodb-rsyir.ondigitalocean.app/dashboard/#/nc/base/e3bba9df-4fc1-4d11-b7ce-41c4a3ad6810?embed"
        frameBorder="0"
        width="100%"
        height="700"
        style="background: transparent; border: 1px solid #ddd"
>
</iframe>
```

### Embed into application's HTML Body

Sample code with embedded iframe generated above

```html
<!DOCTYPE html>
<html>
<body>
<iframe
        class="nc-embed"
        src="http://localhost:3000/#/nc/base/7d4b551c-b5e0-41c9-a87b-f3984c21d2c7?embed"
        frameBorder="0"
        width="100%"
        height="700"
        style="background: transparent; "
></iframe>
</body>
</html>
```


# Share view
URL: /docs/product-docs/collaboration/share-view

Procedures to share a view publicly















## Generate Share View

1. Click `Share` button on the top right of the toolbar
2. Toggle `Enable public viewing` to create shared view link
3. Click `Copy` button to copy the link to clipboard

<img alt="share button" src={__img0} placeholder="blur" />

<img alt="shared view" src={__img1} placeholder="blur" />

### Share view options

#### Password protection

You can enable `Restrict access with a password` if you want a password-protected view

<img alt="password protection" src={__img2} placeholder="blur" />

#### Download options

You can toggle `Allow Download` button to enable or disable download CSV/XLSX options in the shared view link

<img alt="download options" src={__img3} placeholder="blur" />

### Share Form View Options

Form view has additional customizations for shared view. You can enable/disable the following options for shared form view:

1. `Survey mode`: This option when enabled, will display the form in survey mode.
2. `RTL Orientation`: This option when enabled, will display the form in RTL orientation.
3. `Themes`: You can select a theme for the form from the dropdown.
   <img alt="form view options" src={__img4} placeholder="blur" />

## Access Share View

To access the shared view, please follow the steps below:
Click on the `Shared View URL`. If the URL is password-protected, you will be prompted to enter the password to unlock it. Please input the required password to proceed.

<img alt="password modal" src={__img5} placeholder="blur" />

Once the password is successfully entered and authenticated, you will gain access to the shared view.
In the event that the URL is not password-protected, you will be directed to the shared view directly, without the need for a password.

<img alt="share-view" src={__img6} placeholder="blur" />

Users with the shared view link can only view the data and cannot make any changes to the view or its content. Records and fields in the shared view will be updated in real-time as changes are made to the original view. Users accessing shared view can apply filters and sort records as per their requirements.

:::info
Note that, filters & sorts applied to shared view will not be persisted. These filters & sorts will be reset when the shared view is accessed again.
:::


# Teams
URL: /docs/product-docs/collaboration/teams

Manage groups of users with role-based access to workspaces & bases























































<Callout type="info">
  Workspace Teams: 

  **Business**

   plan onwards in Cloud and On-premise 

  **Enterprise**

   edition. Organization Teams: 

  **Enterprise**

   plan only (Cloud & On-premise).
</Callout>

## Overview

Teams let you group members so you can assign and manage permissions at scale. Instead of configuring the same role for each person on every base, add users to a team and grant that team a role on one or more bases.

NocoDB supports two scopes of teams:

|                  | Workspace Teams            | Organization Teams   |
| ---------------- | -------------------------- | -------------------- |
| **Scope**        | Single workspace           | Entire organization  |
| **Managed in**   | Workspace Settings > Teams | Admin Panel > Teams  |
| **Availability** | Business plan onwards      | Enterprise plan only |

**When to use which:**

* **Org teams** are ideal for company-wide groups like departments (Engineering, Marketing, HR) that need consistent access across multiple workspaces. The Org Admin manages them centrally, and they can be assigned roles in any workspace.
* **Workspace teams** are better for project-specific or workspace-local groups — for example, a "Sprint Team" or "External Contractors" group that only needs access within a single workspace.

Teams help you to

* **Organize** members by department, project, or function
* **Manage permissions** efficiently by assigning roles to teams instead of individuals
* **Scale access control** without managing individual user permissions
* **Maintain flexibility** with inheritance and override capabilities
* **Create sub-teams** for more granular organization with up to 4 levels of nesting

## Workspace Teams

<Callout type="info">
  The following sections cover 

  **Workspace Teams**

  . For organization-level teams, see 

  [Organization Teams](#organization-teams)

   below.
</Callout>

### Create Team

1. Navigate to **Workspace Settings** > **Teams** tab.
2. Click **New Team**.
3. Enter a team name (Optional).
4. Click **Create Team**.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

When a team is created, the creator is automatically added as its first member and designated as the **Team Owner**. Team Owners have full administrative privileges, including adding or removing members, renaming the team, and deleting it when necessary. Multiple owners can be assigned to a team, but each team must always have at least one owner.

### Add Members to a Team

In the **Teams** tab, select the team you want to manage, then follow these steps:

1. Click **Add Members**.
2. Use the toggle buttons to select existing workspace members to add. Members already part of the team are clearly indicated.
3. Click **Add Members** again to confirm your selection.

You can search by name or email to quickly locate users. Existing team members have their toggles disabled to avoid duplicate additions. Each member's workspace role is displayed beside their name for better context.

<img alt="image" src={__img2} placeholder="blur" />
<img alt="image" src={__img3} placeholder="blur" />

### Remove Members from a Team

In the **Teams** tab, select the team you want to manage, then follow these steps:

1. Locate the member you want to remove. Use the search bar if needed and open the **Actions** (three dots) menu beside their name.
2. Select **Remove Member**.
3. Confirm the action when prompted.

<img alt="image" src={__img4} placeholder="blur" />
<img alt="image" src={__img5} placeholder="blur" />

To remove **multiple members** at once:

1. Use the checkboxes to select the members you want to remove.
2. Click **Actions** > **Remove from Team** at the top of the member list.
3. Confirm the action when prompted.

<img alt="image" src={__img6} placeholder="blur" />
<img alt="image" src={__img7} placeholder="blur" />

### Manage Team Owners

A team can have multiple owners, but it must always have at least one.

To add or remove team owners:

1. In the **Teams** tab, select the team you want to manage.
2. Locate the member whose ownership status you want to change. Use the search bar if necessary and open the **Actions** (three dots) menu beside their name.
3. To grant ownership, select **Assign as Team Owner**. To revoke ownership, select **Remove as Team Owner**.

<img alt="image" src={__img8} placeholder="blur" />
<img alt="image" src={__img9} placeholder="blur" />

### Leave Team

Members can leave a team on their own if they no longer wish to be part of it (any team member can leave, not just owners — as long as at least one owner remains).

To leave a team you are a member of:

1. In the **Teams** tab, open team context menu by clicking the **Actions** (three dots) button beside the team name.
2. Click the **Leave Team** button from the dropdown menu.
3. Confirm the action when prompted.

<img alt="image" src={__img10} placeholder="blur" />
<img alt="image" src={__img11} placeholder="blur" />

### Rename Team

In the **Teams** tab, select the team you want to rename. Edit team name as needed, and your changes will be saved automatically.

<img alt="image" src={__img12} placeholder="blur" />

### Delete Team

<Callout type="warning">
  Only Team Owners can delete a team. Deleting a team will not remove its members from the workspace; it only dissolves the team grouping.
</Callout>

To delete a team:

1. In the **Teams** tab, open team context menu by clicking the **Actions** (three dots) button beside the team name.
2. Click the **Delete Team** button from the dropdown menu.
3. Confirm the action when prompted.

<img alt="image" src={__img13} placeholder="blur" />
<img alt="image" src={__img14} placeholder="blur" />

### Sub-teams

You can create teams within teams to match how your company is organized. For example, an "Engineering" team can have "Frontend" and "Backend" as sub-teams.

Sub-teams can be nested up to **4 levels deep**.

```
Engineering
├── Frontend
│   └── Design System
│       └── Icons              ← maximum depth
└── Backend
```

<img alt="image" src={__img15} placeholder="blur" />

#### Create a sub-team

1. In the **Teams** tab, click the **Actions** (three dots) menu next to the parent team.
2. Select **Create Sub-team**.
3. Enter a name for the sub-team.
4. Click **Create Team**.

<img alt="image" src={__img16} placeholder="blur" />
<img alt="image" src={__img17} placeholder="blur" />

Alternatively, click **New Team** and select a parent team from the **Parent team** dropdown. Enter a name for the team and click **Create Team**.

<img alt="image" src={__img18} placeholder="blur" />

#### Move a team

You can move a team under a different parent, or make it a top-level team.

1. In the **Teams** tab, click the **Actions** (three dots) menu next to the team.
2. Select **Move Team**.
3. Pick the new parent team, or choose no parent to make it top-level.
4. Confirm the move.

<img alt="image" src={__img19} placeholder="blur" />
<img alt="image" src={__img20} placeholder="blur" />

<Callout type="warning">
  Moving a team also moves all its sub-teams. The total depth after the move cannot exceed 4 levels.
</Callout>

#### Members in sub-teams

Adding someone to a parent team does **not** automatically add them to its sub-teams. You manage each team's members separately.

When you open a team's details, you'll see:

* **Direct members** — people you added to this team
* **Inherited members** — people from parent teams above, shown for reference with a label indicating which team they belong to

<img alt="image" src={__img21} placeholder="blur" />

### How sub-teams affect permissions

| What                              | Direction | How it works                                                                 |
| --------------------------------- | --------- | ---------------------------------------------------------------------------- |
| Workspace & base roles            | Upward    | Parent team members automatically get their sub-team's roles                 |
| Table, record & field permissions | Downward  | Sub-team members are included by default; you can switch to "This team only" |

Sub-teams change how permissions work in two ways:

#### 1. Workspace & base roles flow upward

When you give a sub-team a role on a workspace or base, members of the **parent team also get that role** automatically. This way, managers in the parent team can always see what their sub-teams have access to.

**Example:** The "Frontend" sub-team has **Editor** access to Workspace X.

| Person | Team                             | Access to Workspace X          |
| ------ | -------------------------------- | ------------------------------ |
| Alice  | Frontend                         | Editor                         |
| Bob    | Engineering (parent of Frontend) | Editor — gets it automatically |
| Carol  | Backend (sibling, not parent)    | No access                      |

<Callout type="info">
  This only works 

  **upward**

  . Parent team members get the sub-team's roles, but sub-team members do 

  **not**

   get the parent team's roles.
</Callout>

#### 2. Table, record & field permissions flow downward

When you grant a team access using **"Specific users or teams"** in [table visibility](/docs/product-docs/roles-and-permissions/table-permissions#table-visibility), [record permissions](/docs/product-docs/roles-and-permissions/table-permissions#table-record-permissions), or [field permissions](/docs/product-docs/roles-and-permissions/field-permissions), you can choose whether to include sub-team members or not.

After selecting a team, you'll see a segmented control next to the team name with two options:

| Option                    | Who gets access                                     |
| ------------------------- | --------------------------------------------------- |
| **This team**             | Only direct members of this team                    |
| **+ Sub-teams** (default) | Members of this team **and all sub-teams below it** |

<img alt="image" src={__img22} placeholder="blur" />

{/* ![Hierarchy scope toggle — include sub-teams](/img/v2/collaboration/teams/scope-toggle-with-descendants.png) */}

**Example:** The "Infrastructure" table is visible to the "Engineering" team.

With **"Include sub-teams"** (default):

| Person | Team                         | Can see "Infrastructure"? |
| ------ | ---------------------------- | ------------------------- |
| Alice  | Engineering                  | Yes                       |
| Bob    | Frontend (sub-team)          | Yes                       |
| Carol  | Design System (sub-sub-team) | Yes                       |
| Dave   | Marketing                    | No                        |

With **"This team only"**:

| Person | Team                         | Can see "Infrastructure"? |
| ------ | ---------------------------- | ------------------------- |
| Alice  | Engineering                  | Yes                       |
| Bob    | Frontend (sub-team)          | No                        |
| Carol  | Design System (sub-sub-team) | No                        |

This toggle is available wherever you see the **"Specific users or teams"** option:

* **Table visibility** — who can see a table
* **Record permissions** — who can create or delete records
* **Field permissions** — who can edit a field

### Team roles

Every team member is either an **Owner** or a **Member**.

| Role       | What they can do                                                            |
| ---------- | --------------------------------------------------------------------------- |
| **Owner**  | Manage the team — rename, move, delete, add/remove people, create sub-teams |
| **Member** | Be part of the team and receive the workspace/base roles assigned to it     |

* The person who creates a team is automatically its first Owner.
* A team can have multiple Owners but must always have at least one.
* Team roles (Owner/Member) are separate from workspace and base roles (Creator, Editor, Viewer, etc.).

### Assign roles to teams

You can give a team a role at the workspace or base level, just like you do for individual users. When a team gets a role, all its members receive that access.

Available roles for teams:

* **Creator** — full control except deletion
* **Editor** — add, edit, and delete records
* **Commenter** — view and comment on records
* **Viewer** — read-only access
* **No Access** — block access entirely

<Callout type="info">
  Teams 

  **cannot**

   be given the 

  **Owner**

   role. Only individual users can be workspace or base owners.
</Callout>

For step-by-step instructions:

* [Add a team to a workspace](/docs/product-docs/collaboration/workspace-collaboration#invite-teams-to-workspace-)
* [Add a team to a base](/docs/product-docs/collaboration/base-collaboration#invite-teams-to-base-)

### Effective role resolution

When someone belongs to one or more teams **and** has an individual role, NocoDB picks the one that applies using this order:

#### For a base

| Priority    | Where the role comes from                            |
| ----------- | ---------------------------------------------------- |
| 1 (highest) | Role assigned directly to the user on this base      |
| 2           | Highest role from any team assigned to this base     |
| 3           | Role assigned directly to the user on the workspace  |
| 4           | Highest role from any team assigned to the workspace |
| 5 (lowest)  | No access                                            |

#### For a workspace

| Priority    | Where the role comes from                            |
| ----------- | ---------------------------------------------------- |
| 1 (highest) | Role assigned directly to the user on the workspace  |
| 2           | Highest role from any team assigned to the workspace |
| 3 (lowest)  | No access                                            |

#### Rules to remember

* **Individual roles always win over team roles** at the same level.
* **Base-level roles win over workspace-level roles** — a role set on a specific base takes priority.
* **Highest team role wins** — if you're in two teams with different roles, you get the higher one. For example, Viewer + Editor = Editor.
* **"Inherit" at workspace level** means "use my team role." Any other workspace role overrides team roles.
* **"No Access" at workspace level blocks everything** — even team roles can't override it.

#### Examples

**Team role only**

Alice is in the "Marketing" team, which has **Editor** access on Workspace X. Alice has no individual role.

→ Alice gets **Editor** access on the workspace and all its bases.

**Individual role overrides team**

Bob is in "Marketing" (Editor on Workspace X), but Bob is also individually set as **Viewer** on Workspace X.

→ Bob gets **Viewer** — individual roles always take priority, even if less permissive.

**Multiple teams**

Carol is in "Marketing" (Viewer on Base A) and "Content" (Editor on Base A).

→ Carol gets **Editor** on Base A — the higher team role wins.

**Base-level override**

Dave is in "Engineering" (Editor on Workspace X). He's also individually set as **Creator** on Base B.

→ Dave gets **Creator** on Base B, **Editor** on all other bases.

**Sub-team role flowing upward**

"Frontend" is a sub-team of "Engineering." "Frontend" has **Editor** on Workspace X.

→ Frontend members get **Editor**.
→ Engineering members also get **Editor** — parent team members automatically receive sub-team roles.

### Best practices

* **Invite users with the "Inherit" role** at workspace level. This lets their access be fully controlled through teams. (Note: "No Access" at workspace level blocks all team roles.)
* **Match your org chart** — create top-level teams for departments and sub-teams for groups within them.
* **Put managers in parent teams** — they'll automatically get access to everything their sub-teams can see.
* **Use individual roles only for exceptions** — teams should handle the norm, individual assignments handle the edge cases.
* **Use clear team names** (e.g., `Eng - Backend`, `Ops - HR`) so it's easy to find and manage teams.
* **Review membership regularly** — remove people who've left or changed roles.
* **Add multiple team owners** — so things don't get stuck if one owner is unavailable.

***

## Organization Teams

<Callout type="info">
  Availability: 

  **Enterprise**

   plan only (Cloud & On-premise)
</Callout>

Organization teams are scoped to the entire organization and can be assigned roles across any workspace within the org. They are created and managed from the **Admin Panel** > **Teams** section by the Org Admin.

Unlike workspace teams, org teams do not have a separate Team Owner / Team Member distinction. The **Org Admin** has full management control over all org-level teams — including creating, editing, deleting teams and managing their members.

Org teams appear in workspace member and team lists with an **ORG** badge. They are read-only at the workspace level — you cannot edit their membership from workspace settings, but you can assign them workspace or base roles just like workspace teams.

### Create an Org Team

1. Navigate to **Admin Panel** > **Teams**.
2. Click **+ New Team**.
3. Enter a team name.
4. Optionally, select a **Parent team** to create it as a sub-team.
5. Click **Create Team**.

<img alt="image" src={__img23} placeholder="blur" />

### Manage an Org Team

Click the **Actions** (three dots) menu beside a team to:

* **Edit** – Open the team to manage its members and settings.
* **Add sub-team** – Create a nested sub-team under this team.
* **Move team** – Move the team under a different parent.
* **Delete team** – Remove the team from the organization.

<img alt="image" src={__img24} placeholder="blur" />

### Add Members to an Org Team

1. In **Admin Panel** > **Teams**, click **Edit** on the team you want to manage.
2. Click **Add Members**.
3. Select one or more members from the organization's member list.
4. Click **Add Members** to confirm.

Members already part of the team are indicated and cannot be added again. You can search by name or email to quickly locate users.

### Sub-teams

Org teams support the same hierarchical structure as workspace teams, with sub-teams nested up to **4 levels deep**.

To create an org sub-team:

1. In **Admin Panel** > **Teams**, click the **Actions** (three dots) menu next to the parent team.
2. Select **Add sub-team**.
3. Enter a name and click **Create Team**.

Alternatively, click **+ New Team** and select a parent team from the **Parent team** dropdown.

<img alt="image" src={__img25} placeholder="blur" />

<Callout type="warning">
  Organization teams and workspace teams are separate hierarchies. An org team cannot be a child of a workspace team, and a workspace team cannot be a child of an org team.
</Callout>

### Assign Org Teams to Workspaces and Bases

Org teams can be assigned workspace-level or base-level roles, just like workspace teams. When an org team is given a role, all its members receive that access.

From a workspace's **Members** tab, org teams appear with an **ORG** badge. You can assign or change their role from this view, but you cannot edit the team's membership — that is managed from the Admin Panel.

<img alt="image" src={__img26} placeholder="blur" />

Roles assigned to org teams follow the same [effective role resolution](#effective-role-resolution) rules as workspace teams.

### Org Teams vs Workspace Teams

| Aspect                    | Workspace Teams            | Organization Teams              |
| ------------------------- | -------------------------- | ------------------------------- |
| Plan required             | Business+                  | Enterprise                      |
| Scope                     | Single workspace           | Entire organization             |
| Managed from              | Workspace Settings > Teams | Admin Panel > Teams             |
| Managed by                | Team Owners                | Org Admin                       |
| Visible in workspace      | Yes (native)               | Yes (with ORG badge, read-only) |
| Sub-team depth            | 4 levels                   | 4 levels                        |
| Members source            | Workspace members          | Org members                     |
| Can parent the other type | No                         | No                              |

<Callout type="info">
  Team names are scoped — they must be unique within their own scope (workspace or org), but the same name can exist in different scopes. For example, a team called "Support" can exist as an org team and also as a workspace team in two different workspaces, all independently.
</Callout>

### Best practices

* **Use org teams for cross-workspace access** — when teams need consistent roles across multiple workspaces, create an org team in the Admin Panel rather than duplicating workspace teams in each workspace.
* **Reserve workspace teams for project-specific groups** — if a team only needs access within a single workspace, a workspace team is simpler to manage.

***


# Workspace collaboration
URL: /docs/product-docs/collaboration/workspace-collaboration

This article explains how to invite members or teams to your workspace, manage their roles, and remove them when needed.





















<Callout type="info">
  A comprehensive guide regarding roles and permissions can be accessed 

  [here](/docs/product-docs/roles-and-permissions)
</Callout>

<Callout type="info">
  Teams feature availability: 

  **Business**

   plan onwards in cloud and On-premise 

  **Enterprise**

   edition
</Callout>

## Invite Members to Workspace

1. Go to **Team & Settings** in the left minibar.
2. Open the **Members** tab.
3. Click **Add Member**.
4. Enter one or more email addresses (comma-separated).
5. Select a role for the invited member(s).
6. Click **Invite to Workspace**.

<Callout type="info">
  Any user can invite members to the workspace, but they can only assign a role to new members that is at most equal to their own role.
</Callout>

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />
<img alt="image" src={__img2} placeholder="blur" />

<Callout type="info">
  You have the capability to invite multiple members simultaneously by entering their email addresses, separated by commas.
</Callout>

## Invite Teams to Workspace ☁

NocoDB now allows inviting **Teams** to the workspace for simplified collaboration. Teams can be assigned workspace-level access roles, streamlining permissions for all their members.

1. Navigate to the `Team & Settings` page and open the `Members` tab.
2. Click on the `Add Teams` button.
3. From the dropdown, select one or multiple teams to add.
4. Choose the appropriate access role from the dropdown menu. Note that,
   * Similar to individual members, you can only assign roles that are at most equal to your own role in the workspace.
   * Teams can't be assigned the **Owner** role.
5. Click on the `Add Teams` button to complete the process.

<Callout type="info">
  When a team is invited to the workspace, all users under that team inherit the assigned workspace-level role unless overridden by a lower-level permission (explicit workspace role or base-level role).
</Callout>

<img alt="image" src={__img3} placeholder="blur" />
<img alt="image" src={__img4} placeholder="blur" />

To learn more about creating and managing teams, refer to the [Teams documentation](/docs/product-docs/collaboration/teams).

<Callout type="info">
  **Organization Teams**

   (Enterprise only): Org-level teams also appear in the team selector with an 

  **ORG**

   badge. These teams are managed from the 

  [Admin Panel](/docs/product-docs/cloud-enterprise-edition/admin-panel#teams)

   and are read-only at the workspace level — you cannot edit their membership from workspace settings, but you can assign them workspace or base roles. Learn more about 

  [Organization Teams](/docs/product-docs/collaboration/teams#organization-teams)

  .
</Callout>

<img alt="image" src={__img5} placeholder="blur" />

## List Workspace Members and Teams

The `Members` tab displays all users and teams that have access to the workspace.

* Individual members appear with their email addresses.
* Teams are listed with their name and member count.
* Organization teams (Enterprise only) are displayed with an **ORG** badge, distinguishing them from workspace teams.

<Callout type="info">
  Members and teams list is accessible to all workspace members.
</Callout>

<img alt="image" src={__img6} placeholder="blur" />

## Modify Roles for Members or Teams

Access permissions for both members and teams can be updated directly from the `Members` tab.

1. Click on the access dropdown next to the member or team.
2. Select a new role from the list of available options.

<Callout type="info">
  You can only assign roles that are at most equal to your own role in the workspace. Teams cannot be assigned the 

  **Owner**

   role.
</Callout>

<img alt="image" src={__img7} placeholder="blur" />

## Role Precedence

When a user has multiple role assignments through both team and individual access, NocoDB resolves the final permission using a clear precedence order.

* Individual explicit role takes precedence over team-assigned role.
* Base-level roles override workspace-level roles.
* In case of multiple team roles, the **highest** permission applies.

<Callout type="info">
  This ensures users always retain the most permissive access assigned at their lowest configured level.
</Callout>

To learn more about effective role resolution, refer to the [Teams effective role resolution documentation](/docs/product-docs/collaboration/teams#effective-role-resolution).

## Remove Members or Teams from Workspace

You can remove both members and teams from the workspace using the context menu.

1. Click on the vertical ellipses `⋮` beside the member or team entry.
2. Select the appropriate removal option — `Remove User` or `Remove Team`.

<Callout type="info">
  Only the workspace 

  **owner**

   or 

  **creator**

   can remove members or teams from the workspace.
</Callout>

<img alt="image" src={__img8} placeholder="blur" />
<img alt="image" src={__img9} placeholder="blur" />

## Best Practice

* Invite all users to the workspace first with the **Inherit** role. This will allow them to access workspaces based on their team or base-level roles.
* Use teams for departments or functional groups to manage roles efficiently.
* Adjust team-level permissions instead of managing roles individually for large workspaces.

Learn more [here](/docs/product-docs/collaboration/teams#best-practices).

***


# Dashboards
URL: /docs/product-docs/dashboards

Create and share dashboards with your team













The Dashboard feature in NocoDB enables you to visualize data from your tables using charts, graphs, and metric widgets. Dashboards help present key insights to stakeholders through an interactive, configurable interface.

<Callout type="info">
  Dashboards are currently in Beta and available on 

  **Plus**

   and 

  **Business**

   plans in Cloud.
</Callout>

## Getting Started

### Creating a Dashboard

1. Click on **Create New** in the left sidebar.
2. Select **Dashboard** from the dropdown.
3. Enter a name for your dashboard. (Optional, Defaults to "Dashboard")
4. Click **Create Dashboard** to open the dashboard editor.
5. Click on **Edit Dashboard** to start adding widgets.

<img alt="Create a new dashboard" src={__img0} placeholder="blur" />
<img alt="Create a new dashboard" src={__img1} placeholder="blur" />
<img alt="Create a new dashboard" src={__img2} placeholder="blur" />

### Managing Dashboards

Use the dashboard context menu to perform actions like:

* **Rename dashboard**: Change the dashboard name
* **Edit description**: Add or update the dashboard description. This description will appear on hover over the `i` icon in the dashboard header.
* **Duplicate dashboard**: Create a copy of the dashboard
* **Delete dashboard**: Remove the dashboard

<img alt="Dashboard context menu" src={__img3} placeholder="blur" />

### Sharing Dashboards

To share a dashboard publicly, click the **Share** button in the top navigation bar, enable the `Enable Public Viewing` option, and copy the generated link. Anyone with this link will be able to view the dashboard without requiring a NocoDB account.

<img alt="Share dashboard" src={__img4} placeholder="blur" />

Additional options include:

* Configuring a custom URL for your dashboard.
* Setting a password to control access.

Dashboard sharing works similarly to view sharing. Learn more about [sharing views](/docs/product-docs/views/share-view).

***

## Dashboard Layout

1. **Top Navigation Bar**: Navigation breadcrumbs and dashboard-level actions. Toggle between dashboard **View** and **Edit** modes. You can also **Share** the dashboard with team members.
2. **Widget Bar**: Toolbar at the top with available widget types to add to the dashboard.
3. **Dashboard Canvas**: Main area where widgets are arranged. NocoDB supports a flexible grid layout, allowing you to drag and drop widgets to position them as needed.
4. **Widget Configuration Panel**: Right panel for configuring selected widget properties.

<img alt="Dashboard layout" src={__img5} placeholder="blur" />

## Widgets

NocoDB dashboards support various widget types to visualize data effectively. You can add widgets from the widget bar at the top of the dashboard editor.

The following widget types are available:

| Widget Type                                                          | Description                             |
| -------------------------------------------------------------------- | --------------------------------------- |
| **[Number](/docs/product-docs/dashboards/widgets/number)**           | Displays KPIs and metric summaries      |
| **[Pie Chart](/docs/product-docs/dashboards/widgets/pie-chart)**     | Visualizes parts of a whole             |
| **[Donut Chart](/docs/product-docs/dashboards/widgets/donut-chart)** | Pie chart variant with a hollow center  |
| **[Text](/docs/product-docs/dashboards/widgets/text)**               | Displays static text                    |
| **[iFrame](/docs/product-docs/dashboards/widgets/iframe)**           | Embeds external web content             |
| **[Bar Chart](/docs/product-docs/dashboards/widgets/bar-chart)**     | Bar chart variant with a hollow center  |
| **[Line Chart](/docs/product-docs/dashboards/widgets/line-chart)**   | Line chart variant with a hollow center |

***


# Actions on Data sources
URL: /docs/product-docs/data-sources/actions-on-data-sources

Learn more about actions that can be performed on data sources in NocoDB.













## Edit Data Source parameters

* Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings homepage
* Click on the data source that you wish to edit
* Re-configure data source parameters as required. The following parameters can be edited:
  1. Data source name
  2. Database & Schema
  3. Data source access permissions
* Click on `Submit` button to save the changes

<Callout type="info">
  To change database connection configuration parameters (like host, port, and such) use 

  [Edit connection](/docs/product-docs/integrations/actions-on-connection#edit)

   option. Edit connection option is available only for the users with Workspace Creator+ permissions
</Callout>

<img alt="edit-data-source" src={__img0} placeholder="blur" />

## Remove data source

Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings homepage

1. Click on Actions button (three dots) against the data source that you wish to remove
2. Select `Remove` option from the dropdown

<img alt="datasource unlink" src={__img1} placeholder="blur" />

<img alt="datasource unlink" src={__img2} placeholder="blur" />

<Callout type="info">
  Removing a data source will not delete the external data source. It will only remove the data source from the current base
</Callout>

## Data source visibility

* Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings homepage
* Toggle radio button listed under `Visibility` column for the data source that you wish to hide/un-hide

<img alt="datasource visibility" src={__img3} placeholder="blur" />

## View visibility

<Callout type="info">
  View visibility is available only in Open-Source version of NocoDB
</Callout>

Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings homepage, select the data source that you wish to configure view visibility for and follow the steps below:

1. Select `View visibility` tab
2. You can see the list of views & tables available in the data source as rows & roles available as columns. Toggle checkboxes to enable/disable access to tables for specific roles.
3. Click on `Save` button to save the changes

<img alt="ui acl" src={__img4} placeholder="blur" />

## Relations

* Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings homepage
* Select the data source that you wish to access ERD (Relations view) for
* Click on `ERD View` tab

<img alt="relations" src={__img5} placeholder="blur" />


# Connect to a Data source
URL: /docs/product-docs/data-sources/connect-to-data-source

Learn how to connect to an external data-source (PG/MySQL) in NocoDB.









<Callout type="info">
   NocoDB recommends using 

  **MySQL version 5.7 or later**

   and 

  **PostgreSQL version 14 or later**

   for best compatibility and performance. 
</Callout>

To connect an external Database as a new Data Source for NocoDB, follow the steps below:

1. Click on the Base name in the left sidebar to access the **Base homepage**
2. Click **Connect External Data** button
3. Provide a name to the data source
4. Select connection to pick credentials for the database
   (a) Select connection from the list of available connections in the dropdown\
   (b) Click on `+ New connection` button to create a new connection instead
5. Configure / Change database & schema details as required. If default database & schema details were provided during connection creation, these details will be pre-filled.
6. [Configure permissions](#configuring-permissions) for the data source
7. Click on `Test Database Connection` button to verify the connection
8. Click on `Add Source` button to save the data source

<img alt="data source" src={__img0} placeholder="blur" />

<img alt="data source" src={__img1} placeholder="blur" />

<img alt="data source" src={__img2} placeholder="blur" />

<Callout type="info">
  Option (4b) to create a new connection is available only if the user has the required permissions to create new connection (Workspace Creator+)
</Callout>

## Configuring Permissions

This section covers the settings available when configuring data source permissions. These settings determine the level of access and modifications allowed on the connected database.

<img alt="data source-1" src={__img3} placeholder="blur" />

NocoDB provides the following options for schema and data permissions:

### Allow Data Edit

This option when enabled, users can insert, update, and delete records from the tables. This provides the flexibility to manage the data directly from the NocoDB UI but should be used with caution to avoid unintentional changes to the records in the external data source. This level of access is ideal for administrative users who need to modify data directly.

By default, data editing is enabled

When data editing is disabled, users can still view the data and perform read-only operations such as filtering, sorting, and grouping. This ensures that users can access the data for analysis and reporting purposes without the risk of modifying the records.

<Callout type="info">
  Data editing can only be disabled when schema editing is also disabled
</Callout>

### Allow Schema Edit

This option enables users to modify the structure of the database schema. When enabled, users can create, modify, and delete tables, fields and relationships (links) within the connected datasource from NocoDB UI. This provides flexibility to adjust the database schema design as needed from UI.

<Callout type="warn">
  NocoDB strongly advises against enabling the schema editing option unless absolutely necessary. Use with extreme caution, as improper changes can severely impact the data integrity and functionality of the connected data source.
</Callout>

By default, schema editing is disabled.

Even when schema editing is disabled, users can still

* add (augment) virtual columns such as Lookup, Rollup and Formula. These virtual columns do not alter the underlying schema of the connected data source.
* create views to customize the data presentation without modifying the original tables.
* create webhooks to trigger external actions based on specific events within the connected datasource.
* collaborate with other users by explicitly inviting them to the base or by sharing views.


# Data sources
URL: /docs/product-docs/data-sources

NocoDB Data-Source sync, access control & re-config



## Overview

NocoDB allows you to connect to external data sources and get a unified spreadsheet view of your data. Activities related to external data sources can be managed from `Data Sources` tab in `Base dashboard`.

`Data Sources` tab includes following functionalities

1. Connect / manage external data source
2. UI Access Control
3. Relations (ERD View)
4. Meta Sync

## Accessing `Data Sources`

1. Click on Base name in the left sidebar to access **Base homepage**
2. Select **Data Sources** tab

<img alt="data source" src={__img0} placeholder="blur" />

Learn more about **working with Data sources** in the following sections:

* [Connect to a Data source](/docs/product-docs/data-sources/connect-to-data-source)
* [Sync changes externally made to data source](/docs/product-docs/data-sources/sync-with-data-source)
* [Edit external database configuration parameters](/docs/product-docs/data-sources/actions-on-data-sources#edit-data-source-parameters)
* [Remove Data source](/docs/product-docs/data-sources/actions-on-data-sources#remove-data-source)
* [Hide Data source](/docs/product-docs/data-sources/actions-on-data-sources#data-source-visibility)
* [Relations within a data source](/docs/product-docs/data-sources/actions-on-data-sources#relations)
* [View visibility](/docs/product-docs/data-sources/actions-on-data-sources#view-visibility)


# Sync with Data source
URL: /docs/product-docs/data-sources/sync-with-data-source

Learn how to sync changes done in external data source with NocoDB.





To sync changes done in the external data source with NocoDB, Open [Data Sources](/docs/product-docs/data-sources#accessing-data-sources) tab in the Base Settings, select the data source you wish to sync metadata for, and follow the steps below:

1. Click on the `Meta Sync` tab
2. Click on the `Reload` button to refresh Sync state (Optional)
3. Any changes to the metadata identified will be listed in the `Sync State` column
4. Click on `Sync Now` button to sync the metadata changes
5. Once the sync is complete, you can see the updated state in the `Sync State` column

<img alt="sync metadata" src={__img0} placeholder="blur" />

<img alt="sync metadata" src={__img1} placeholder="blur" />

After the sync is complete, you can see the updated state in the `Sync State` column.\
Sync modal also marks `Tables metadata is in Sync` in the header.


# Updating Secrets
URL: /docs/product-docs/data-sources/updating-secret

Learn how to update secrets in NocoDB using the nc-secret-mgr package.

## Updating Secrets

To update a secret in NocoDB, you can use the `nc-secret-mgr` package. Follow the steps below to update a secret:

### Using the Command Line Interface (CLI)

1. Install the `nc-secret-mgr` package if you haven't already. You can do this by running the following command in your terminal:

   ```bash
   npm install -g nc-secret-mgr
   ```

2. Once the package is installed, you can update a secret by running the following command:

   ```bash
   NC_DB="pg://host:port?u=user&p=password&d=database" nc-secret-mgr update --prev <previous-secret> --new <new-secret>
   ```

   OR

   ```bash
   NC_DB="pg://host:port?u=user&p=password&d=database" nc-secret-mgr <previous-secret> <new-secret>
   ```

   Replace `<previous-secret>` with the name of the secret you used previously, and `<new-secret>` with the new value of the secret.

3. After running the command, the secret will be updated in NocoDB.

### Using Executables

Alternatively, you can use the `nc-secret-mgr` executable to update secrets.

1. Download the `nc-secret-mgr` executable from the [NocoDB Github](https://github.com/nocodb/nc-secret-mgr/releases/latest).

2. Run the executable using the following command:

   ```bash
   NC_DB="pg://host:port?u=user&p=password&d=database" ./nc-secret-mgr-macos-arm64 update --prev <previous-secret> --new <new-secret>
   ```

   Replace `<previous-secret>` with the name of the secret you used previously, and `<new-secret>` with the new value of the secret.

3. After running the command, the secret will be updated in NocoDB.

Note: All environment variables are supported, including `NC_DB`, `NC_DB_JSON`, `NC_DB_JSON_FILE`, `DATABASE_URL`, and `DATABASE_URL_FILE`. You can use any of these variables to specify your database connection. Alternatively, you can use the following equivalent parameters.

| Environment Variable | CLI Parameter         |
| -------------------- | --------------------- |
| `NC_DB`              | `--nc-db`             |
| `NC_DB_JSON`         | `--nc-db-json`        |
| `NC_DB_JSON_FILE`    | `--nc-db-json-file`   |
| `DATABASE_URL`       | `--database-url`      |
| `DATABASE_URL_FILE`  | `--database-url-file` |


# MCP Server
URL: /docs/product-docs/developer-resources/mcp

Connect NocoDB to Large Language Models (LLMs) via the Model Context Protocol (MCP).



































The **Model Context Protocol (MCP) Server** lets you connect NocoDB with LLMs that support MCP, such as Claude, Cursor, or Windsurf. With this integration, LLMs can interact directly with your NocoDB base to create, query, update, and manage records.

## Desktop LLM Clients

Each MCP endpoint in NocoDB provides a secure URL that can be linked to an MCP-compatible client.
Once configured, the LLM can execute database operations in your workspace through natural language prompts.

MCP server exposes standard CRUD operations. These can be triggered conversationally, without writing SQL or scripts.

| Action | Purpose              | Sample Prompt                                                 |
| ------ | -------------------- | ------------------------------------------------------------- |
| Create | Add new records      | Create a task named ‘Review Documentation’                    |
| Read   | Look up information  | Show me all projects with deadlines this week                 |
| Update | Change existing data | Mark the status of Project X as completed & re-assign to John |
| Delete | Remove records       | Remove all tasks assigned to John                             |

<Callout type="note">
   NocoDB MCP supports only record-level operations and does not handle table, field, or other metadata changes. 
</Callout>

### Server Configuration (NocoDB)

1. Click on the **Overview** button in the left sidebar.
2. Select the **Settings** tab.
3. Select the **Model Context Protocol**
4. Click on the **New MCP Endpoint** to create a new MCP config JSON for your base.
5. Provide a name for the MCP endpoint
6. Click **Create** to generate the MCP Config JSON.
7. Copy the generated JSON configuration. This will be used in your LLM client configuration.

<img alt="MCP Config" src={__img0} placeholder="blur" />

<img alt="MCP Config" src={__img1} placeholder="blur" />

### Client Configuration

#### Claude

1. Open **Claude Desktop Preferences** (`⌘+,`).
2. Under **Develop**, click **Edit Config**.
3. Insert the JSON block copied [here](#server-configuration-nocodb) as `claude_desktop_config.json`.
4. Save the file and restart Claude Desktop.

#### Cursor

1. Go to **Cursor Settings** (`⇧+⌘+J`).
2. Open the **MCP** tab and select **Add Custom MCP**.
3. Paste the JSON block copied [here](#server-configuration-nocodb). Save.

<Callout type="info">
   On success, you will see 

  `11 tools enabled`

   below the MCP Server just installed. If you see an error, double-check the JSON configuration. 
</Callout>

<img alt="Cursor MCP Settings" src={__img2} placeholder="blur" />

#### Windsurf

1. Open **Windsurf Settings** (`⌘+,`).
2. In the **Cascade** section > `Plugins (MCP Server)` > Click **Manage Plugins**
3. Paste the JSON block copied [here](#server-configuration-nocodb). Save.

<img alt="Windsurf MCP Settings" src={__img3} placeholder="blur" />

<img alt="Windsurf MCP Settings" src={__img4} placeholder="blur" />

### JSON Example

```json
{
  "mcpServers": {
    "NocoDB MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/mcp/<ncId>",
        "--header",
        "xc-mcp-token: <ncToken>"
      ]
    }
  }
}

```

<Callout type="warning">
   Your MCP configurations generated above functions as a set of access credentials, granting full control over your NocoDB base. Ensure it remains confidential, never include it in source control, and store it only in secure, protected locations.
</Callout>

***

## Web based LLM Clients (OAuth)

Connect NocoDB to web-based LLM applications using OAuth, enabling seamless database access directly from the browser without requiring desktop client setup. This approach grants granular permission controls and eliminates the need for manual JSON configuration.

### Claude Web

OAuth-based integration allows Claude web users to access NocoDB databases through the connectors interface.

#### Setup Steps

1. Click [here](https://claude.ai/settings/connectors) to open Claude Web Settings in a new tab.
   * Alternatively, navigate to **Settings** > **Connectors** from the Claude Web app.
2. Click **Add custom connector**.
   <img alt="open-connectors" src={__img5} placeholder="blur" />
3. In the "Add custom connector" dialog:
   * Provide a connector name of your choice
   * Enter the MCP endpoint URL: `https://app.nocodb.com/mcp`
   * Click `Add`
     <img alt="add-connector-dialog" src={__img6} placeholder="blur" />
4. NocoDB Connector will now be listed in "Disconnected" state. Click **Connect** to initiate the OAuth authorization flow (Opens in a new tab).
   <img alt="add-connector" src={__img7} placeholder="blur" />
5. Authorize Access
   * You will be asked to log in to your NocoDB account (if not already logged in)
   * Select the workspace and base you want to connect
   * Confirm the permissions Claude will have
     * Access the selected base
     * Read / create / update / delete records in the selected base
     * Act on your behalf within the selected resources
   * Click **Authorize** to grant access
     <img alt="authorize-access" src={__img8} placeholder="blur" />

With this, the NocoDB connector will move to "Connected" state in Claude Web. You can now interact with your NocoDB data through Claude web application.

<Callout type="note">
   On-prem enterprise users should replace 

  [https://app.nocodb.com](https://app.nocodb.com)

   with their NocoDB instance URL
</Callout>

#### Configure Tool Permissions

By default, all tools are set to "Always ask permission" to ensure you have control over each operation Claude performs. You can modify these settings as needed.

Click [here](https://claude.ai/settings/connectors) to open Claude Web Settings in a new tab. Click **Configure** on the NocoDB connector to manage tool permissions. Set each tool's permission level using the dropdown menu:

* **Always ask permission** — Your approval is required every time Claude uses this tool
* **Allow unsupervised** — Claude can use this tool without requesting approval

<img alt="tool-permissions" src={__img9} placeholder="blur" />
<img alt="tool-permissions" src={__img10} placeholder="blur" />

To retrieve Workspace & Base information that this connector has access to, use the "Get Base Info" tool.
<img alt="get-base-info" src={__img11} placeholder="blur" />

#### Using NocoDB Tools in Claude Web

Once configured, you can interact with your NocoDB data conversationally. For example:

* "Show me all projects with deadlines this week"
* "Create a task named 'Review Documentation'"
* "Mark the status of Project X as completed and reassign to John"
* "Provide details of our top 3 sponsors"

Claude will execute these requests using the enabled NocoDB tools, reading from and writing to your database based on the permissions you've granted.

<img alt="connected-connector" src={__img12} placeholder="blur" />

<Callout type="warning">
  OAuth authorization functions as a set of access credentials granting Claude control over your NocoDB base within the selected workspace. Only authorize access to bases and operations you trust Claude to perform on your behalf.
</Callout>

### ChatGPT

OAuth-based integration enables OpenAI web users (ChatGPT) to securely connect with NocoDB databases through the MCP connector, directly from their browser environment. This provides the same granular access control and eliminates the need for manual configuration or desktop client setup.

#### Prerequisites

Enable Developer Mode in ChatGPT settings to allow custom connector additions.

1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
   * Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. Click **Advanced Settings** & enable **Developer Mode**.

<img alt="open-connectors" src={__img13} placeholder="blur" />

#### Setup Steps

1. Open [ChatGPT Settings](https://chatgpt.com/#settings/Connectors) in a new tab.
   * Alternatively, click your **Profile Icon** → **Settings** → **Settings** → **Apps & Connectors**).
2. Click **Create** button in top right corner of the **Connectors** modal.
3. In the "New connector" dialog:
   * Provide a connector name of your choice. Optionally, add a description / icon.
   * Enter the MCP Server URL: `https://app.nocodb.com/mcp`
   * Check the box for **I trust this application**.
   * Click `Create`
     <img alt="new-connector" src={__img14} placeholder="blur" />
4. Authorize Access:
   * Log in to your NocoDB account if prompted
   * Select the workspace and base you want to connect
   * Review and confirm the permissions being requested:
     * Access to the selected base
     * Read / create / update / delete records
     * Act on your behalf within the selected resources
   * Click **Authorize**

Once authorization completes, you will see a confirmation message in ChatGPT Web indicating the NocoDB connector is now connected.
<img alt="connected" src={__img15} placeholder="blur" />

<Callout type="note">
  For on-prem enterprise users, replace 

  `https://app.nocodb.com`

   with your NocoDB instance URL.
</Callout>

#### Using NocoDB Tools in OpenAI Web

On the ChatGPT interface, start a new conversation and

* Click the **+** icon to open the "Tools" menu, enable `Developer Mode` if not already enabled.
* Click `More` to find and select the NocoDB connector you created. Toggle to enable it.
  <img alt="using-connector" src={__img16} placeholder="blur" />

Once configured, you can query or update your NocoDB data conversationally. For example:

* “List all open support tickets assigned to me”
* “Add a new contact named ‘Alice Chen’ to the CRM base”
* “Update the status of Order #2456 to ‘Shipped’”
* “Summarize total revenue by month from the Sales base”

ChatGPT executes these actions using the connected NocoDB tools according to the permissions granted.

<Callout type="warning">
  OAuth authorization provides ChatGPT controlled access to your NocoDB base within the selected workspace. Only authorize operations and bases you trust ChatGPT to manage on your behalf.
</Callout>

***


# Architecture overview
URL: /docs/product-docs/engineering/architecture

Simple overview of NocoDB architecture



By default, if `NC_DB` is not specified, then SQLite will be used to store your metadata. We suggest users to separate the metadata and user data in different databases.

<img alt="image" src={__img0} placeholder="blur" />

| Project Type                           | Metadata stored in | Data stored in    |
| -------------------------------------- | ------------------ | ----------------- |
| Create new base                        | NC\_DB             | NC\_DB            |
| Create new base with External Database | NC\_DB             | External Database |
| Create new base from Excel             | NC\_DB             | NC\_DB            |


# Releases & builds
URL: /docs/product-docs/engineering/builds-and-releases

NocoDB creates Docker and Binaries for each PR















## Builds of NocoDB

There are 3 kinds of docker builds in NocoDB

* Release builds [nocodb/nocodb](https://hub.docker.com/r/nocodb/nocodb) : built during NocoDB release.
* Daily builds [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily) : built every 6 hours from Develop branch.
* Timely builds [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely): built for every PR and manually triggered PRs.

Below is an overview of how to make these builds and what happens behind the scenes.

## Release builds

### How to make a release build  ?

* Click [NocoDB release action](https://github.com/nocodb/nocodb/actions/workflows/release-nocodb.yml)

* You should see the below screen

  <img alt="NocoDB Release Workflow" src={__img0} placeholder="blur" />

* Change `Use workflow from` to `Branch: master`. If you choose the wrong branch, the workflow will be ended.

  <img alt="Release Branch Selection" src={__img1} placeholder="blur" />

* Then there would be two cases - you can either leave target tag and pervious tag blank or manually input some values

* Target Tag means the target deployment version, while Previous Tag means the latest version as of now. Previous Tag is used for Release Note only - showing the file / commit differences between two tags.

### Tagging

The naming convention would be following given the actual release tag is `0.100.0`

* `0.100.0-beta.0` (first version of pre-release)
* `0.100.0-beta.1` (include bug fix changes on top of the previous version)
* `0.100.0-beta.2`(include bug fix changes on top of the previous version)
* and so on ...
* `0.100.0` (actual release)
* `0.100.1` (minor bug fix release)
* `0.100.2` (minor bug fix release)

### Case 1: Leaving inputs blank

* If Previous Tag is blank, then the value will be fetched from [latest](https://github.com/nocodb/nocodb/releases/latest)
* If Target Tag is blank, then the value will be Previous Tag plus one. Example: 0.90.11 (Previous Tag) + 0.0.1 = 0.90.12 (Target Tag)

### Case 2: Manually Input

Why? Sometimes we may mess up in NPM deployment. As NPM doesn't allow us to redeploy to the same tag again, in this case we cannot just use the previous tag + 1. Therefore, we need to use previous tag + 2 instead and we manually configure it.

* After that, click `Run workflow` to start
* You can see Summary for the overall job status.
* Once `release-draft-note` and `release-executables` is finished, then go to [releases](https://github.com/nocodb/nocodb/releases), edit the draft note and save as draft for time being.
  * Example: Adding header, update content if necessary, and click `Auto-generate release notes` to include more info.
* Once `release-docker` is finished, then test it locally first. You'll be expected to see `Upgrade Available` notification in UI as we haven't published the release note. (the version is retrieved from there)
* Once everything is finished, then publish the release note and the deployment is considered as DONE.

### How does release action work ?

#### validate-branch

To check if `github.ref` is master. Otherwise, other branches will be not accepted.

#### process-input

To enrich target tag or previous tag if necessary.

#### pr-to-master

Automate a PR from develop to master branch so that we know the actual differences between the previous tag and the current tag. We choose master branch for a deployment base.

#### release-npm

Build frontend and backend and release them to NPM. The changes during built such as version bumping will be committed and pushed to a temporary branch and an automated PR will be created and merged to master branch.

Note that once you publish with a certain tag, you cannot publish with the same tag again.

#### release-draft-note

Generate a draft release note. Some actions need to be done after this step.

#### release-docker

Build docker image and publish it to Docker Hub. It may take around 15 - 30 mins.

#### close-issues

Open issues marked with label `Status: Fixed` and `Status: Resolved` will be closed by bot automatically with comment mentioning the fix is included in which version.

Example:

<img alt="Close Issues Example" src={__img2} placeholder="blur" />

#### publish-docs

Publish Documentations

#### update-sdk-path

`nocodb-sdk` is used in frontend and backend. However, in develop branch, the value would be `file:../nocodb-sdk` for development purpose (so that the changes done in nocodb-sdk in develop will be included in frontend and backend). During the deployment, the value will be changed to the target tag. This job is to update them back.

#### sync-to-develop

Once the deployment is finished, there would be some new changes being pushed to master branch. This job is to sync the changes back to develop so that both branch won't have any difference.

## Daily builds

### What are daily builds ?

* NocoDB creates every 6 hours from develop branches and publishes as nocodb/nocodb-daily
* This is so that we can easily try what is in the develop branch easily.

### Docker images

* The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily/tags) for the full list).

## Timely builds

### What are timely builds ?

NocoDB has github actions which creates docker and binaries for each PR! And these can be found as a **comment on the last commit** of the PR.

Example shown below

* Go to a PR and click on the comment.
  <img alt="PR Comment Timely Build" src={__img3} placeholder="blur" />

* Click on the link to copy the docker image and run it locally.
  <img alt="Docker Copy Command" src={__img4} placeholder="blur" />

This is to

* reduce pull request cycle time
* allow issue reporters / reviewers to verify the fix without setting up their local machines

### Docker images

When a non-draft Pull Request is created, reopened or synchronized, a timely build for Docker would be triggered for the changes only included in the following paths.

* `packages/nocodb-sdk/**`
* `packages/nc-gui/**`
* `packages/nocodb/**`

The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely/tags) for the full list). Once the image is ready, GitHub bot will add a comment with the command in the pull request. The tag would be `<NOCODB_CURRENT_VERSION>-pr-<PR_NUMBER>-<YYYYMMDD>-<HHMM>`.

<img alt="Timely Build Comment" src={__img5} placeholder="blur" />

## Executables or Binaries

Similarly, we provide a timely build for executables for non-docker users. The source code will be built, packaged as binary files, and pushed to GitHub (See [nocodb/nocodb-timely](https://github.com/nocodb/nocodb-timely/releases) for the full list).

Currently, we only support the following targets:

* `node16-linux-arm64`
* `node16-macos-arm64`
* `node16-win-arm64`
* `node16-linux-x64`
* `node16-macos-x64`
* `node16-win-x64`

Once the executables are ready, GitHub bot will add a comment with the commands in the pull request.

<img alt="Executables Comment" src={__img6} placeholder="blur" />

NocoDB creates Docker and Binaries for each PR.

This is to

* reduce pull request cycle time
* allow issue reporters / reviewers to verify the fix without setting up their local machines


# Development Setup
URL: /docs/product-docs/engineering/development-setup

How to set-up your development environment



## Clone the repo

```bash
git clone https://github.com/nocodb/nocodb
# change directory to the project root
cd nocodb
```

## Install dependencies

```bash
# run from the project root
# this command will install the dependencies including sdk build
pnpm bootstrap
```

## Start Frontend

```bash
# run from the project root
pnpm start:frontend
# runs on port 3000
```

## Start Backend

```bash
# run from the project root
pnpm start:backend
# runs on port 8080
```

Any changes made to frontend and backend will be automatically reflected in the browser.

## Enabling CI-CD for Draft PR

CI-CD will be triggered on moving a PR from draft state to `Ready for review` state & on pushing changes to `Develop`. To verify CI-CD before requesting for review, add label `trigger-CI` on Draft PR.

## Accessing CI-CD Failure Screenshots

For Playwright tests, screenshots are captured on the tests. These will provide vital clues for debugging possible issues observed in CI-CD. To access screenshots, Open link associated with CI-CD run & click on `Artifacts`

<img alt="CI-CD Artifacts" src={__img0} placeholder="blur" />


# Playwright E2E testing
URL: /docs/product-docs/engineering/playwright

Overview to playwright based e2e tests

## How to run tests

All the tests reside in `tests/playwright` folder.

Make sure to install the dependencies (in the playwright folder):

```bash
pnpm --filter=playwright install
pnpm exec playwright install --with-deps chromium
```

### Run Test Server

Start the backend test server (in `packages/nocodb` folder):

```bash
pnpm run watch:run:playwright
```

Start the frontend test server (in `packages/nc-gui` folder):

```bash
NUXT_PAGE_TRANSITION_DISABLE=true pnpm run dev
```

### Running all tests

For selecting db type, rename `.env.example` to `.env` and set `E2E_DEV_DB_TYPE` to  `sqlite`(default), `mysql` or `pg`.

headless mode(without opening browser):

```bash
pnpm run test
```

with browser:

```bash
pnpm run test:debug
```

For setting up mysql(sakila):

```bash
docker-compose -f ./tests/playwright/scripts/docker-compose-mysql-playwright.yml  up -d
```

For setting up postgres(sakila):

```bash
docker-compose -f ./tests/playwright/scripts/docker-compose-playwright-pg.yml 
```

### Running individual tests

Add `.only` to the test you want to run:

```js
test.only('should login', async ({ page }) => {
  // ...
})
```

```bash
pnpm run test
```

## Concepts

### Independent tests

* All tests are independent of each other.
* Each test starts with a fresh project with a fresh sakila database(option to not use sakila db is also there).
* Each test creates a new user(email as `user@nocodb.com`) and logs in with that user to the dashboard.

Caveats:

* Some stuffs are shared i.e, users, plugins etc. So be catious while writing tests touching that. A fix for this is in the works.
* In test, we prefix email and project with the test id, which will be deleted after the test is done.

### What to test

* UI verification. This includes verifying the state of the UI element, i.e if the element is visible, if the element has a particular text etc.
* Test should verify all user flow. A test has a default timeout of 60 seconds. If a test is taking more than 60 seconds, it is a sign that the test should be broken down into smaller tests.
* Test should also verify all the side effects the feature(i.e. On adding a new field type, should verify field deletion as well) will have, and also error cases.
* Test name should be descriptive. It should be easy to understand what the test is doing by just reading the test name.

### Playwright

* Playwright is a nodejs library for automating chromium, firefox and webkit.
* For each test, a new browser context is created. This means that each test runs in a new incognito window.
* For assertion always use `expect` from `@playwright/test` library. This library provides a lot of useful assertions, which also has retry logic built in.

## Page Objects

* Page objects are used to abstract over the components/page. This makes the tests more readable and maintainable.
* All page objects are in `tests/playwright/pages` folder.
* All the test related code should be in page objects.
* Methods should be as thin as possible and its better to have multiple methods than one big method, which improves reusability.

The methods of a page object can be classified into 2 categories:

* Actions: Performs an UI actions like click, type, select etc. Is also responsible for waiting for the element to be ready and the action to be performed. This included waiting for API calls to complete.
* Assertions: Asserts the state of the UI element, i.e if the element is visible, if the element has a particular text etc. Use `expect` from `@playwright/test` and if not use `expect.poll` to wait for the assertion to pass.

## Writing a test

Let's write a test for testing filter functionality.

For simplicity, we will have `DashboardPage` implemented, which will have all the methods related to dashboard page and also its child components like Grid, etc.

### Create a test suite

Create a new file `filter.spec.ts` in `tests/playwright/tests` folder and use `setup` method to create a new project and user.

```js
import { test, expect } from '@playwright/test';
import setup, { NcContext } from '../setup';

test.describe('Filter', () => {
  let context: NcContext;

  test.beforeEach(async ({ page }) => {
    context = await setup({ page });
  })

  test('should filter', async ({ page }) => {
    // ...
  });
});
```

### Create a page object

Since filter is UI wise scoped to a `Toolbar` , we will add filter page object to `ToolbarPage` page object.

```js
export class ToolbarPage extends BasePage {
  readonly parent: GridPage | GalleryPage | FormPage | KanbanPage;
  readonly filter: ToolbarFilterPage;

  constructor(parent: GridPage | GalleryPage | FormPage | KanbanPage) {
    super(parent.rootPage);
    this.parent = parent;
    this.filter = new ToolbarFilterPage(this);
  }
}
```

We will create `ToolbarFilterPage` page object, which will have all the methods related to filter.

```js
export class ToolbarFilterPage extends BasePage {
  readonly toolbar: ToolbarPage;

  constructor(toolbar: ToolbarPage) {
    super(toolbar.rootPage);
    this.toolbar = toolbar;
  }
}
```

Here `BasePage` is an abstract class, which used to enforce structure for all page objects. Thus all page object *should* inherit `BasePage`.

* Helper methods like `waitForResponse` and `getClipboardText` (this can be access on any page object, with `this.waitForResponse`)
* Provides structure for page objects, enforces all Page objects to have `rootPage` property, which is the page object created in the test setup.
* Enforces all pages to have a `get` method which will return the locator of the main container of that page, hence we can have focused dom selection, i.e.

```js
// This will only select the button inside the container of the concerned page
await this.get().querySelector('button').count();
```

### Writing an action method

This a method which will reset/clear all the filters. Since this is an action method, it will also wait for the `delete` filter API to return. Ignoring this API call will cause flakiness in the test, down the line.

```js
async resetFilter() {
  await this.waitForResponse({
    uiAction: async () => await this.get().locator('.nc-filter-item-remove-btn').click(),
    httpMethodsToMatch: ['DELETE'],
    requestUrlPathToMatch: '/api/v1/db/meta/filters/',
  });
}
```

### Writing an assertion/verification method

Here we use `expect` from `@playwright/test` library, which has retry logic built in.

```js
import { expect } from '@playwright/test';

async verifyFilter({ title }: { title: string }) {
  await expect(
    this.get().locator(`[data-testid="nc-fields-menu-${title}"]`).locator('input[type="checkbox"]')
  ).toBeChecked();
}
```

## Tips to avoid flakiness

* If an UI action, causes an API call or the UI state change, then wait for that API call to complete or the UI state to change.
* What to wait out can be situation specific, but in general, is best to wait for the final state to be reached, i.e. in the case of creating filter, while it seems like waiting for the filter API to complete is enough, but after its return the table records are reloaded and the UI state changes, so its better to wait for the table records to be reloaded.

## Accessing playwright report in the CI

* Open `Summary` tab in the CI workflow in github actions.
* Scroll down to `Artifacts` section.
* Access reports which suffixed with the db type and shard number(corresponding to the CI workerflow name). i.e `playwright-report-mysql-2` is for `playwright-mysql-2` workflow.
* Download it and run `pnpm install -D @playwright/test && npx playwright show-report ./` inside the downloaded folder.


# Repository structure
URL: /docs/product-docs/engineering/repository-structure

Repository Structure

We use `Lerna` to manage multi-packages. We have the following [packages](https://github.com/nocodb/nocodb/tree/master/packages).

* `packages/nocodb-sdk`: API client sdk of nocodb.

* `packages/nc-gui`: NocoDB Frontend.

* `packages/nc-lib-gui`: The build version of `nc-gui` which will be used in `packages/nocodb`.

* `packages/nocodb`: NocoDB Backend, hosted in [NPM](https://www.npmjs.com/package/nocodb).


# i18n translation
URL: /docs/product-docs/engineering/translation

Contribute to NocoDB's i18n translation













* NocoDB supports 30+ foreign languages & community contributions are now simplified via [Crowdin](https://crowdin.com/).

## How to add / edit translations ?

### Using GitHub

* For English, make changes directly to [en.json](https://github.com/nocodb/nocodb/blob/develop/packages/nc-gui/lang/en.json) & commit to `develop`
* For any other language, use `crowdin` option.

### Using Crowdin

* Setup [Crowdin](https://crowdin.com) account
* Join [NocoDB](https://crowdin.com/project/nocodb) project

<img alt="Crowdin Join Project" src={__img0} placeholder="blur" />

* Click the language that you wish to contribute

<img alt="Crowdin Select Language" src={__img1} placeholder="blur" />

* Click the `Translate` button; this opens up `Crowdin Online Editor`

<img alt="Crowdin Translate Button" src={__img2} placeholder="blur" />

* Select string in `English` on the left-hand menu bar \[1]
* Propose changes \[2]
* Save \[3]
  Note: Crowdin provides translation recommendation's as in \[4]. Click directly if it's apt

<img alt="Crowdin Online Editor" src={__img3} placeholder="blur" />

A GitHub Pull Request will be automatically triggered (periodicity- 6 hours). We will follow up on remaining integration work items.

#### Reference

Refer following articles to get additional details about Crowdin Portal usage

* [Translator Introduction](https://support.crowdin.com/crowdin-intro/)
* [Volunteer Translation Introduction](https://support.crowdin.com/for-volunteer-translators/)
* [Online Editor](https://support.crowdin.com/online-editor/)

## How to add a new language ?

#### GitHub changes

* Update enumeration in `enums.ts` \[packages/nc-gui/lib/enums.ts]
* Map JSON path in `a.i18n.ts` \[packages/nc-gui/plugins/a.i18n.ts]

#### Crowdin changes \[admin only]

* Open `NocoDB` project
* Click on `Language` on the home tab
* Select target language, `Update`
* Update array in `tests/playwright/tests/language.spec.ts`

<img alt="Crowdin Language Settings" src={__img4} placeholder="blur" />

<img alt="Crowdin Language Update" src={__img5} placeholder="blur" />

## String Categories

* **General**: simple & common tokens (save, cancel, submit, open, close, home, and such)
* **Objects**: objects from NocoDB POV (project, table, field, view, page, and such)
* **Title**: screen headers (compact) (menu headers, modal headers)
* **Lables**: text box/ radio/ field headers (few words) (Labels over textbox, radio buttons, and such)
* **Activity**/ actions: work items (few words) (Create Project, Delete Table, Add Record, and such)
* **Tooltip**: additional information associated with work items (usually lengthy) (Additional information provided for activity)
* **Placeholder**: placeholders associated with various textboxes (Text placeholders)
* **Msg**
  * Info: general/success category for everything
  * Error: warnings & errors
  * Toast: pop-up toast messages

> Note: string name should be in camelCase. Use above list as priority order in case of ambiguity.


# Writing unit tests
URL: /docs/product-docs/engineering/unit-testing

Overview to Unit Testing

## Unit Tests

* All individual unit tests are independent of each other. We don't use any shared state between tests.
* Test environment includes `sakila` sample database and any change to it by a test is reverted before running other tests.
* While running unit tests, it tries to connect to mysql server running on `localhost:3306` with username `root` and password `password` (which can be configured) and if not found, it will use `sqlite` as a fallback, hence no requirement of any sql server to run tests.

### Pre-requisites

* MySQL is preferred - however tests can fallback on SQLite too

### Setup

```bash
pnpm --filter=-nocodb install

# add a .env file
cp tests/unit/.env.sample tests/unit/.env

# open .env file
open tests/unit/.env
```

Configure the following variables

> DB\_HOST : host
> DB\_PORT : port
> DB\_USER : username
> DB\_PASSWORD : password

### Run Tests

```bash
pnpm run test:unit
```

### Folder Structure

The root folder for unit tests is `packages/nocodb/tests/unit`

* `rest` folder contains all the test suites for rest apis.
* `model` folder contains all the test suites for models.
* `factory` folder contains all the helper functions to create test data.
* `init` folder contains helper functions to configure test environment.
* `index.test.ts` is the root test suite file which imports all the test suites.
* `TestDbMngr.ts` is a helper class to manage test databases (i.e. creating, dropping, etc.).

### Factory Pattern

* Use factories for create/update/delete data. No data should be directly create/updated/deleted in the test.
* While writing a factory make sure that it can be used with as less parameters as possible and use default values for other parameters.
* Use named parameters for factories.
  ```ts
  createUser({ email, password})
  ```
* Use one file per factory.

### Walk through of writing a Unit Test

We will create an `Table` test suite as an example.

#### Configure test

We will configure `beforeEach` which is called before each test is executed. We will use `init` function from `nocodb/packages/nocodb/tests/unit/init/index.ts`, which is a helper function which configures the test environment(i.e resetting state, etc.).

`init` does the following things -

* It initializes a `Noco` instance(reused in all tests).
* Restores `meta` and `sakila` database to its initial state.
* Creates the root user.
* Returns `context` which has `auth token` for the created user, node server instance(`app`), and `dbConfig`.

We will use `createProject` and `createProject` factories to create a project and a table.

```typescript
let context;

beforeEach(async function () {
  context = await init();

  project = await createProject(context);
  table = await createTable(context, project);
});
```

#### Test case

We will use `it` function to create a test case. We will use `supertest` to make a request to the server. We use `expect`(`chai`) to assert the response.

```typescript
it('Get table list', async function () {
  const response = await request(context.app)
    .get(`/api/v1/db/meta/projects/${project.id}/tables`)
    .set('xc-auth', context.token)
    .send({})
    .expect(200);

  expect(response.body.list).to.be.an('array').not.empty;
});
```

<Callout type="info">
  We can also run individual test by using `.only` in `describe` or `it` function and the running the test command.
</Callout>

```typescript
it.only('Get table list', async () => {
```

#### Integrating the New Test Suite

We create a new file `table.test.ts` in `packages/nocodb/tests/unit/rest/tests` directory.

```typescript
import 'mocha';
import request from 'supertest';
import init from '../../init';
import { createTable, getAllTables } from '../../factory/table';
import { createProject } from '../../factory/project';
import { defaultColumns } from '../../factory/column';
import Model from '../../../../src/lib/models/Model';
import { expect } from 'chai';

function tableTest() {
  let context;
  let project;
  let table;

  beforeEach(async function () {
    context = await init();

    project = await createProject(context);
    table = await createTable(context, project);
  });

  it('Get table list', async function () {
    const response = await request(context.app)
      .get(`/api/v1/db/meta/projects/${project.id}/tables`)
      .set('xc-auth', context.token)
      .send({})
      .expect(200);

    expect(response.body.list).to.be.an('array').not.empty;
  });
}

export default function () {
  describe('Table', tableTests);
}
```

We can then import the `Table` test suite to `Rest` test suite in `packages/nocodb/tests/unit/rest/index.test.ts` file(`Rest` test suite is imported in the root test suite file which is `packages/nocodb/tests/unit/index.test.ts`).

### Seeding Sample DB (Sakila)

```typescript

function tableTest() {
  let context;
  let sakilaProject: Project;
  let customerTable: Model;

  beforeEach(async function () {
    context = await init();
    
    /******* Start : Seeding sample database **********/
    sakilaProject = await createSakilaProject(context);
    /******* End : Seeding sample database **********/
    
    customerTable = await getTable({project: sakilaProject, name: 'customer'})
  });

  it('Get table data list', async function () {
    const response = await request(context.app)
      .get(`/api/v1/db/data/noco/${sakilaProject.id}/${customerTable.id}`)
      .set('xc-auth', context.token)
      .send({})
      .expect(200);

    expect(response.body.list[0]['FirstName']).to.equal('MARY');
  });
}
```


# Writing docs
URL: /docs/product-docs/engineering/writing-docs

Overview to writing docs



This article discusses some of the protocol and conventions to be followed while writing docs.

## Folder Structure

* Docs follow object-oriented approach. Each folder represents an object and each file represents procedures associated with that object.
* Each folder contains an `meta.json` file which contains the metadata for that object.

```
{
  "title": "Engineering",
  "icon": "terminal",
  "pages": [
    "architecture",
    "repository-structure",
    "development-setup",
    "unit-testing",
    "playwright",
    "build-and-releases",
    "translations",
    "writing-docs"
  ]
}
```

## File Structure

* Add following metadata to the top of each file.

```
---
title: "Writing docs"
description: "Overview to writing docs"
tags: ['Engineering']
keywords: ['Engineering', Writing docs', 'Docs conventions']
---
```

* `title` is the title of the article that appears on the sidebar and on the top of the article.
* `description` is the description of the article that appears in search results.
* `tags` are the tags associated with the article. Tags are used to group articles together. For example, all articles with the tag `Workspaces` will be grouped together.
* `keywords` are the keywords associated with the article. Keywords are used to improve search results. For example, if the user searches for `Create workspace`, then the article with the keyword `Create workspace` will be displayed in the search results.

## Nomenclature

* Folder names & file name are
  * in kebab-case.
  * For example, `account-settings`.
* Only first letter of the folder/file name is capitalized. Second letter onwards, first letter is capitalized only if it is a proper noun.

## Tags

* First letter of each tag is capitalized.
* Tags usually are Objects or Actions. Add a tag only if we are sure that the tag will be used in multiple places. Example: 'Create' - we can have `Create project`, `Create user`, `Create API token` etc.

### Active Tags

Tags that are currently being used in the docs are listed below. See if you can reuse any of these tags before adding a new tag.

## Description

* Description should be crisp and to the point. Preferably one line.
* Refer to the description associated with the tag to get an idea of how the description should be.
* Descriptions appear in the search results (when searched by tags). So, it should be descriptive enough to give the user an idea of what the article is about.

<img alt="Search by tags" src={__img0} placeholder="blur" />

## Images

* Annotated images should be placed in `img/v2` folder.
* For every annotated image, there should be a corresponding unannotated image in the `img/v2-unannotated` folder.
* Images are kept in the same folder structure as the docs.
* Use `Skitch` for annotations.

## Before you commit

* Use `pnpm run build` to build the docs.
* Ensure that the build is successful & there are no errors/warnings related to missing links, images, etc.


# Bulk Update
URL: /docs/product-docs/extensions/bulk-update

Update multiple records in a table at once





## Overview

<img alt="Bulk Update" src={__img0} placeholder="blur" />

The Bulk Update extension empowers users to modify multiple records across a selected table view simultaneously. Instead of editing each row one by one, you can define field-level updates and apply them to all visible records with a single action—saving time and reducing manual errors.

<Callout type="warning">
  Bulk updates are irreversible. Ensure you review the changes before confirming the update.
</Callout>

## Updating Records

Follow these steps to update multiple records in a table:

1. Select the table and associated view you wish to update.
2. Click the **New Action** button.
3. Choose the **Field** you want to update.
4. Select an **Update Type**:
   * **Set Value**: Set a specific value for the field.
   * **Clear Value**: Clear the field value.
5. If you selected **Set Value**, provide the **Value** to be applied.
6. Click the **Update Records** button to apply the changes.
7. A confirmation dialog will display the number of fields and records to be updated. Review the details and click **Confirm Update** to proceed.

<img alt="Bulk Update" src={__img1} placeholder="blur" />

You can add multiple actions to update different fields in the table.

Bulk updates affect all records within the current view, including those not visible on the screen. Since views are just filtered representations of the same underlying data, any record that appears in multiple views will also reflect the update. These updates apply only to records in the selected view and do not impact records outside of it or in unrelated views.

## Managing Actions

The Update work items added are listed in the **Actions** section. You can:

* **Edit** an action by clicking on the action item in the list & making the necessary changes.
* **Delete** an action by clicking on the delete icon next to the action item.
* **Disable** an action by toggling the switch next to the action item. Disabling an action will prevent it from being applied to the records.

For any configured bulk update extension, you can reuse the **Update Records** button to repeat the batch update process. This is particularly useful when you need to apply the same changes across multiple records in the future.


# Data Exporter
URL: /docs/product-docs/extensions/data-exporter

Export data from NocoDB in various formats



## Overview

The `Data Exporter` extension is designed to simplify the process of exporting data from your NocoDB tables. With just a few clicks, you can effortlessly download CSV files for any specific table and view within your base. The download process is handled asynchronously in the background, ensuring that your application usage remains uninterrupted. Once your file is ready, you’ll receive a notification, allowing you to download the CSV into your local machine at your convenience.

## Exporting Data

Follow these steps to export data from your NocoDB tables:

1. Select the table and associated view you wish to export.
2. Configure optional settings for Separator and Encoding:
   * Default separator: Comma `,`
   * Other options: Semicolon `;`, Pipe `|` and `Tab`
3. Click the **Export** button.
4. Once the export is complete, the file will be listed in the **Recent Exports** section.
5. Click the **Download** button to save the CSV file to your local device.

<Callout type="note">
  Separator and Encoding configurations are only accessible from the expanded extension panel.
</Callout>

<img alt="Data Exporter" src={__img0} placeholder="blur" />

## Managing Exports

The files exported have a limited lifespan and are automatically removed after 6 hours. The files listed under the **Recent Exports** section are only visible to you and are not shared with other users. You can manage your exports by downloading or removing them as needed.

### Downloading Exports

1. In the Recent Exports section, locate the desired file.
2. Click the Download icon next to the file to save it to your device.

### Removing Exports

1. Locate it in the Recent Exports section.
2. Click the `x` icon to remove it from the list.


# Dedupe
URL: /docs/product-docs/extensions/dedupe

Identify and merge duplicate records in a table













## Overview

<img alt="Dedupe" src={__img0} placeholder="blur" />

The Dedupe extension helps you identify and merge duplicate records in a table using one or more fields for grouping. Instead of manually scanning and comparing records, Dedupe detects groups of records with matching values across the selected fields and provides a guided interface to review, select, and merge them into a single primary record.

This extension is especially useful for maintaining clean datasets such as contacts, leads, or inventories where duplicate entries are common.

<Callout type="warning">
  Merging duplicate records is irreversible. Once records are merged, deleted records cannot be restored.
</Callout>

***

## Finding Duplicate Records

Follow these steps to detect duplicate records:

1. Select the **Table** you want to scan for duplicates. Optionally, you can also select a specific **View** within that table to limit the scope of the records being analyzed.
2. Select one or more **Field(s)** to group records by. You can choose multiple fields from the dropdown to define more granular deduplication criteria.
3. Dedupe identifies groups where **two or more records** share the same values across all the selected fields.
4. Each group is presented for review one at a time.

<img alt="Dedupe Find Duplicates" src={__img1} placeholder="blur" />

***

## Resolving Duplicate Records

For each duplicate group, review and merge records as follows:

1. Select **one primary record** to keep.
2. If a record shown in the group is not actually a duplicate, **exclude** it. Excluded records are not merged and not deleted.
3. Optionally, for each field - click a value from any record to copy it into the primary record.
4. Once satisfied, proceed to merge the group.

When the merge is completed:

* The primary record is retained with its original primary key.
* Selected field values are copied into the primary record.
* All non-excluded duplicate records in the group are permanently deleted.

<img alt="Dedupe Review" src={__img2} placeholder="blur" />
<img alt="Dedupe Review - Field Selection" src={__img3} placeholder="blur" />
<img alt="Dedupe Merge" src={__img4} placeholder="blur" />

***

## Field Behavior During Merge

All editable fields are displayed except the grouping field(s) & system fields (e.g. `id`, `created_at`, `updated_at`). Virtual fields (Formula, Lookup, Rollup) are shown for reference as these cannot be edited directly. Record ID of the primary record is always retained. Modified timestamps are updated automatically.

When merging, field values are handled as follows:

* If you select a value from any record for a field, that value is copied into the primary record.
* If no value is selected for a field, the primary record's existing value remains unchanged.

***

## Group Review Actions

While reviewing duplicate groups, you can:

* **Skip group**
  Move to the next duplicate group without making any changes.

* **Reset**
  Clear all selections for the current group (primary record, field selections, exclusions) and start over.

<img alt="Dedupe Actions" src={__img5} placeholder="blur" />

You can skip a group before selecting a primary record, or reset even after making selections.

***

## Supported Field Types

**Supported for duplicate detection**

* Text, LongText, SingleLineText
* Number, Decimal, Currency, Percent, Duration, Rating
* Date, DateTime, Time, Year
* Phone, Email, URL
* SingleSelect, MultiSelect
* Checkbox
* Attachment
* JSON, Geometry
* User
* Links & LinkToAnotherRecord (LTAR): many-to-many, belongs-to-one

**Not supported**

* Links & LinkToAnotherRecord (LTAR): has-many, one-to-one

***

## Key Notes

* Duplicate detection supports **single-field or multi-field grouping**
* When multiple fields are selected, records must match on **all** selected fields to be grouped as duplicates
* At least **two matching records** are required per group
* Undo / Redo is not supported
* Deleted records cannot be restored

The Dedupe extension provides a controlled and efficient way to clean up duplicate data while giving you full visibility and control over what gets merged and removed.

***


# Extensions
URL: /docs/product-docs/extensions

Overview of the extensions available in NocoDB







<Callout type="note">
  The Extensions feature is available on NocoDB cloud and on-premise licensed deployments.
</Callout>

Extensions are modular components designed to expand and customize your experience with NocoDB. Functioning like plugins, extensions introduce new features and functionalities beyond the platform's core capabilities, allowing users to adapt NocoDB to suit unique requirements and workflows.

This section provides an overview of the Extensions framework, detailing how to install, manage, and utilize extensions to optimize your NocoDB base.

* [Extension Marketplace](#extensions-marketplace)

* [Adding Extensions](#adding-extensions)

* [Managing Extensions](#managing-extensions)

Extensions can be developed using JavaScript and Vue.js, offering a flexible approach to adding new features to your NocoDB instance. The ability to develop custom extensions will be available soon, allowing you to tailor NocoDB to meet specific needs and workflows. Stay tuned for more updates!

The Extensions side panel can be toggled using the `Extensions` button located in the top-right corner of the NocoDB interface.

<img alt="Extensions side panel" src={__img0} placeholder="blur" />

## Extensions Marketplace

The Extensions Marketplace is a centralized hub where you can explore, discover, and install extensions to enhance your NocoDB experience.

The following extensions are currently available in the marketplace:

* [Data Exporter](/docs/product-docs/extensions/data-exporter)
* [Upload Data from CSV](/docs/product-docs/extensions/upload-data-from-csv)
* [URL Preview](/docs/product-docs/extensions/url-preview)
* [World Clock](/docs/product-docs/extensions/world-clock)
* [Page Designer](/docs/product-docs/extensions/page-designer)
* [Bulk Update](/docs/product-docs/extensions/bulk-update)

Note that, the ability to develop custom extensions is not supported currently.

## Adding Extensions

To add an extension to your NocoDB instance, open extensions side panel and follow these steps:

1. Click the `Add Extension` button in the Extensions side panel.
2. Click the `Add` button to add the extension to your NocoDB instance. You can also click on the extension card to view more details about the extension.

<Callout type="info">
  * The extensions installed are specific to the base and are not shared across workspace.
  * Multiple instances of the same extension can be added to a base.
</Callout>

<img alt="Add Extension-1" src={__img1} placeholder="blur" />
<img alt="Add Extension-2" src={__img2} placeholder="blur" />

## Managing Extensions

After installing an extension, you can manage it using the following options:

### 1. Adjust Visibility

Use the `expand` icon to view the extension in full screen mode.

<img src="/img/v2/extensions/expand.png" alt="Extension visibility" width="480" />

### 2. Reorder Extensions

Use the `drag-drop` icon to reorder the extensions in the side panel.

<img src="/img/v2/extensions/reorder.png" alt="Reorder" width="480" />

### 3. Additional Actions

Use the `More` button to perform the following actions:

* Rename extension
* Duplicate extension
* Clear data
* Delete extension

<img src="/img/v2/extensions/more-actions.png" alt="more-actions" width="480" />


# Org Chart
URL: /docs/product-docs/extensions/org-chart

Display an organization chart based on your data

## Overview

The Org Chart extension in NocoDB allows you to visualize hierarchical data in the form of an organization chart. This extension is particularly useful for displaying relationships within teams, departments, or any other hierarchical structure based on your data.


# Page Designer
URL: /docs/product-docs/extensions/page-designer

Create printable and shareable layouts from your database records



## Overview

<img alt="Page Designer" src={__img0} placeholder="blur" />

The **Page Designer** extension allows users to create printable and shareable (PDF) visual layouts from their database records. Common use cases include generating invoices, reports, certificates, and summaries—by combining text, images, and dynamic field data in a freeform design canvas.

This feature is ideal for teams who want to convert structured table data into branded, formatted documents directly within NocoDB.

## Key Features

* **Drag-and-drop Builder**: Add text, images, tables, and dividers to customize your page layout.
* **Record-specific Rendering**: Auto-populates fields dynamically from the selected record.
* **Supports Linked Records**: Render data from related tables in a tabular, list, or inline format.
* **Full Design Control**: Modify font, alignment, borders, colors, and more for each element.
* **Print & PDF Export**: Preview your design and export directly to PDF.

## How to Access

To get started:

1. Open **Page Designer** from the **Extensions** menu in your NocoDB instance.
2. Choose the target **table** and **view** from which records will be pulled.
3. Select a specific **record** to preview and design the layout interactively.

## Designing Your Page

The canvas on the left shows a preview of your document layout. Use the sidebar on the right to add and arrange elements.

### Add Elements

Add components to your layout by dragging them onto the canvas:

| Element   | Description                                          |
| --------- | ---------------------------------------------------- |
| 🅰️ Text  | Add static or dynamic text (linked to table fields). |
| 🖼️ Image | Add image blocks, such as logos or banners.          |
| ➖ Divider | Insert horizontal lines for visual separation.       |

### Bind Field Data

Under **Field Elements**, you can drag and drop database fields onto the canvas. Once dropped into the canvas, these fields will auto-populate with values from the selected record. You can also format these fields using the sidebar options (font size, color, alignment, etc.).

##### Field Configuration

For most field types, you can configure:

| Setting          | Description                                         |
| ---------------- | --------------------------------------------------- |
| Font settings    | Customize font family, size, line height, and color |
| Alignment        | Set horizontal and vertical alignment               |
| Border & Radius  | Add borders and set corner radius                   |
| Background color | Set background color for the field                  |

### Linked Records

The **Linked Records** section allows you to display related table data using three formats:

* **Inline**: Display as plain text.
* **List**: Show entries in a vertical list.
* **Table** : Render fields from the related table as a structured table with columns and rows.

For linked records displayed in tabluar format, you can choose which fields to display and customize their visibility.

##### Table Configuration

| Column                | Options                                             |
| --------------------- | --------------------------------------------------- |
| Enable/Disable fields | Toggle visibility per field                         |
| Font settings         | Customize font family, size, line height, and color |
| Table Header styling  | Set separate font size and line height for headers  |
| Background color      | Set background color for the table                  |

## Record Preview

Use the **Record selector** in the sidebar to toggle between different records and preview how the design looks with real data.

## Page Settings

* **Page Name**: Customize the name of your page for easy reference. This name will be used when exporting or printing.
* **Print / Export**: Use the print icon in the top-right corner to generate PDFs or physical printouts.

## Key Use Cases

* 🧾 Invoices & Quotes
* 📄 Client Reports & Status Sheets
* 🎓 Certificates & Badges
* 📊 Internal Summaries for review meetings

## Limitations (Beta)

* The Page Designer is currently in **Beta**—minor rendering issues may occur in some browsers. Help us improve by reporting any bugs you encounter and any suggestions you have to improve the experience.

***


# Upload data from CSV
URL: /docs/product-docs/extensions/upload-data-from-csv

Import data from CSV files into NocoDB



## Overview

The `Upload data from CSV` extension in NocoDB allows users to import data from CSV files directly into existing tables. This tool enables you to efficiently add new records, update existing ones, and map CSV columns to NocoDB fields with precision.

## Importing Data

### Modes of Import

The Import CSV Extension supports two modes of data import:

  **1. Add Records**: Import all records from the CSV file as new entries in the selected table. No existing records are modified.

  **2. Merge Records**: Update existing records based on a designated **merge field** (a unique field used for matching) while optionally adding new records. The available options under this mode are:

* *Create New Records Only*
  * Only adds new records from the CSV. Existing records are not updated. New records are identified based on the merge field specified.
* *Update Existing Records Only*
  * Only updates records that already exist in the table based on the merge field. New records are not added.
* *Create and Update Records*
  * Adds new records and updates existing ones as needed, based on the merge field.

**Merge Field:** The merge field is the key field used to match records in the CSV file with those in the NocoDB table for updating purposes. Typically, this is the Primary Key or another unique identifier. Composite keys are not supported.

**Field Mapping:** Easily map CSV columns to corresponding fields in the NocoDB table. You have the flexibility to import only the fields you need.

### Steps to Import

Follow these steps to import data from a CSV file into NocoDB:

1. Drag and drop or upload your CSV file into the Import CSV Extension area.
2. Select the table you want to import the data into. By default, current active table is selected.
3. Choose the mode of import:
   * **Add Records** or
   * **Merge Records** with one of the following **Import Types**:
     * *Create New Records Only*
     * *Update Existing Records Only*
     * *Create and Update Records*
4. Set the **Merge Field** (for Merge Records mode): Select the field that will be used to match CSV records with existing table records.
5. **Use first record as header**: If the first row of the CSV file contains the column headers, enable this option to use them as the field names.
6. Map the columns from the CSV file to the corresponding fields in the NocoDB table.
7. Click the **Import** button to start the import process.

<img alt="Import CSV" src={__img0} placeholder="blur" />

### Post-Import Summary

Once the import is complete, NocoDB will display a summary detailing:

* The number of new records added
* The number of existing records updated
* Any records left unchanged

This streamlined process ensures your data is imported accurately and efficiently.


# URL Preview
URL: /docs/product-docs/extensions/url-preview

Preview URLs in NocoDB



## Overview

The URL Preview extension in NocoDB allows you to preview URLs directly within your NocoDB instance. This feature is particularly useful when you need to quickly view the content of a URL without leaving your workspace. This extension enhances the data visualization capabilities of NocoDB by providing rich, contextual previews for supported online platforms and services.

## Previewing URLs

To preview a URL in NocoDB, just select a cell from the URL field. A preview of the URL content will be displayed in the extension sub-panel, allowing you to view the content without navigating away from your workspace.

<img alt="URL Preview" src={__img0} placeholder="blur" />

## Supported Platforms

The URL Preview Extension currently supports the following platforms:

### 📽️ Media & Social

* YouTube
* Vimeo
* SoundCloud
* Spotify
* Twitter
* Dailymotion
* Behance
* TED

### 💼 Productivity & Collaboration

* Google Docs
* Google Sheets
* Google Slides
* Google Drive share links
* Loom share links

### 🧑‍💻 Design & Development

* GitHub (Gists)
* CodePen
* CodeSandbox (Embed url)
* JSFiddle
* StackBlitz
* Figma
* Notion


# World Clock
URL: /docs/product-docs/extensions/world-clock

Display multiple time zone clocks with in NocoDB

## Overview

The World Clock extension in NocoDB allows you to display multiple time zone clocks within your NocoDB instance. This feature is particularly useful when you need to track time across different regions or collaborate with team members in different time zones. The extension enhances the user experience by providing a visual representation of time zones, making it easier to manage global operations and schedules.

<img src="/img/v2/extensions/world-clock-2.png" alt="Analog" width="380" />

<img src="/img/v2/extensions/world-clock-1.png" alt="Digital" width="420" />

### Adding Clock

To add a clock, expand World clock extension, click `+ Add City` and select City from the dropdown available. You can add a maximum of 4 clocks per instance of an extension.

* **Clock Name**: Enter a name for the clock to identify it easily. It defaults to the selected City name.
* **Theme**: Choose one amongst the available themes for the clock display.

### Clock Display Settings

The following are the global settings that will be applied to all the clocks configured.

* **Clock Type**: Choose between **Analog**, **Digital**, or **Both** for the display format.
* **Show Numbers**: For analog clocks, you can additionally configure if hour numbers are to be displayed on the clock dial.
* **Time Format**: Choose between 12H and 24H format for the clock display.


# Actions on field
URL: /docs/product-docs/fields/actions-on-field

This article explains how to perform various actions on a field- like rename, change field type, default, field width, record height, show/hide.



















## Fields context menu

Fields context menu can be accessed by clicking on the dropdown icon (🔽) next to the field name.\
<img alt="Fields context menu" src={__img0} placeholder="blur" />

### Edit

#### Rename field

1. Open the field context menu
2. Click on `Edit` option.
3. Enter new field name as required in the `Field Name` field.
4. Click on `Save Field` button.

<img alt="Rename field" src={__img1} placeholder="blur" />

#### Change field type

1. Open the field context menu
2. Click on `Edit` option.
3. Select new field type from the `Field Type` dropdown.
4. Click on `Save Field` button.

<img alt="Change field type" src={__img2} placeholder="blur" />

#### Change default value

1. Open the field context menu
2. Click on `Edit` option.
3. Enter new default value in the `Default Value` field. To disable, click on `x` icon.
4. Click on `Save Field` button.

<img alt="Change default value" src={__img3} placeholder="blur" />

### Change field width

To adjust the width of the field, hover over the field edge and drag to adjust the width.

<img alt="Change field width" src={__img4} placeholder="blur" />

### Hide field

1. Open the field context menu
2. Click on `Hide Field` option

<Callout type="note">
  * Hidden fields are not visible in the table view, but will still be accessible for Formulas, Sort, Filter, etc.
  * To un hide a field, use `Toolbar > Fields` menu
  * Fields can also be marked as hidden from `Toolbar > Fields` menu
</Callout>

### Set as Display value

1. Open the field context menu
2. Click on `Set as Display Value` option.

Refer to [Display Value](/docs/product-docs/fields/display-value) for more details.

### Sort Ascending

1. Open the field context menu
2. Click on `Sort Ascending` option.

### Sort Descending

1. Open the field context menu
2. Click on `Sort Descending` option.

### Duplicate field

1. Open the field context menu
2. Click on `Duplicate` option.

Duplicated field sans the data will be created with suffix `_copy` in its name & will be placed to the right of the original field.

### Insert after a field

1. Open the field context menu
2. Click on `Insert after` option.

New field will be created to the right of the original field.

### Insert before a field

1. Open the field context menu
2. Click on `Insert before` option.

New field will be created to the left of the original field.

### Delete field

<Callout type="info">
  **This action cannot be undone**
</Callout>

To delete a field, follow the steps below:

1. Open the field context menu by clicking on dropdown icon (🔽) .
2. Click on **Delete**.
3. Confirm the deletion by clicking on **Delete Field** on the confirmation modal.

### Add / edit field description

Field description can be added by clicking on the `Add Description` button on the field creation modal or by clicking on the `Edit Description` button from the field context menu.

<img alt="add field description" src={__img5} placeholder="blur" />
<img alt="edit field description" src={__img6} placeholder="blur" />

Description for a field will be visible as a tooltip when hovering over the `info` icon next to the field name.

<img alt="Field description" src={__img7} placeholder="blur" />

### Set field as unique

To set a field as unique, follow the steps below:

1. Open the field context menu by clicking on dropdown icon (🔽) .
2. Click on **Edit field**.
3. Toggle on the **Unique values only** option.
4. Click on **Save Field** button.

<img alt="Set field as unique" src={__img8} placeholder="blur" />

Note that, this feature is only available for certain field types like Single line text, Email, Number, etc. Find more details on setting a field as unique in [Unique Fields](/docs/product-docs/fields#unique-fields-) article.


# Display Value
URL: /docs/product-docs/fields/display-value

This article explains how to set the display value for a table and its significance.





The **Display Value** serves as the primary visual identifier for a record within a table. It helps users quickly recognize and associate records across views and linked tables. While it is often recommended to set a display value based on a field with unique identifiers (like a primary key), uniqueness is not enforced at the database level.

<div style={{ textAlign: 'center' }}>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/GAPAec6zXQ8?start=13" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</div>

***

## Use of Display Value

* In the spreadsheet view, the display value is visually emphasized to make it easier to identify the record you’re working with.
* When creating **Links** between tables, the display value is shown in the **Linked Records** modal, making cross-table relationships more readable and intuitive.

**Example: Display Value highlighted in the Actor table**
<img alt="display value" src={__img0} placeholder="blur" />

**Example: Display Value shown in a Links field.**
The value shown in the **Link Records** modal is pulled from the related table's display value.
<img alt="display value- links field" src={__img1} placeholder="blur" />

***

## Set Display Value

To set a field as the display value:

1. Click the dropdown icon (🔽) next to the desired field.
2. Select **Set as display value** from the menu.

<div style={{ textAlign: 'center' }}>
  <img src="/img/v2/fields/set-as-display-value.png" alt="Set as display value" style={{ width: '80%', maxWidth: '480px' }} />
</div>

***

## FAQ

**How is the Display Value determined for existing database tables?**
For tables connected from external databases, NocoDB automatically selects the display value based on the table structure. By default, it picks the first non-numeric field after the primary key. If no non-numeric field is found, it selects the next field after the primary key.

**Can I change the Display Value later?**
Yes. You can change the display value at any time by using the context menu on the target field. [Learn more →](/docs/product-docs/fields/display-value#set-display-value)

***


# Field summary
URL: /docs/product-docs/fields/field-summary-footer

Understanding the field summary bar in NocoDB!



The "Field Summary" provides quick calculations for chosen fields displayed in the footer of a table's grid view. These calculations offer quick insights into your data, such as total sums, averages, minimum, and maximum values. This section explains how to use & configure field summary to accurately compute these values.

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/VzmzvLST_dk?si=VVd40nh-7YSNUGaQ&start=14" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

## Overview

Field Summary is aggregated value computed by considering all the rows present in a grid view. The resulting values are displayed in the summary cells at the bottom of the field for easy reference. Filters configured on the grid, if any will affect the rows displayed & hence the summary as well.

Please note that it is not possible to reference these aggregated values directly in other parts of the table.

When a grid view is **shared publicly**, the summary  is also visible to the viewers. Viewers of shared view can also modify the field summary configuration to suit their needs, but the changes are not saved (revert upon page refresh).

Summary configurations are grid **view specific**. Multiple grid views can be created for a table, and each grid view can have its own summary configuration.

## Configuring Field Summary

By default, the summary is disabled for all fields. To enable the summary for a field, follow these steps:

Navigate to the grid view of the table you wish to configure the field summary for.

1. Click on the cell of the field you wish to configure the summary for.
2. Select the desired summary type from the dropdown list.

<img alt="Access" src={__img0} placeholder="blur" />

Changes to the grid view immediately update the values displayed in the footer cells. To disable the summary for a field, click on the summary cell and select "None" from the dropdown list.

## Summary Types

Summary function types available for configuration depend on the field type. General functions listed below are available for most of the field types:

### General

* **Empty**: Count of empty cells in the field.
* **Filled**: Count of non-empty cells in the field.
* **Unique**: Count of unique values in the field.
* **Percent Empty**: Percentage of empty cells in the field.
* **Percent Filled**: Percentage of non-empty cells in the field.
* **Percent Unique**: Percentage of unique values in the field.

Apart from these general functions, specific functions are available for different field types:

### Numeric

* **Sum**: Sum of all numeric values in the field.
* **Minimum**: Minimum value in the field.
* **Maximum**: Maximum value in the field.
* **Average**: Average of all numeric values in the field.
* **Median**: Median of all numeric values in the field.
* **Standard Deviation**: Standard deviation of all numeric values in the field.
* **Range**: Range of all numeric values in the field.

### Date

* **Earliest Date**: Earliest date in the field.
* **Latest Date**: Latest date in the field.
* **Date Range**: Range of dates in the field.
* **Month Range**: Range of months in the field.

### Checkbox

* **Checked**: Count of checked checkboxes in the field.
* **Unchecked**: Count of unchecked checkboxes in the field.
* **Percent Checked**: Percentage of checked checkboxes in the field.
* **Percent Unchecked**: Percentage of unchecked checkboxes in the field.

### Attachment

* **Attachment Size**: Total size of attachments in the field.

<Callout type="note">
  Summary configuration is not available for `DB specific field` types.
</Callout>


# Fields
URL: /docs/product-docs/fields

This article discusses various field types that NocoDB offers.









Fields define the structure and type of data stored in each record of a table. They are the building blocks of your database, determining how information is entered, displayed, and interpreted. Whether you're capturing names, numbers, dates, selections, or calculated values—fields provide the necessary flexibility to model your data accurately.

This section will guide you through the different types of fields available, their configurations, and best practices for choosing the right field type based on your use case. By understanding how fields work, you can design more effective tables and ensure consistent, meaningful data across your workspace.

<img alt="image" src={__img0} placeholder="blur" />

Among all fields in a table, two hold special significance: the **[primary key](/docs/product-docs/fields/primary-key)** and the **[display value](/docs/product-docs/fields/display-value)**. The **primary key** is a technical identifier that uniquely distinguishes each record and is essential for backend operations like updates, deletions, and maintaining data integrity. It is always unique and typically hidden from end users. On the other hand, the **display value** is a human-readable label—such as a name or title—used in the interface to help users quickly identify and associate records. While it’s recommended to use a field with unique values as the display value, strict uniqueness is not enforced. In essence, the primary key ensures consistent record management, while the display value improves usability and context.

## Create a Field

To add a new field to your table:

1. Click on the ➕ icon in the table header where you'd like to insert the new field.
2. In the **New Field** panel:
   * Enter the field name (optional at first).
   * Select the appropriate **field type** from the list (e.g., Single line text, Number, Lookup, etc.).
3. Configure additional settings such as default value and description as needed.
4. Unique constraints can be enabled for supported field types by checking the **Unique values only** option. More details can be found in the [Unique Fields](#unique-fields-) section below.
5. Click **Save Field** to finalize the creation.

<div style={{ textAlign: 'center' }}>
  <img src="/img/v2/fields/create-field-1.png" alt="Create new field - select type" style={{ width: '90%', maxWidth: '800px' }} />
</div>

<div style={{ textAlign: 'center', marginTop: '1rem' }}>
  <img src="/img/v2/fields/create-field-2.png" alt="Configure field details" style={{ width: '90%', maxWidth: '400px' }} />
</div>

<Callout type="note">
  You can edit the field name, type, default value, or description anytime using the field’s context menu.
</Callout>

Depending on the field type selected, additional options or configurations may be required—such as allowed values, precision, formulas, or linked table settings. Refer to the documentation for each field type for detailed guidance.

## Field Default Value

You can set a default value when creating a field. This value is automatically applied to new records created after the field is set. It does not affect existing records. The default can be a fixed value (e.g., "N/A", "Unknown") or, for some field types, a dynamic value such as the current date, time, or user ID. Refer [Set default value](/docs/product-docs/fields/actions-on-field#change-default-value) for more details on how to configure default values.

## Field Description

<img alt="Field description" src={__img1} placeholder="blur" />

Adding a description to a field provides context and guidance for users interacting with the table. This is especially useful in collaborative environments where multiple users may access the same data. The description can include details about the field's purpose, expected values, or any specific instructions for data entry. It appears as a tooltip when users hover over `i` icon next to the field name in the table header. For more details, refer to [Add/Edit Field Description](/docs/product-docs/fields/actions-on-field#add--edit-field-description).

<Callout type="info">
  You can also search for fields using their names or descriptions. This helps quickly locate specific fields, especially in larger tables with many columns.
</Callout>

<img alt="Field search" src={__img2} placeholder="blur" />

## Field Types

NocoDB offers a wide range of field types to help you structure your data effectively. From basic text and numeric fields to more advanced options like linked records, formulas, and custom types, each field serves a specific purpose. The table below provides an overview of all available field types along with brief descriptions to help you choose the right one for your use case.

| Field Type       | Name                                                                                                    | Description                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Text based**   | [Single line text](https://nocodb.com/docs/product-docs/fields/field-types/text-based/single-line-text) | For short text entries like names or titles.             |
|                  | [Long text](https://nocodb.com/docs/product-docs/fields/field-types/text-based/long-text)               | Suitable for paragraphs or detailed notes.               |
|                  | [Email](https://nocodb.com/docs/product-docs/fields/field-types/text-based/email)                       | Stores and validates email addresses.                    |
|                  | [Phone](https://nocodb.com/docs/product-docs/fields/field-types/text-based/phonenumber)                 | For storing phone numbers.                               |
|                  | [URL](https://nocodb.com/docs/product-docs/fields/field-types/text-based/url)                           | Stores website or web resource links.                    |
| **Numerical**    | [Number](https://nocodb.com/docs/product-docs/fields/field-types/numerical/number)                      | Whole numbers, positive or negative.                     |
|                  | [Decimal](https://nocodb.com/docs/product-docs/fields/field-types/numerical/decimal)                    | Numbers with decimal precision.                          |
|                  | [Percentage](https://nocodb.com/docs/product-docs/fields/field-types/numerical/percent)                 | Represents numeric values as percentages.                |
|                  | [Currency](https://nocodb.com/docs/product-docs/fields/field-types/numerical/currency)                  | Stores monetary values with currency symbol.             |
| **Date & Time**  | [Date](https://nocodb.com/docs/product-docs/fields/field-types/date-time-based/date)                    | Captures calendar dates.                                 |
|                  | [Time](https://nocodb.com/docs/product-docs/fields/field-types/date-time-based/time)                    | Stores time of day.                                      |
|                  | [Date and time](https://nocodb.com/docs/product-docs/fields/field-types/date-time-based/date-time)      | Stores both date and time in one field.                  |
|                  | [Duration](https://nocodb.com/docs/product-docs/fields/field-types/date-time-based/duration)            | Measures length of time (e.g., hours or days).           |
| **Select based** | [Single select](https://nocodb.com/docs/product-docs/fields/field-types/select-based/single-select)     | Allows choosing one option from a list.                  |
|                  | [Multi select](https://nocodb.com/docs/product-docs/fields/field-types/select-based/multi-select)       | Allows selecting multiple options from a list.           |
| **Link based**   | [Links](https://nocodb.com/docs/product-docs/fields/field-types/links-based/links)                      | Creates relationships between tables.                    |
|                  | [Lookup](https://nocodb.com/docs/product-docs/fields/field-types/links-based/lookup)                    | Pulls data from linked records.                          |
|                  | [Rollup](https://nocodb.com/docs/product-docs/fields/field-types/links-based/rollup)                    | Aggregates values from related records.                  |
| **Custom types** | [Attachment](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/attachment)           | Upload and store files or images.                        |
|                  | [Barcode](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/barcode)                 | Stores and displays barcodes.                            |
|                  | [QR-code](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/QR-code)                 | Stores and displays QR codes.                            |
|                  | [Geometry](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/geometry)               | For geographic or spatial data.                          |
|                  | [GeoData](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/geodata)                 | Stores latitude and longitude coordinates.               |
|                  | [JSON](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/json)                       | Stores structured data in JSON format.                   |
|                  | [Checkbox](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/checkbox)               | Boolean toggle for true/false values.                    |
|                  | [Rating](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/rating)                   | Displays star-based or numeric rating.                   |
|                  | [Colour](https://nocodb.com/docs/product-docs/fields/field-types/custom-types/colour)                   | Displays colour swatch & corresponding Hex code.         |
| **Identifier**   | [UUID](https://nocodb.com/docs/product-docs/fields/field-types/identifier-types/uuid)                   | Auto-generates globally unique identifiers (UUID v4).    |
|                  | [Auto Number](https://nocodb.com/docs/product-docs/fields/field-types/identifier-types/auto-number)     | Auto-generates sequential numbers for each record.       |
| **Formula**      | [Formula](https://nocodb.com/docs/product-docs/fields/field-types/formula/formula)                      | Computes values using expressions based on other fields. |

***

## Unique Fields ☁

<Callout type="info">
  Feature available in Business and Enterprise plans.
</Callout>

Certain field types in NocoDB can be configured to enforce uniqueness, ensuring that no two records contain the same non-empty value for that field. This is especially useful for fields such as email addresses, usernames, or other identifiers that must remain distinct across records. When enabled, empty cells are permitted, while duplicate non-empty values are prevented. You can enable this behavior by selecting the **Unique values only** option in the field settings during field creation or editing. Once configured, NocoDB validates all new entries and updates to enforce the uniqueness constraint.

<img alt="Unique field setting" src={__img3} placeholder="blur" />

When a user attempts to enter a duplicate value in a unique field, NocoDB will display an error message and prevent the record from being saved until a unique value is provided.

Supported field types for uniqueness enforcement include:

* Single line text
* Email
* Phone number
* URL
* Number
* Decimal
* Currency
* Percent
* DateTime
* Date
* Time

<Callout type="note">
  - Enforcing uniqueness can impact performance on large datasets. Enable this option only when required by your application.
  - Uniqueness constraints are supported only for tables created within NocoDB (NC-DB). Fields from external database tables do not support uniqueness constraints via NocoDB.
  - When converting an existing field to a unique field, all existing values must already be unique; otherwise, the conversion will fail.
  - Default values and uniqueness constraints are mutually exclusive. A field marked as unique cannot have a default value.
  - Empty values are allowed in unique fields and do not violate the uniqueness constraint.
</Callout>

## Field Actions

Beyond selecting the right field type, you can also perform various actions to customize how fields behave and appear in your tables. These actions are accessible from the field’s context menu & toolbar menu and include:

* [Rename a field](/docs/product-docs/fields/actions-on-field#rename-field)
* [Change field type](/docs/product-docs/fields/actions-on-field#change-field-type)
* [Set default value](/docs/product-docs/fields/actions-on-field#change-default-value)
* [Adjust field width](/docs/product-docs/fields/actions-on-field#change-field-width)
* [Hide or unhide fields](/docs/product-docs/fields/actions-on-field#hide-field)
* [Set as display value](/docs/product-docs/fields/actions-on-field#set-as-display-value)
* [Sort by field (ascending/descending)](/docs/product-docs/fields/actions-on-field#sort-ascending)
* [Duplicate a field](/docs/product-docs/fields/actions-on-field#duplicate-field)
* [Insert new field before or after](/docs/product-docs/fields/actions-on-field#insert-before-a-field)
* [Delete a field](/docs/product-docs/fields/actions-on-field#delete-field)
* [Add or edit field description](/docs/product-docs/fields/actions-on-field#add--edit-field-description)

For step-by-step instructions and visuals, refer to the full guide on [Actions on Field](/docs/product-docs/fields/actions-on-field).

***


# Multi-field editor
URL: /docs/product-docs/fields/multi-fields-editor

Understanding use of multi-field editor in NocoDB!















NocoDB offers a handy tool for easily managing the fields within a table. With this tool, you can add, modify, rename, arrange, or hide fields efficiently. It's particularly useful when creating a new table structure or making changes to an existing one.

## Accessing the Multi-Field Editor

1. Navigate to the table you wish to edit
2. Click on `Details` in the navbar
3. Select `Fields` tab

<img alt="Access" src={__img0} placeholder="blur" />

## Adding fields

On the Multi-field editor page,

1. Click on `Add Field` button to add a new field.
2. Enter the field name and select the field type; configure default value (optional).
3. Field will be added to the end of the list. You can reorder the fields as needed. You can add / update multiple fields in one go & save all at once.
4. Click `Save changes` button to save the changes.

<img alt="Add field" src={__img1} placeholder="blur" />

<Callout type="tip">
  * You can add / update/ delete multiple fields & save changes in one go.
  * Use `Restore` to discard edits to a particular field. Use `Reset` to discard all active changes on multi-field editor.
</Callout>

## Editing fields

On the Multi-field editor page,

1. Click on the field you wish to edit.
2. Make the necessary changes in the `Edit Field` modal. You can update the field name, type, default value, and other attributes.
3. Updates to the field are recorded in the fields list view. You can add / update multiple fields in one go & save all at once.
4. Click `Save changes` button to save the changes.

<img alt="Edit field" src={__img2} placeholder="blur" />

<Callout type="tip">
  * You can add / update/ delete multiple fields & save changes in one go.
  * Use `Restore` to discard edits to a particular field. Use `Reset` to discard all active changes on multi-field editor.
</Callout>

## Deleting fields

On the Multi-field editor page,

1. Hover over the field you wish to delete, select `...` icon to open context menu
2. Click on `Delete` option to delete the field.
3. Deletions in the table are recorded in the fields list view. You can delete multiple fields in one go & save all at once.
4. Click `Save changes` button to save the changes.

After all the changes are made, click `Save changes` button to save the changes.

<img alt="Delete field" src={__img3} placeholder="blur" />

<img alt="Delete field" src={__img4} placeholder="blur" />

<Callout type="tip">
  * You can add / update/ delete multiple fields & save changes in one go.
  * Use `Restore` to discard edits to a particular field. Use `Reset` to discard all active changes on multi-field editor.
</Callout>

## Reordering fields

On the Multi-field editor page, use `drag-drop` handle to drag and drop the fields to reorder them.

<Callout type="note">
  The changes will only be saved when you click `Save changes` button.
</Callout>

<img alt="Reorder fields" src={__img5} placeholder="blur" />

## Show / Hide fields

On the Multi-field editor page, use the `toggle` button next to the fields to show or hide them.

<Callout type="note">
  The changes will only be saved when you click `Save changes` button.
</Callout>

<img alt="Show / Hide fields" src={__img6} placeholder="blur" />


# Primary key
URL: /docs/product-docs/fields/primary-key

This article explains what a primary key is and how it is used in NocoDB.

A primary key is a special database table field designated to uniquely identify each table record. As it uniquely identifies an individual record of a table, it is used internally by NocoDB for all operations associated with a record

## Primary Key in NocoDB

Primary Key that gets defined / used in NocoDB depends on how underlying table was created. Summary is captured below

1. From UI, Create new table / Import from Excel / Import from CSV
   1. An `ID` \[datatype: Integer] system field created by default during table creation is used as primary key
   2. Additional system fields `created-at`, `updated-at` are inserted by default

2. Connect to existing external database
   1. Existing `primary key` field defined for a table is retained as is; NocoDB doesn't insert a new ID field
   2. Additional system fields `created-at`, `updated-at` are not inserted by default

3. Import from Airtable
   1. Airtable record ID is marked as primary key for imported records, and is mapped to field `ncRecordId`  \[datatype: varchar]
   2. If a new record is inserted after migration & if ncRecordId field was omitted during record insertion - auto generated string will be inserted by NocoDB
   3. Computed hash value for the entire record is stored in system field `ncRecordHash`
   4. Additional system fields `created-at`, `updated-at` are not inserted by default

4. Create new table using SDK / API
   1. No default primary key field is introduced by NocoDB. It has to be explicitly specified during table creation (using attribute `pk: true`)

### FAQ

**What if Primary Key was missing?**

In NocoDB, it's possible for a table to have no primary key—this can happen if the table is created externally or through the SDK/API without specifying one. While new records can still be added to such tables, updating or deleting them won’t be possible since there's no unique identifier to reference each record.

**Can I change the Primary Key to another field within tables?**

You can't update Primary Key from NocoDB UI. You can reconfigure it at database level directly & trigger `meta sync` explicitly.

***


# Getting started
URL: /docs/product-docs/getting-started



NocoDB is available in two variants: **self-hosted** and **cloud-hosted** (SaaS). This guide walks you through getting started with either option.

<Callout type="tip">
   New to NocoDB? We recommend starting with the cloud-hosted option. New users can explore the platform's features on the 

  **free plan**

  .
</Callout>

## Self Hosted

Self-hosting gives you full control over your data and infrastructure. You can run NocoDB on your own server or a cloud provider of your choice.

* [Installation](/docs/self-hosting/installation/auto-upstall)
* [Environment Variables](/docs/self-hosting/environment-variables)
* [Upgrading](/docs/self-hosting/upgrading)

## SaaS (Cloud Hosted)

### Sign up for a NocoDB account

1. Visit the [NocoDB website](https://www.nocodb.com).
2. Click on the **Start For Free** button in the top right corner.
3. Sign up using your Google account or email address.
4. Verify your account using the link sent to your email.

Once signed up, you'll land on the NocoDB dashboard with a default workspace ready to use.

### Build a Base

A base is your database — it contains tables, fields, and relationships. [Create a new base](/docs/product-docs/bases/create-base) or [import an existing one from Airtable](/docs/product-docs/bases/import-base-from-airtable).

#### Create Tables

Tables store your data in rows and columns, like a spreadsheet. [Add new tables](/docs/product-docs/tables/create-table) to your base, or [import from CSV, Excel, or JSON](/docs/product-docs/tables/create-table-via-import).

#### Add Fields

Fields are columns that hold a specific type of data — text, numbers, dates, attachments, and [more](/docs/product-docs/fields). Use the [multi-fields editor](/docs/product-docs/fields/multi-fields-editor) to add, edit, reorder, and configure fields in bulk.

#### Establish Relationships between Tables

Connect related data across tables using [Link To Another Record](/docs/product-docs/fields/field-types/links-based/link-to-another-record) fields. For example, link "Tasks" to a "Project" by creating an LTAR field in the "Projects" table that points to the "Tasks" table.

#### Add Records

[Add records manually](/docs/product-docs/records/create-record) or [upload data from CSV](/docs/product-docs/tables/import-data-into-existing-table) files.

#### Create views

Views let you display and interact with data in different layouts. [Create multiple views](/docs/product-docs/views/create-view) per table, each with its own fields, filters, and sort order. Available view types: [Grid](/docs/product-docs/views/view-types/grid), [Form](/docs/product-docs/views/view-types/form), [Gallery](/docs/product-docs/views/view-types/gallery), [Kanban](/docs/product-docs/views/view-types/kanban), [Calendar](/docs/product-docs/views/view-types/calendar), [Timeline](/docs/product-docs/views/view-types/timeline), [List](/docs/product-docs/views/view-types/list), and [Map](/docs/product-docs/views/view-types/map).

#### Connect your data sources

Already have data in an external database? [Connect your existing data sources](/docs/product-docs/data-sources) and work with them through NocoDB's spreadsheet interface.

### Collaborate with your team

[Invite team members to your workspace](/docs/product-docs/collaboration/workspace-collaboration) and [share bases with them](/docs/product-docs/collaboration/base-collaboration). [Assign roles and permissions](/docs/product-docs/roles-and-permissions) to control access at workspace, base, table, and field levels.

Want to share publicly? [Create a public link](/docs/product-docs/collaboration/share-base) or [embed your base](/docs/product-docs/collaboration/share-base#embeddable-frame) on your website.

### Automate your workflows

NocoDB provides multiple ways to automate repetitive tasks:

* **[Workflows](/docs/product-docs/automation/workflow)**: Build visual automations with triggers, actions, conditions, and loops
* **[Scripts](/docs/scripts)**: Write JavaScript to automate operations across tables, fields, and records
* **[Webhooks](/docs/product-docs/automation/webhook)**: Send notifications to external services on record changes

### Extend with dashboards and apps

* **[Dashboards](/docs/product-docs/dashboards)**: Create visual dashboards with chart widgets, numbers, text, and iframes
* **[Extensions](/docs/product-docs/extensions)**: Add functionality with Bulk Update, Data Exporter, Dedupe, Org Chart, Page Designer, and more

### Use AI to work faster

[NocoAI](/docs/product-docs/noco-ai) helps you create bases, tables, fields, views, filters, formulas, and select options using natural language.

### Create documents with NocoDocs

[NocoDocs](/docs/noco-docs) is a built-in document editor with rich text formatting, comments, AI writing assistance, and granular permissions.


# Keyboard shortcuts
URL: /docs/product-docs/getting-started/keyboard-shortcuts









## Quick Actions

`⌘` + `K` (or `Ctrl` + `K` on Windows) is a keyboard shortcut to quickly navigate between different workspace, table, view, or a menu items. For example, if you want to quickly navigate to the "API Tokens" page, you can open Quick Actions menu using ⌘+K, type "Token" in the search box and press enter.

This shortcut is often referred to as "Command-K". It's a great way to save time when you're navigating around NocoDB.

Command-K menu can also be accessed via the "Quick Actions" button in the top left corner of the screen.

<img alt="Quick Actions" src={__img0} placeholder="blur" />

To navigate within ⌘+K menu,

* Use `↑` `↓` to navigate between listed items
* Use `Enter` to select an item
* Use `Backspace` to move to parent menu
* Use `Esc` to close the menu

## Recent Views

Access recently visited views quickly using `⌘` + `L` (or `Ctrl` + `L` on Windows). Search results will be displayed in a modal window; click on the result to open the view.

<img alt="Recent Views" src={__img1} placeholder="blur" />

To navigate within ⌘+L menu,

* Use `↑` `↓` to navigate between listed items
* Use `Enter` to select an item
* Use `Backspace` to move to parent menu
* Use `Esc` to close the menu

## Search in Docs

Quickly search through docs from within NocoDB UI using `⌘` + `J` (or `Ctrl` + `J` on Windows). Search results will be displayed in a modal window; click on the result to open the page in a new tab.

To navigate within ⌘+J menu,

* Use `↑` `↓` to navigate between listed items
* Use `Enter` to select an item
* Use `Backspace` to move to parent menu
* Use `Esc` to close the menu

<img alt="Search in Docs" src={__img2} placeholder="blur" />

## General shortcuts

|         Key | Behaviour                     |
| ----------: | :---------------------------- |
| `alt` + `t` | Opens new table modal         |
| `alt` + `c` | Opens new field modal         |
| `alt` + `f` | Toggles fullscreen mode       |
| `alt` + `i` | Opens share button modal      |
|   `⌘` + `k` | Opens Quick Actions modal     |
|   `⌘` + `l` | Opens Recent Views modal      |
|   `⌘` + `j` | Opens Search in Docs modal    |
|   `⌘` + `/` | Opens Keyboard shortcut modal |

## Grid view shortcuts

|               Key | Behaviour                                                                            |
| ----------------: | :----------------------------------------------------------------------------------- |
|   `←` `→` `↑` `↓` | General cell navigation                                                              |
|          `Delete` | Clear cell                                                                           |
|           `Space` | Expand current record                                                                |
| `Shift` + `Space` | Expand current cell                                                                  |
|             `Tab` | Move to next cell horizontally; if on last cell, move to beginning of next record    |
|             `Esc` | Exit cell EDIT mode                                                                  |
|           `Enter` | Switch cell in focus to EDIT mode; opens modal/picker if cell is associated with one |
|         `⌘` + `↑` | Jump to first record in this field (in same page)                                    |
|         `⌘` + `↓` | Jump to last record in this field (in same page)                                     |
|         `⌘` + `←` | Jump to first field in this record                                                   |
|         `⌘` + `→` | Jump to last field in this record                                                    |
|         `⌘` + `c` | Copy cell contents                                                                   |
|         `⌘` + `v` | Paste copied contents                                                                |
|       `alt` + `r` | Inserts new record in grid view                                                      |
|       `alt` + `↑` | Jump to last page in this view (obsolete)                                            |
|       `alt` + `↓` | Jump to first page in this view (obsolete)                                           |
|       `alt` + `←` | Jump to previous page in this view (obsolete)                                        |
|       `alt` + `→` | Jump to next page in this view (obsolete)                                            |

## Field type specific shortcuts

|            Datatype           |         Key | Behaviour                          |
| :---------------------------: | ----------: | :--------------------------------- |
|     Text & Numerical cells    |     `←` `→` | Move cursor to the left / right    |
|                               |     `↑` `↓` | Move cursor to the beginning / end |
|         Single Select         |     `↑` `↓` | Move between options               |
|                               |     `Enter` | Select option                      |
|          Multi Select         |     `↑` `↓` | Move between options               |
|                               |     `Enter` | Select / deselect option           |
|              Link             |     `↑` `↓` | Move between options               |
|                               |     `Enter` | Link current selection             |
|            Checkbox           |     `Enter` | Toggle                             |
|             Rating            | `<0 ~ Max>` | Enter number to toggle rating      |
| Date / Time / DateTime / Year |   `⌘` + `;` | Select today's date                |

## Expanded form shortcuts

|           Key | Behaviour                         |
| ------------: | :-------------------------------- |
| `⌘` + `Enter` | Save current expanded form item   |
|   `alt` + `→` | Switch to next record             |
|   `alt` + `←` | Switch to previous record         |
|   `alt` + `S` | Save current expanded form record |
|   `alt` + `N` | Create a new record               |


# License
URL: /docs/product-docs/getting-started/license

Understanding NocoDB’s Sustainable Use License (SUL) and Fair-Code principles.

As of **January 09, 2026** - NocoDB is transitioning from **AGPL-3.0** to a **Sustainable Use License (SUL)**, based on **[Fair-Code](https://faircode.io/) principles**.

👉 View the full license terms [here](https://github.com/nocodb/nocodb?tab=License-1-ov-file#readme)

This change is intended to:

* Keep NocoDB open and accessible
* Protect the work of maintainers and contributors
* Ensure long-term sustainability of the project
* Provide clear and predictable rules for commercial usage

## Fair-Code Philosophy

**Fair-Code** is a licensing philosophy that balances:

* Open access to source code
* Freedom to use, modify, and self-host
* Fair compensation when the software itself is monetized

Fair-code does **not** aim to restrict usage. Its goal is to prevent large-scale commercial exploitation where the software is monetized without supporting the people building it.

## Sustainable Use License (SUL)

The **Sustainable Use License** is one implementation of fair-code principles.

### SUL allows

* Free use for individuals and organizations
* Full access to source code
* Self-hosting without restrictions
* Modification for internal or product use

### SUL restricts

* Offering NocoDB itself as a paid or managed service
* Redistributing NocoDB as part of a commercial platform without a license

## Why This Change

### Sustainability

AGPL-3.0 permits commercial reuse at scale without ensuring ongoing support for maintainers. SUL enables continued investment in development, documentation, and support.

### Community Protection

The license protects contributors by ensuring that commercial value derived directly from NocoDB supports the ecosystem.

### Clear Commercial Boundaries

SUL clearly defines when commercial licensing is required, reducing ambiguity around SaaS and redistribution scenarios.

***

## Usage Rights

### Free Use (No Commercial License Required)

You may use NocoDB freely if you are:

* An individual developer
* A startup or enterprise using NocoDB internally
* Self-hosting NocoDB for internal tools or workflows
* Building an application or product that uses NocoDB internally
* Using NocoDB for education, research, or non-commercial purposes

Internal usage is permitted regardless of organization size.

***

### Commercial License Required

A commercial license is required if you:

* Offer NocoDB as a hosted or managed service
* Provide direct NocoDB access to external customers
* Resell or redistribute NocoDB as part of a paid offering
* Embed NocoDB in a platform where customers interact with NocoDB itself

If your business model monetizes **access to NocoDB**, a commercial license is required. If you need assistance determining your licensing needs, please contact the NocoDB team. Details [here](/docs/product-docs/getting-started/license#how-do-i-obtain-a-commercial-license)

***

## What Remains Unchanged

* Source code remains available
* Self-hosting remains supported
* Community contributions remain welcome
* APIs, integrations, and extensions remain open

This is **not** a move to closed source.

***

## Frequently Asked Questions

### Is NocoDB still open source?

NocoDB is **source-available under fair-code principles**. While SUL is not OSI-approved, it preserves transparency, extensibility, and community access.

### Can I self-host NocoDB for my company?

Yes. Internal self-hosting does not require a commercial license.

### Can I modify NocoDB’s source code?

Yes. You may modify NocoDB for internal use or as part of your product.

### What licenses are considered fair-code compatible?

The following licenses meet fair-code requirements and are commonly referenced in the ecosystem:

* **[Sustainable Use License (SUL)](https://github.com/n8n-io/n8n/blob/master/LICENSE.md?utm_source=chatgpt.com)**
* **[Business Source License (BSL)](https://mariadb.com/bsl11)**
* **[Commons Clause](https://commonsclause.com)** (with an OSI-approved license)
* **[Confluent Community License](https://www.confluent.io/confluent-community-license)**
* **[Elastic License 2.0 (ELv2)](https://www.elastic.co/licensing/elastic-license)**
* **[Server Side Public License (SSPL)](https://www.mongodb.com/licensing/server-side-public-license)**

### Which projects follow fair-code-compatible licenses?

Several well-known infrastructure and developer-tool projects use licenses aligned with fair-code principles, including:

* **[Airbyte](https://airbyte.com)** (Elastic License 2.0)
* **[CockroachDB](https://www.cockroachlabs.com)** (Business Source License)
* **[Elastic](https://www.elastic.co)** (Elastic License 2.0)
* **[HashiCorp](https://www.hashicorp.com)** (Business Source License)
* **[MongoDB](https://www.mongodb.com)** (Server Side Public License)
* **[n8n](https://n8n.io)** (Sustainable Use License)
* **[Sentry](https://sentry.io)** (Business Source License)

These projects follow a similar approach: open access for builders, with licensing required when the software itself is monetized.

### Why move away from AGPL-3.0?

AGPL-3.0 does not sufficiently address large-scale commercial redistribution. SUL provides clearer, more predictable rules while preserving openness and community access.

### How do I obtain a commercial license?

Contact the NocoDB team through official channels to discuss commercial licensing options.

* Use in-product support chat for inquiries.
* Request details over Email ([cs@nocodb.com](mailto:cs@nocodb.com)).
* Book a meeting via [Cal](https://cal.com/nocodb/sales).

## Summary

The Sustainable Use License ensures that NocoDB remains:

* Open and accessible for builders
* Fair to contributors and maintainers
* Sustainable for long-term development

For most users, **nothing changes**. For commercial redistribution, licensing ensures fairness and continued innovation.

***


# NocoDB terminologies
URL: /docs/product-docs/getting-started/terminologies





Familiarize yourself with key terms used across NocoDB.

## Layout

The layout below shows the main parts of NocoDB's user interface.

<img alt="image" src={__img0} placeholder="blur" />

1. **Minibar**: The vertical bar on the far left with icons for quick access to Search, Workflows, Integrations, Help, and Settings.

2. **Sidebar**: Displays the base name (e.g., "Sales CRM"), a **Create New** button, and a tree of all tables and their views. Each table and view shows its icon for easy identification.

3. **Navbar**: The horizontal bar at the top showing the current breadcrumb path (Base > Table > View), along with tabs for **Data**, **Details**, and **Extensions**, and the **Share** button.

4. **Toolbar**: Located below the Navbar, provides tools for the current view — **Fields**, **Filter**, **Group**, **Sort**, **Colour**, row height, and search.

5. **View Area**: The central workspace displaying records in the selected view format (Grid, Form, Gallery, Kanban, Calendar, Timeline, List, or Map). In Grid view, data is shown in rows and columns with fields like Activity, Type, Date, Outcome, and Notes.

6. **Footbar**: The bottom bar showing the total record count and field aggregations (e.g., Filled, Min, Percent Filled) when configured.

## Terminologies

### Core Concepts

| Term          | Description                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | Top-level organizational unit that contains one or more bases. Manages user access and permissions across all bases within it.                            |
| **Base**      | A container for one or more related data sources, each comprising multiple tables. Think of a base as a project workspace for organizing structured data. |
| **Table**     | Organizes data into rows (records) and columns (fields). Each table represents a distinct entity and can be linked to other tables through relationships. |
| **Field**     | A named column within a table that holds values of a specific type (e.g., text, number, date). All records in a table share the same set of fields.       |
| **Record**    | A single entry in a table, represented as a row. Contains values across multiple fields.                                                                  |
| **Cell**      | The intersection of a row and a column. Holds the actual value of a field in a specific record.                                                           |

### Views

| Term                   | Description                                                                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **View**               | Defines how records in a table are displayed and interacted with. Each table can have multiple views with their own filters, sorts, and field visibility. |
| **Grid View**          | Default spreadsheet-like view displaying data in rows and columns.                                                                                        |
| **Form View**          | Presents fields as a form for data collection. Can be shared publicly.                                                                                    |
| **Gallery View**       | Displays records as cards, useful for visual content like images or profiles.                                                                             |
| **Kanban View**        | Organizes records into columns based on a Single Select or User field, useful for tracking status or stages.                                              |
| **Calendar View**      | Displays records on a calendar based on a date field.                                                                                                     |
| **Timeline View**      | Shows records along a horizontal timeline based on date ranges.                                                                                           |
| **List View**          | Hierarchical outline view that displays records organized through LTAR relationships.                                                                     |
| **Map View**           | Plots records on a map using a Geometry or GeoData field.                                                                                                 |
| **Shared View**        | A publicly accessible link to a view, optionally password-protected.                                                                                      |
| **Collaborative View** | A view shared across all base members, where changes to filters, sorts, or field visibility are visible to everyone.                                      |
| **Locked View**        | A view where the configuration (filters, sorts, field visibility) is locked and cannot be modified.                                                       |
| **Personal View**      | A private view visible only to the user who created it.                                                                                                   |

### Relationships & Computed Fields

| Term                              | Description                                                                                                                 |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Link To Another Record (LTAR)** | A field type that creates a relationship between two tables, allowing records in one table to reference records in another. |
| **Lookup**                        | A field that retrieves and displays a value from a linked table via an LTAR relationship.                                   |
| **Rollup**                        | A field that aggregates values (e.g., sum, count, average) from linked records in another table via an LTAR relationship.   |
| **Formula**                       | A computed field whose value is derived from an expression involving other fields, operators, and built-in functions.       |

### Automation & Integrations

| Term            | Description                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook**     | Sends data to a specified URL when a configured event occurs (e.g., record created, updated, or deleted), enabling integrations with external services. |
| **Workflow**    | A visual automation that runs a sequence of actions in response to a trigger event, with support for conditions, loops, and delays.                     |
| **Script**      | A JavaScript-based automation that can read and modify data across tables, fields, and records programmatically.                                        |
| **Integration** | A configured connection to an external service or data source that NocoDB can interact with.                                                            |
| **Data Source** | An external database (e.g., PostgreSQL, MySQL) connected to a base, allowing NocoDB to read and write data directly.                                    |

### Extensions & Features

| Term          | Description                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Dashboard** | A visual canvas for building charts and widgets that summarize data from your tables.                                              |
| **Extension** | An add-on app that provides additional functionality such as Bulk Update, Data Exporter, Dedupe, Org Chart, or Page Designer.      |
| **NocoDocs**  | Built-in document editor with rich text formatting, comments, AI writing assistance, and granular permissions.                     |
| **NocoAI**    | AI-powered assistant that helps create bases, tables, fields, views, filters, formulas, and select options using natural language. |
| **NocoSync**  | Syncs data from external tools like GitHub, GitLab, Bitbucket, and Linear into NocoDB tables.                                      |

### Roles & Permissions

| Term                 | Description                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Owner**  | The user who created the workspace. Has full administrative privileges including managing members, roles, and billing.       |
| **Workspace Member** | A user with access to the workspace. Can be assigned roles such as Owner, Creator, Editor, Commenter, or Viewer.             |
| **Base Owner**       | The member who created the base or was assigned the owner role. Has full control over the base configuration and data.       |
| **Base Member**      | A user with access to a base, assigned a role that defines their permissions (Owner, Creator, Editor, Commenter, or Viewer). |

### UI Elements

| Term                | Description                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Expanded Record** | A detailed view of a single record, showing all fields and their values in a panel or modal.                                                   |
| **Modal**           | A UI overlay for a specific task such as editing a record or confirming an action. Blocks access to the rest of the interface until dismissed. |


# Actions on connection
URL: /docs/product-docs/integrations/actions-on-connection

Learn how to perform actions (edit, duplicate, delete) on a connection in NocoDB.









## List

To list all the connections in NocoDB, follow the steps below:

1. Select the **Integrations** menu in the left sidebar.
2. Click on the **Connections** tab

<img alt="Connections List" src={__img0} placeholder="blur" />

Connections list provides a consolidated view of all the connections in this workspace. The details include

* Connection name, as specified during creation
* Connection type, i.e., the integration type \[Example: PG, MySQL]
* Date added, specifies the date when this connection was created
* Added by, specifies the user who created this connection
* Usage, depends on the type of the integration
  * for database type integrations, this would specify the number of data sources using this connection

<Callout type="info">
  Note that, there is no ownership concept for connections in NocoDB. All the connections created in a workspace are accessible to all eligible users in that workspace.

  * Users with Workspace Creator+ permissions can create, edit, duplicate, and delete connections
  * Users with Base Creator+ permissions can create data sources using these connections
</Callout>

## Edit

To edit a connection in NocoDB, Open the [Connections list](#list) and follow the steps below:

* Click on the Connection you want to edit
* Modify the required details in the subsequent modal
* **Test connection** if applicable
  * Applicable if you have updated the connection details for a database integration
* Click on the **Update connection** button to save the changes

## Duplicate

To duplicate a connection in NocoDB, Open the [Connections list](#list) and follow the steps below:

1. Click on the Action menu (three dots) against the Connection you want to duplicate
2. Select the **Duplicate** option from the dropdown

Duplicated base will be created with the same connection details as the original connection - with connection name for the duplicated entry suffixed with **\_copy**.

<img alt="Duplicate Connection" src={__img1} placeholder="blur" />

## Delete

To delete a connection in NocoDB, Open the [Connections list](#list) and follow the steps below:

1. Click on the Action menu (three dots) against the Connection you want to delete
2. Select the **Delete** option from the dropdown
3. Click on the **Delete** button in the subsequent modal to confirm deletion

<img alt="Delete Connection" src={__img2} placeholder="blur" />

<img alt="Delete Connection" src={__img3} placeholder="blur" />

<Callout type="warn">
  Note that, deleting a database connection **will remove all the associated data sources using this connection** from all the bases in this workspace.
</Callout>


# Connect to an Integration
URL: /docs/product-docs/integrations/create-connection

Learn how to create a new connection in NocoDB.















Users with Workspace Owner or Workspace Creator roles can create a new connection in NocoDB. To create a new connection, follow the steps below:

<img alt="Integrations" src={__img0} placeholder="blur" />

1. Click on the `Integrations` menu in the left minibar.
2. From the list, click on the integration you want to connect to
3. In the subsequent modal, provide required details. Please refer to the integration-specific documentation for more details.
   * [PostgreSQL](#postgresql)
   * [MySQL](#mysql)

Connection to an integration thus created will be listed in the `Connections` tab under the `Integrations` menu.

<Callout type="info">
  Note that, there is no ownership concept for connections in NocoDB. All the connections created in a workspace are accessible to all eligible users in that workspace.

  * Users with **Workspace Creator+** permissions can create, edit, duplicate, and delete connections
  * Users with **Base Creator+** permissions can create data sources using database connections
</Callout>

## Database Integrations

### PostgreSQL

This section covers the details required to create a new PostgreSQL connection in NocoDB.

<img alt="PostgreSQL Connection" src={__img1} placeholder="blur" />

1. **Connection Name**: Name for this connection for display on NocoDB UI
2. Key in following database connection configuration details
   * **Host Address**: Hostname of the PostgreSQL server
   * **Port Number**: Port number of the PostgreSQL server, default is 5432
   * **Username**: Username to connect to the PostgreSQL server, default is "postgres"
   * **Password**: Password to connect to the PostgreSQL server
   * \[Optional] **Database**: Name of the PostgreSQL database to connect to
   * \[Optional] **Schema Name**: Name of the schema to connect to
     :::info
     Note, Database name & Schema name are optional fields when creating a connection. If provided, these details will be filled in by default when creating a new data source using this connection.
     :::
3. **Connection parameters**: required if any, can be added as Key-Value pairs
4. **SSL Mode**: This step is required if the connection required is TLS/MTLS for MITM protection. Toggle to enable SSL for the connection & select the SSL mode
   * **Client Certificate**: Upload the client certificate file
   * **Client Key**: Upload the client key file
   * **Root CA**: Upload the Root CA file
5. **Test Database Connection**: Click to verify the connection
6. **Create Connection**: Click to save the data source

The connection thus created will be listed in the `Connections` tab under the `Integrations` menu.

<Callout type="info">
  You can autofill the connection details if you have a connection URL.

    <img alt="Connection URL" src={__img2} placeholder="blur" />
</Callout>

<Callout type="info">
  The entire connection parameters can be viewed in JSON form by clicking on the **Advanced Options** and edited as required by database server type.

  **Example**: When SSL mode set to "Required-Identity," if the server certificate's common name (cname) differs from the actual DNS/IP used for connection, the connection will fail. To resolve, add "servername" property with same cname value under the SSL section. Additional details are available at [knex configuration options](https://knexjs.org/guide/#configuration-options).
</Callout>

### MySQL

This section covers the details required to create a new MySQL connection in NocoDB.

<img alt="MySQL Connection" src={__img3} placeholder="blur" />

1. **Connection Name**: Name for this connection for display on NocoDB UI
2. Key in following database connection configuration details
   * **Host Address**: Hostname of the MySQL server
   * **Port Number**: Port number of the MySQL server, default is 3306
   * **Username**: Username to connect to the MySQL server, default is "root"
   * **Password**: Password to connect to the MySQL server
   * \[Optional] **Database**: Name of the MySQL database to connect to

<Callout type="info">
  Database name is optional when creating a connection. If provided, it will be filled in by default when creating a new data source using this connection
</Callout>

3. **Connection parameters**: required if any, can be added as Key-Value pairs
4. **SSL Mode**: This step is required if the connection required is TLS/MTLS for MITM protection. Toggle to enable SSL for the connection & select the SSL mode
   * **Client Certificate**: Upload the client certificate file
   * **Client Key**: Upload the client key file
   * **Root CA**: Upload the Root CA file
5. **Test Database Connection**: Click to verify the connection
6. **Create Connection**: Click to save the data source

The connection thus created will be listed in the `Connections` tab under the `Integrations` menu.

<Callout type="info">
  You can autofill the connection details if you have a connection URL.

    <img alt="Connection URL" src={__img4} placeholder="blur" />
</Callout>

<Callout type="info">
  The entire connection parameters can be viewed in JSON form by clicking on the **Advanced Options** and edited as required by database server type.

  **Example**: When SSL mode set to "Required-Identity," if the server certificate's common name (cname) differs from the actual DNS/IP used for connection, the connection will fail. To resolve, add "servername" property with same cname value under the SSL section. Additional details are available at [knex configuration options](https://knexjs.org/guide/#configuration-options).
</Callout>

***

## Communication Integrations

### Twilio

This section covers the details required to create a new Twilio integration in NocoDB.

1. **Integration Name:**
   Enter a name for this integration as it should appear in the NocoDB UI

2. **Authentication Type:**
   Select **API credentials** as the authentication method.

3. **Account SID:**
   Enter your Twilio **Account SID**.
   This can be obtained from the [Twilio Console](https://console.twilio.com/) under **Account Info**.

4. **Auth Token**
   Enter your Twilio **Auth Token**, available in the [Twilio Console](https://console.twilio.com/) under **Account Info**.
   Ensure this value is stored securely.

5. **Test Connection**
   Click **Test connection** to verify that the provided credentials are valid and that NocoDB can connect to Twilio.

6. **Create Integration**
   Click **Create integration** to save the connection.

<img alt="Twilio Integration" src={__img5} placeholder="blur" />

<img alt="Twilio Integration" src={__img6} placeholder="blur" />

Once created, the Twilio integration will be listed in the `Connections` tab under the `Integrations` menu and can be used across eligible features that support Twilio.

<Callout type="info">
  For trial Twilio accounts, messaging and calls are limited to verified phone numbers, as enforced by Twilio.
</Callout>

**References**

* [Twilio Console](https://console.twilio.com/)
* [Twilio Documentation](https://www.twilio.com/docs/)

***


# Integrations
URL: /docs/product-docs/integrations

Overview of the integrations available in NocoDB



**Integrations** enable seamless connectivity between NocoDB and external platforms. This helps consolidate your data scattered across multiple silos into one common platform.

You can add multiple instances of an integration within a single workspace, with each instance referred to as a **Connection**. Once established, these connections allow you to utilize data from the integrated platforms in your NocoDB base. If applicable, changes made in NocoDB can also be synchronized back to the external platforms.

Currently, NocoDB supports integrations with databases such as *MySQL* and *PostgreSQL*, with additional integrations planned for the future. If you have a specific integration in mind, please let us know by submitting your request using "**Request Integration**" option in the `Integrations` menu.

<Callout type="info">
  * In Cloud hosted solutions, Integrations menu will be accessible for Workspace Owners & Workspace Creators.
  * In Self-hosted solutions (OSS), Integrations menu will be accessible for Organization Admins & Organization Creators.
</Callout>

All activities related to integrations and their connections can be efficiently managed from the `Integrations` menu, conveniently located in the left sidebar.

<img alt="Integrations" src={__img0} placeholder="blur" />

Learn more about working with integrations in the following sections:

* [Create a new connection](/docs/product-docs/integrations/create-connection)
* [Edit connection](/docs/product-docs/integrations/actions-on-connection#edit)
* [Delete connection](/docs/product-docs/integrations/actions-on-connection#delete)


# Create Base using AI
URL: /docs/product-docs/noco-ai/create-base

Quickly generate a fully-structured base using natural language prompts with NocoAI













<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

NocoAI lets you instantly generate a complete base — including tables, views, fields, and relationships — just by describing your needs in natural language. Perfect for non-technical users, fast prototyping, and workflow automation.

***

## Steps to Create a Base Using AI

1. Click **Create Base**

From the left sidebar, click **+ Create Base**.

2. Choose **Build Base with AI**

In the dialog, select **✨ Build Base with AI** to use AI-powered base generation.

3. Select a **Use Case** *(Optional)*

Choose a predefined use case to auto-fill a sample prompt.

4. OR **Write Your Own Prompt**

You can edit the suggested prompt or enter your own.
For example:

> Streamline the hiring process by managing candidate applications, scheduling interviews, and tracking hiring outcomes.

5. Add **Additional Context** *(Optional)*

Provide more details like organization name, industry, and audience to help tailor AI results.

6. Click **Suggest Tables & Views**

NocoAI will analyze your prompt and generate the recommended schema.

7. **Review** Tables and Views

You’ll see all suggested tables and their associated views.

8. **Review Relationships** using ERD

Switch to the **Relationship Diagram** tab to view an auto-generated ERD (Entity Relationship Diagram).

9. Click **Create Base**

Once you’re happy with the structure, click **Create Base** to finalize and start using it.

<img alt="Step 1" src={__img0} placeholder="blur" />

<img alt="Step 2" src={__img1} placeholder="blur" />

<img alt="Step 3 & 4" src={__img2} placeholder="blur" />

<img alt="Step 5" src={__img3} placeholder="blur" />

<img alt="Step 6" src={__img4} placeholder="blur" />

<img alt="Step 7 & 8" src={__img5} placeholder="blur" />

## Tips for Better AI Suggestions

* **Be clear and specific**\
  Avoid vague descriptions like “make a project tracker.” Instead, try:
  > Track multiple projects with assigned team members, tasks, deadlines, and project status updates.

* **Mention key entities and relationships**\
  Include what you want to manage and how they relate.
  > Each candidate can apply to multiple job openings and be scheduled for multiple interviews.

* **Add extra context**\
  Use fields like **Industry** or **Audience** to help guide the AI.

* **Start simple, refine later**\
  You can edit the prompt and regenerate suggestions if needed.

***

## Next Steps

Now that your base is created, explore additional NocoAI capabilities:

* AI-assisted **[View Suggestions](/docs/product-docs/noco-ai/create-view)**
* AI-assisted **Field Suggestions**
* Prompt-based **Formula Generation**
* Smart **Select Option** predictions

Let AI do the heavy lifting, so you can focus on what matters.


# Create Fields using AI
URL: /docs/product-docs/noco-ai/create-field

Automatically generate relevant fields for your tables using NocoAI.





<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

With NocoAI, you can instantly generate a set of fields for your table by describing the kind of data you want to manage. Whether you're setting up a simple list or a complex workflow, NocoAI helps you get started with the right fields in seconds.

***

## Steps to Create Fields Using AI

Open any existing table where you want to add fields.

1. Open **+ Add Field** modal

   In the table header, click the **+** button to the right of the field list.

2. Use **NocoAI Suggestions**

   In the field creation dialog, select **✨ Use NocoAI** to get AI-powered suggestions.

3. Choose from Suggested Fields

   NocoAI will analyze your table name, existing fields, and related context to recommend relevant fields. You can edit field names, types, and options as needed.

4. Click **Create \[X] Fields**

   Select the ones you need and confirm to add them to your table.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

***

## Tips for Better AI Suggestions

* **Name your table clearly**
  For example, use "Job Applications" instead of "Table 1" to help NocoAI make better field recommendations.

* **Think in terms of attributes**
  Consider what information each record should store.
  *Example*: A “Candidate” table may need Full Name, Email, Phone, Resume, Status, and Applied Date.

* **Leverage existing fields**
  NocoAI takes into account your current setup to avoid duplicates and suggest only what's missing.

* **Use it iteratively**
  You can always run field suggestions multiple times as your table evolves.

***

## Example Scenarios

Here are examples of what NocoAI might suggest based on table name:

| Table Name         | Suggested Fields                                       |
| ------------------ | ------------------------------------------------------ |
| `Leads`            | Name, Email, Source, Status, Last Contacted            |
| `Tasks`            | Title, Due Date, Priority, Assigned To, Status         |
| `Job Applications` | Candidate Name, Resume, Email, Phone, Application Date |

***

## What's Next

Now that your fields are ready, you can:

* Use **[NocoAI View Suggestions](/docs/product-docs/noco-ai/create-view)** to visualize data more effectively
* Create **[Formulas using AI](/docs/product-docs/noco-ai/create-formula)** to automate calculations and logic

Let NocoAI take care of the structure — so you can focus on your workflow.


# Filter Records using AI
URL: /docs/product-docs/noco-ai/create-filter

Use natural language to filter your table data with NocoAI.





<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

With **NocoAI**, you can now describe what data you want to see in plain English, and have the right filter conditions applied automatically. Instead of manually configuring filter operators, values, and conditions, simply type a description like *"Show high priority tasks due this week"* and NocoAI will set up the filters for you.

This is perfect for quickly narrowing down records, exploring data without remembering filter syntax, or letting non-technical users build complex filter conditions effortlessly.

***

## Steps to Filter Records Using AI

1. Open the **Filter** menu

   Click the **Filter** button in the toolbar above your table to open the filter panel.

2. **Describe** what you want to see

   At the top of the filter panel, you'll see an AI-powered text input with a ✨ icon. Type a natural-language description of the records you want to see.

   *Example*:

   > Show high priority tasks that are due this week

3. Press **Enter** or click **Send**

   NocoAI will analyze your table's structure and generate the appropriate filter conditions.

4. **Filters are applied automatically**

   The generated filters appear in the filter panel and are applied to your view immediately — no extra confirmation needed.

<img alt="image" src={__img0} placeholder="blur" />

<img alt="image" src={__img1} placeholder="blur" />

***

## Supported Actions

NocoAI understands your intent and can perform three types of filter actions:

| Action      | When it's used                                | Example prompt                            |
| ----------- | --------------------------------------------- | ----------------------------------------- |
| **Add**     | Append new filters to existing ones           | "Also show rows where Status is Done"     |
| **Replace** | Remove all current filters and apply new ones | "Show only rows where Score is above 80"  |
| **Clear**   | Remove all existing filters                   | "Remove all filters" or "Show everything" |

***

## Supported Filter Types

NocoAI can generate filters for a wide range of field types:

| Field Type                                      | Example Prompts                                               |
| ----------------------------------------------- | ------------------------------------------------------------- |
| **Text** (SingleLineText, Email, URL)           | "Title contains meeting", "Title is either A or B"            |
| **Number** (Number, Decimal, Currency, Percent) | "Price is greater than 100", "Score between 50 and 80"        |
| **SingleSelect / MultiSelect**                  | "Status is either Todo or In progress", "Tags include urgent" |
| **Date / DateTime**                             | "Due this week", "Created after 2025-01-01", "Modified today" |
| **Checkbox**                                    | "Show only checked items", "Where completed is unchecked"     |
| **Rating**                                      | "Rating is 4 or above"                                        |

NocoAI also understands **AND** vs **OR** logic:

* "Priority is High and Status is not Done" → AND conditions
* "Title is either Alpha or Beta" → OR conditions

***

## Tips for Better AI Filters

* **Use exact field names when possible**

  NocoAI matches against your table's column names. Using exact names produces more accurate results.
  *Example*: If your column is called "Due Date", say *"Due Date is this week"* instead of *"due soon"*.

* **Be specific about values**

  For select fields, use exact option values.
  *Example*: *"Status is In progress"* works better than *"status is active"* if your options are `Todo`, `In progress`, `Done`.

* **Use keywords for clear/replace**

  To remove filters, say *"clear filters"*, *"remove all filters"*, *"show everything"*, or *"reset"*.
  To replace existing filters entirely, start with *"show only ..."* or *"instead show ..."*.

* **Start simple, then refine**

  You can add filters incrementally. Start with *"Status is Todo"*, then follow up with *"also where Priority is High"*.

* **Match filter type with field type**

  Make sure your condition aligns with the field type. Example: Using a filter like *"Price \< 50"* will not work if the Price field is a text field. Numeric comparisons only work on number-based fields.

## Example Prompts and Outcomes

| Prompt                            | Generated Filters                                 |
| --------------------------------- | ------------------------------------------------- |
| "Show high priority tasks"        | Priority `is equal` High                          |
| "Title is either Alpha or Beta"   | Title `is equal` Alpha `OR` Title `is equal` Beta |
| "Status is Todo or In progress"   | Status `is any of` Todo, In progress              |
| "Due this week"                   | Due Date `is within` next week                    |
| "Items with no status"            | Status `is blank`                                 |
| "Remove all filters"              | All existing filters cleared                      |
| "Show only rows where Score > 80" | Existing filters replaced with Score `>` 80       |

## What's Next

Now that you can filter records with AI, explore more NocoAI capabilities:

* Create **[Views using AI](/docs/product-docs/noco-ai/create-view)** to set up useful views for your data
* Create **[Fields using AI](/docs/product-docs/noco-ai/create-field)** to auto-generate relevant columns
* Generate **[Formulas using AI](/docs/product-docs/noco-ai/create-formula)** to automate calculations

Let NocoAI handle the filter logic while you focus on your data.

***


# Generate Formulas using AI
URL: /docs/product-docs/noco-ai/create-formula

Use natural language prompts to generate formulas with NocoAI.

<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

Writing formulas can be complex and time-consuming. With **NocoAI**, you can now describe the logic you need in plain English, and have a formula generated for you automatically.

This is perfect for non-technical users, power users who want to speed up formula creation, or anyone looking to avoid syntax errors.

***

## Steps to Generate Formulas Using AI

1. Add a **Formula Field**

   In your table, add field and select **Formula** as the type.

2. Click **Formula Helper**

   Inside the formula editor, click **✨ Formula Helper** to open the prompt-based generation interface.

3. **Describe** the Logic in Natural Language

   Write a simple prompt explaining what the formula should do.
   *Example*:

   > Show "✅ Done" if Status is "Completed", else show "⏳ In Progress".

4. Review and click **Generate**

   NocoAI will generate the formula based on your prompt in the formula editor. You can review and modify if needed.

5. Click **Save**

   Once you're happy with the result, save the field.

<div style={{ display: "flex", gap: "1rem" }}>
  <img src="/img/v2/noco-ai/create-formula-1.png" alt="Formula field using AI - Step 1" style={{ width: "50%", borderRadius: "8px", boxShadow: "0 0 8px rgba(0,0,0,0.05)" }} />

  <img src="/img/v2/noco-ai/create-formula-2.png" alt="Formula field using AI - Step 2" style={{ width: "50%", borderRadius: "8px", boxShadow: "0 0 8px rgba(0,0,0,0.05)" }} />
</div>

***

## Tips for Better Formula Suggestions

* **Be precise in your prompt**

  Mention exact field names and values where possible.
  *Example*:

  > Calculate number of days between Start Date and End Date.

* **Use conditional phrases**

  Help the AI understand intent.
  *Example*:

  > If Priority is "High" and Status is not "Completed", show "⚠️ Urgent".

* **Refer to data types clearly**

  Indicate if you’re working with dates, numbers, checkboxes, or text.
  *Example*:

  > Add 7 days to the Created Date.

***

## Example Prompts and Outcomes

| Prompt                                             | Resulting Formula (Example)                       |
| -------------------------------------------------- | ------------------------------------------------- |
| If Status is "Done", show "✅", else show "⏳"       | `IF({Status} = "Done", "✅", "⏳")`                 |
| Show the number of days between Start and End Date | `DATETIME_DIFF({End Date}, {Start Date}, "days")` |
| If Due Date is past today, mark as "Overdue"       | `IF({Due Date} < TODAY(), "Overdue", "")`         |
| Combine First Name and Last Name into one field    | `CONCAT({First Name}, " ", {Last Name})`          |

***

## What’s Next

Once your formula field is ready, you can:

* Use **[NocoAI View Suggestions](/docs/product-docs/noco-ai/create-view)** to visualize data based on these formulas
* Create **[Fields using AI](/docs/product-docs/noco-ai/create-field)** to automatically generate relevant fields for your table

NocoAI simplifies complex logic so you can stay focused on building great workflows!


# Create Options using AI
URL: /docs/product-docs/noco-ai/create-options

Automatically generate field options for select fields using NocoAI.





<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

When working with **Single Select** or **Multi Select** fields, you can now let **NocoAI** suggest relevant options based on your field name and table context. This helps reduce manual work and ensures meaningful, consistent values.

***

## Steps to Create Options Using AI

1. Add a **Single Select** or **Multi Select** Field

   Click the + icon in the top-right corner of the field header in your table, then select either 'Single Select' or 'Multi Select'. Provide a clear and descriptive field name that reflects the type of options required.

2. Click **Auto Suggest**

   Inside the field configuration modal, click the **✨ Auto Suggest** button to fetch option suggestions.

3. **Review** Suggested options

   NocoAI will analyze your field name and table context to generate a list of relevant options. You can add, remove, or edit the suggested values before saving.

4. Click **Save Field**

   Finalize your configuration to add the field and its options to your table.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

***

## Tips for Better AI Suggestions

* **Use a descriptive field name**
  Example: Instead of "Type", use "Application Status" or "Task Priority".

* **Set table context**
  The more specific your table name and existing fields are, the better the suggestions.
  *Example*: In a table named “Tasks”, a field called “Priority” will likely suggest: `Low`, `Medium`, `High`.

* **Apply business terms**
  Use industry-appropriate terminology in your field name to guide the AI.
  *Example*: For a field called “Candidate Stage”, suggestions might include: `Applied`, `Screened`, `Interviewed`, `Hired`.

***

## Example Use Cases

| Table        | Field Name         | Suggested Options                                  |
| ------------ | ------------------ | -------------------------------------------------- |
| `Tasks`      | Priority           | Low, Medium, High, Critical                        |
| `Candidates` | Application Status | Applied, Shortlisted, Interviewed, Hired, Rejected |
| `Projects`   | Phase              | Initiation, Planning, Execution, Closure           |
| `Feedback`   | Sentiment          | Positive, Neutral, Negative                        |

***

## What’s Next

Now that your select fields are powered with meaningful options, you can:

* Create **[Views using AI](/docs/product-docs/noco-ai/create-view)** to visualize data based on these options
* Use **[Formulas using AI](/docs/product-docs/noco-ai/create-formula)** to derive insights based on selected values

Let NocoAI handle the heavy lifting while you focus on building smarter workflows.


# Create Tables using AI
URL: /docs/product-docs/noco-ai/create-table

Use NocoAI to auto-generate tables and relationships based on natural language prompts.





<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

With NocoAI, you can automatically generate tables — including their fields and relationships — just by describing your system in plain language. Ideal for getting started quickly with a new database structure or adding new modules to an existing base.

***

## Steps to Create Tables Using AI

1. Open \*\* Create Table\*\* modal
   From the left sidebar, Click **+ Create New**, select **Table**

2. Select **Use NocoAI**\
   In the dialog, click on **✨ Use NocoAI** to begin the AI-assisted process.

3. Choose a Suggestion Mode
   * **Auto Suggested**: NocoAI provides a set of suggested tables based on your current schema and context.
   * **Use Prompt**: *(Coming Soon)* Describe what tables you want in your own words.

4. Click **Create \[X] Tables**\
   Select the tables you want from the list and click **Create**.

***

<img alt="Create Table Button" src={__img0} placeholder="blur" />
<img alt="Table Suggestion Modal" src={__img1} placeholder="blur" />

***

## Tips for Better AI Suggestions

* **Use meaningful table names in your base**\
  The AI looks at existing names and structures to recommend relevant tables.

* **Think in entities**\
  Imagine the business objects you want to manage (e.g., Candidates, Applications, Feedback, Agencies) and how they connect.

* **Preview and refine**\
  If the suggestions aren't accurate, use the **Suggest More** button to regenerate.

* **Add new modules incrementally**\
  You can trigger NocoAI for different parts of your app — e.g., one time for recruiting, another for feedback — to build your schema progressively.

***

## What's Next

Once your tables are created:

* Use **[NocoAI View Suggestions](/docs/product-docs/noco-ai/create-view)** to generate meaningful views
* Create **[Fields using AI](/docs/product-docs/noco-ai/create-field)** to automatically generate relevant fields for each table

NocoAI gives you a head start — you can customize everything further to meet your needs.


# Create Views using AI
URL: /docs/product-docs/noco-ai/create-view

Learn how to auto-generate useful views for your table using NocoAI.







<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

## Overview

You can now let **NocoAI** intelligently suggest useful views for your table, helping you get started faster and more efficiently.

***

## Steps to Create Views using AI

1. Click on **+ Create View** in the left sidebar.

2. Select **Use NocoAI** from the dropdown.

3. In the popup, go with:
   * **Auto Suggested**: Choose from automatically generated view suggestions.
   * **Use Prompt**: Manually describe what kind of views you need. (*Coming soon!*)

4. Click **Create \[X] views** to add them to your table.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

You can also access this feature from the **Use NocoAI** button in the view creation modal.
<img alt="image" src={__img2} placeholder="blur" />

***

## Tips for Better AI Suggestions

When using the **Auto Suggested** option, NocoAI analyzes your table's data and structure to provide relevant view suggestions. Here are some tips to get the most out of this feature:

* **Be descriptive**: Clearly state how you want the data grouped or filtered.
  *Example*: “Show candidates grouped by status” or “Create a gallery view of job listings.”

* **Mention layout preferences**: Indicate the desired layout if any — Grid, Kanban, Calendar, etc.

* **Use data cues**: Reference field names or data patterns.
  *Example*: “List interviews scheduled this week” or “Show recently updated resumes.”

***

## Example Prompts for "Use Prompt" Tab

* "Show candidates grouped by status in a Kanban view."
* "Create a calendar view for upcoming interviews."
* "List job openings that have more than 5 applicants."
* "Gallery of candidate profiles with photos and resumes."

***

Start leveraging NocoAI to create powerful views in just a few clicks!


# NocoAI
URL: /docs/product-docs/noco-ai

Smarter Apps, Instantly Built with AI

<Callout type="info">
  NocoAI is available on cloud deployments of NocoDB. It is currently not supported on self-hosted or on-premise installations.
</Callout>

NocoAI brings intelligent automation and AI-powered assistance to the heart of NocoDB. Designed to reduce manual setup and enhance productivity, NocoAI helps you build, extend, and manage your bases using natural language — no technical expertise required.

## Key Features

* **[Prompt-Based Schema Generation](/docs/product-docs/noco-ai/create-base)** : Build a complete base — including tables, fields, and views — by describing your needs in plain language.
* **[Table Recommendations](/docs/product-docs/noco-ai/create-table)** : Get suggestions for additional tables that align with your existing schema and use case.
* **[Field Recommendations](/docs/product-docs/noco-ai/create-field)** : Receive relevant field suggestions based on the context of the table you're editing.
* **[View Recommendations](/docs/product-docs/noco-ai/create-view)**
  Enhance visibility with recommended views tailored to your table’s content.
* **[Select Options Recommendations](/docs/product-docs/noco-ai/create-options)** : When creating single or multi-select fields, NocoAI suggests logical values based on the field name.
* **[Prompt-Based Formula Generation](/docs/product-docs/noco-ai/create-formula)** : Generate complex formulas by describing the logic you need.

## Use Cases

NocoAI is designed for teams of all sizes and skill levels:

* **Non-technical users** can create databases without needing schema knowledge or coding.
* **Product teams** accelerate prototyping and iteration with AI-assisted schema suggestions.
* **Operations managers** get instant view recommendations to streamline workflows.
* **Data teams** automate calculated fields and reduce setup time.

Whether you're building a CRM, project tracker, or content calendar — NocoAI helps you go from idea to working database in seconds.

***

## Roadmap

NocoAI is just getting started. Upcoming enhancements will include:

* Natural language querying
* AI-driven automations
* Text generation
* Advanced recommendations across records and apps

***

## Get Started

To explore NocoAI, open any base or start a new one in NocoDB and look for the NocoAI features in the sidebar, table settings, or formula editor.

Have feedback or ideas? Share them with the NocoDB team using support chat to help shape the future of AI-powered databases.


# NocoSync
URL: /docs/product-docs/noco-sync

Bring external data into NocoDB effortlessly with automated syncs from tools your teams already use.



















<Callout type="info">
  Available on NocoDB Cloud Business plan onwards and Self-Hosted Enterprise Edition.
</Callout>

<img alt="NocoSync Banner" src={__img0} placeholder="blur" />

**NocoSync** is a built-in integration layer in NocoDB that allows you to bring data from external systems directly into your workspace. It keeps your NocoDB tables continuously updated by syncing records from third-party platforms, eliminating the need for manual imports or custom scripts.

Current release introduces support for the **Ticketing** category, enabling you to connect with platforms such as **GitHub, GitLab, Bitbucket, Zendesk, Linear, Freshdesk, and Chatwoot**. Once connected, NocoSync pulls tickets, issues, conversations and related metadata into NocoDB, allowing teams to centralize reporting, automate workflows, and unlock insights across tools.

Additional sync categories—such as **CRM** (Customer Relationship Management), **HRIS** (Human Resources Information System, Accounting), **Accounting**, **ATS** (Application Tracking System) and **File Storage**—will be added in future releases, expanding the types of systems you can bring into NocoDB.

NocoSync runs on a simple setup, supports scheduled syncs, and ensures high reliability, so your workspace always reflects the most recent data from your external sources. It is designed to be flexible, scalable, and accessible to both technical and non-technical users.

***

## How Sync Works

NocoSync is designed around **predefined schemas** for each category, such as Ticketing, ensuring a consistent structure across all supported sources. When a sync is configured, NocoSync automatically creates multiple tables (such as *Ticket*, *User*, *Comment*, and *Team* in case of Ticketing). All required relationships between these tables are generated automatically, mirroring the hierarchy and linkages of the connected source system.

Sync table fields created by NocoSync are **read-only**, as the sync operates strictly one-way—from the source system into NocoDB. Fields that originate from the external source are marked with a flash icon (⚡) and cannot be removed, and sync tables themselves cannot be deleted. While schemas for each sync category are predefined, the actual fields available may vary by source. Different platforms use different naming conventions or may not expose all fields. NocoSync intelligently maps available fields from the source to the predefined schema to maintain consistency.

Users can extend sync tables by adding their own **custom fields** as needed. Beyond the read-only limitations on synced fields, sync tables behave like regular NocoDB tables. They can be shared with collaborators, used in views, and linked to other tables.

Currently, each sync category supports one external source at a time. When multi-source support is introduced, NocoDB will act as a **Unified API** layer across all connected systems, allowing you to query, analyze, and build on top of data coming from multiple platforms through a single, consistent interface. This will significantly simplify integrations and expand the power of NocoSync across complex environments.

Standard operations on Sync fields such as filtering, sorting, grouping, and searching are fully supported. You can create views, dashboards, and reports using synced data just like with any other NocoDB table.

***

## Sync Types

NocoSync provides two sync modes to **manage how data is fetched** from external platforms. These modes help you balance performance, accuracy, and API usage based on your operational needs.

### **Incremental Sync**

Incremental sync fetches only the records that have been created or updated since the last successful sync. This ensures faster sync cycles, minimal load on the external source, and reduced API consumption—making it the recommended option for routine, scheduled syncs. Incremental sync works by tracking timestamps or version markers provided by the source system.

### **Full Sync**

Full sync re-imports the entire dataset from the external source during each run. This mode is helpful in scenarios where historical data needs correction, or the source system does not reliably provide incremental change information. While full sync ensures complete data accuracy, it requires more time and can be resource-intensive—especially for large datasets. It is best used occasionally or in combination with incremental sync.

## Sync Trigger

NocoSync allows you to control when data synchronization should occur through two trigger modes: **manual** and **scheduled**.

### **Manual Sync**

Manual sync lets you trigger the synchronization process on demand. This option is useful when you want immediate updates—such as after making configuration changes, testing a new integration, or verifying data after modifying fields or relationships. Manual sync gives you full control without waiting for the next scheduled run.

### **Scheduled Sync**

Scheduled sync automates data updates at regular intervals, ensuring your NocoDB tables stay current without manual intervention. Scheduled sync currently supports two frequencies:

* **Hourly** – Runs once every hour, suitable for active systems where data changes frequently.
* **Daily** – Runs once every 24 hours, ideal for less dynamic datasets or reporting-focused use cases.

***

## Source Record Delete Handling

NocoSync provides control over how record deletions from the external source are reflected inside NocoDB. This setting helps you decide whether to maintain records for historical visibility or keep your tables strictly aligned with the source system.

### **Ignore**

When set to *Ignore*, NocoDB **retains the record** even if it is deleted at the source. Instead of removing it, NocoSync marks the record to indicate that it has been deleted in the external system. This mode is useful when you want to preserve full history, maintain reporting continuity, or avoid breaking dependencies with linked records.

### **Delete**

When set to *Delete*, NocoDB removes records in sync tables when they are deleted at the source. This option keeps your NocoDB tables fully synchronized and consistent with the external platform.

***

## Add new Sync

To add a new NocoSync integration to your base, follow these steps:

1. Open `Sync` tab from base overview page.
2. Click on the `+ New Sync` button.
   <img alt="New Sync" src={__img1} placeholder="blur" />
3. Sync **Setup** : General configurations
   * Sync name: Provide a name for your sync integration.
   * [Sync type](/docs/product-docs/noco-sync#sync-types): Choose between **Incremental** or **Full** sync modes.
   * [Sync trigger](/docs/product-docs/noco-sync#sync-trigger): Select either **Manual** or **Scheduled** sync. If scheduled, choose the desired frequency.
   * [On delete](/docs/product-docs/noco-sync#source-record-delete-handling): Choose between **Ignore** or **Delete** to define how deletions from the source are managed.
4. Sync **Setup** : Category & Sync scope
   * Select the **Ticketing** category.
   * Choose to sync **All Tables** or **Select Tables** from the predefined schema. For Ticketing, essential tables like Ticket and User are always included.
5. Click on the `Next` button.
   <img alt="Sync Setup" src={__img2} placeholder="blur" />
6. Sync **Source**
   * Select the external platform you want to connect with.
   * Optionally, provide a suitable name for the integration.
   * Authenticate and authorize NocoDB to access your data on the selected platform. This involves creating a new connection or selecting an existing one for the integration source. Generate API tokens or OAuth credentials as required by the platform.
   * Additional configuration options may appear based on the selected source, such as specifying repositories for Git-based platforms or selecting specific projects for ticketing systems.
7. Click on the `Next` button.
   <img alt="Sync Source" src={__img3} placeholder="blur" />
8. Sync **Review**
   * Review all configurations made in the previous steps.
   * If everything looks good, click on the `Create Sync` button to finalize the setup.
     <img alt="Sync Review" src={__img4} placeholder="blur" />
9. Logs appear displaying progress of the initial sync. Once complete, the sync tables will be available in your base.
   <img alt="Sync Logs" src={__img5} placeholder="blur" />
   <img alt="Sync Table" src={__img6} placeholder="blur" />

<Callout type="info">
  The initial sync may take some time depending on the volume of data being imported. Subsequent syncs will be faster, especially when using incremental mode.
</Callout>

<Callout type="info">
  Currently, NocoSync supports adding one sync integration per category in a base. Multi-source support will be introduced in future releases.
</Callout>

***

## Edit Sync

To edit an existing NocoSync integration, open sync tab from base overview page and follow these steps:

1. Click on the sync you want to edit.
2. Modify the desired configurations in the sync setup or sync source steps. Note that, some fields like Sync category & Sync scope cannot be changed after creation.
3. Click on the `Update Sync` button to apply the changes.

## Delete Sync

To delete an existing NocoSync integration, open sync tab from base overview page and follow these steps:

1. Click on `Actions` button corresponding to the sync you want to delete.
2. Select `Delete Sync` from the dropdown menu.
3. Confirm the deletion in the prompt. This will remove the sync integration and all associated sync tables from your base.

<img alt="Delete Sync" src={__img7} placeholder="blur" />
<img alt="Delete Sync" src={__img8} placeholder="blur" />

<Callout type="warning">
  Deleting a sync integration is irreversible and will permanently remove all associated sync tables and data from your base. Ensure you have backed up any important information before proceeding.
</Callout>

***


# Ticketing
URL: /docs/product-docs/noco-sync/ticketing

Bring ticketing data from popular platforms into NocoDB with automated syncs.

















<Callout type="info">
  Available on NocoDB Cloud Business plan onwards and Self-Hosted Enterprise Edition.
</Callout>

Ticketing Sync enables you to import issues, tickets, comments, users, and team information from external platforms. It follows a predefined schema that standardizes ticketing data across systems, ensuring consistency even when naming conventions or field availability differ between sources.

Current supported sources include:

* GitHub
* GitLab
* Zendesk
* Linear
* Freshdesk
* Bitbucket
* Chatwoot

You may choose to sync **all tables** in the Ticketing schema or **only specific tables**. Syncing all tables provides full context and complete relationships, while syncing selected tables helps reduce sync time and resource usage based on your workflow needs.

***

## Available Tables

Each table is mapped to a well-defined set of fields to maintain a unified structure. NocoSync also includes relational fields that connect these tables as required. Ticket and User tables are essential and always included, while Comment and Team tables are optional.

### **Ticket**

Represents a ticket, issue, case, or task from the source platform.
**Key fields include:**

* **Description** – Summary or full content of the ticket.
* **Ticket Number** – Unique identifier from the source system.
* **Due Date** – Target completion date.
* **Priority** – Indicates urgency such as Low, Medium, High, or platform-specific values.
* **Status** – Current stage (Open, In Progress, Closed, etc.).
* **Tags** – Labels or metadata applied to the ticket.
* **Ticket Type** – Category such as Bug, Feature, Task, Case, etc.
* **URL** – Direct link to the ticket in the source app.
* **Is Active?** – Indicates whether the ticket is currently active.
* **Completed At** – Timestamp when the ticket was closed or resolved.

This table includes links to **Users**, **Teams**, and **Comments**, depending on the structure available in the connected source.

### **User**

Represents individuals associated with the ticketing system—such as creators, reporters, agents, assignees, or contributors.
**Key fields include:**

* **Email** – Email associated with the user.
* **URL** – Profile link to the user in the external system.

Users are linked to **Tickets** and **Comments** where applicable.

### **Comment**

Stores discussion entries, updates, or notes related to Tickets.
**Key fields include:**

* **Body** – Full comment text.
* **URL** – Link to the comment in the source system.

Comments are relationally connected to both **Tickets** and **Users**.

### **Team**

Represents groups, departments, or squads defined in the external platform.
**Key fields include:**

* **Description** – Summary or name of the team.
* **Members** – Users associated with the team.

Teams may be associated with **Tickets** or **Users**, depending on source capabilities.

***

## Metadata Fields

Each synced table in the Ticketing category includes a set of metadata fields that track the lifecycle, state, and origin of every record. These fields provide transparency into how data flows from the external source into NocoDB and play an essential role in traceability, debugging, and audit requirements.

These metadata fields are automatically managed by NocoSync and are read-only.

* **RemoteID**
  Unique identifier of the record in the external source system.

* **RemoteCreatedAt**
  Timestamp of when the record was originally created in the source.

* **RemoteUpdatedAt**
  Timestamp of the most recent update made in the source.

* **RemoteDeleted**
  Indicates whether the record has been deleted in the source platform.
  This is used especially when the delete behaviour is set to **Ignore**.

* **RemoteDeletedTime**
  Timestamp of when the record was deleted in the source, if applicable.

* **RemoteRaw**
  Stores the raw payload received from the provider for that record.
  Useful for troubleshooting, verification, or advanced integrations.

* **RemoteNamespace**
  Identifies the origin project, workspace, or repository depending on the provider.
  This is valuable for multi-project setups in GitHub, GitLab, Bitbucket, Zendesk groups, etc.

* **RemoteSynchedAt**
  Last timestamp when NocoDB synced this specific record.

* **SyncConfigID**
  Internal reference to the sync configuration used for this record.

* **SyncRunID**
  Identifies the specific sync execution run that last updated this record.

* **SyncProvider**
  Indicates which external service (GitHub, GitLab, Zendesk, etc.) the record originated from.

***

## Source Specific Details

Each supported ticketing platform has unique characteristics and field mappings. Below are some source-specific details to consider when configuring your Ticketing sync.

### GitHub

GitHub integration lets you bring issues, pull requests, and related project activity directly into your NocoDB workspace. Connect your GitHub account, pick the repositories you want to track, and NocoSync keeps your tables updated with the latest data.

After selecting GitHub as the sync source, you can:

* **Connect using an existing GitHub integration**
  Authenticate once and reuse the connection across multiple syncs. Both OAuth and Personal Access Token methods are supported.

* **Choose one or more repositories**
  Pull data from any repo you manage or collaborate on. You can select multiple repositories to consolidate issues and PRs in a single NocoDB base.

* **Include closed issues (optional)**
  Sync both open and closed issues to maintain a complete project history. Closed issues are marked accordingly in the Ticket table.

* **Sync pull requests (optional)**
  Bring in PRs alongside issues to track code reviews, merges, and engineering workflows. PRs are represented as tickets with a distinct type.

<img alt="GitHub Ticketing Sync Configuration" src={__img0} placeholder="blur" />

***

### GitLab

GitLab integration lets you sync project activity—issues, merge requests, comments, and more—directly into your NocoDB workspace.

After selecting GitLab as your sync source, you can:

* **Connect using an existing GitLab integration**
  Authenticate once and reuse the connection across multiple projects and syncs. Alternatively, you can set up a new connection using OAuth or Personal Access Token methods.

* **Provide a GitLab Project ID**
  Point the sync to any GitLab project you manage or contribute to. NocoDB validates and fetches data from that project automatically.

[Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#find-the-project-id)

<img alt="project ID" src={__img1} placeholder="blur" />

* **Include closed issues (optional)**
  Sync both open and closed issues to maintain a complete historical record of progress, decisions, and resolutions.

* **Include merge requests (optional)**
  Pull in merge requests alongside issues to track reviews, approvals, and code changes within your workspace.

<img alt="GitLab Ticketing Sync Configuration" src={__img2} placeholder="blur" />

***

### Zendesk

Zendesk integration brings your support operations into NocoDB, enabling teams to analyze tickets, measure response trends, and connect customer support data with internal workflows. With NocoSync, your Zendesk tickets stay continuously updated in a structured, queryable format.

Once you select Zendesk as your sync source, you can:

* **Connect using an existing Zendesk integration**
  Authenticate once and reuse the connection for multiple sync configurations.

* **Define your integration name**
  Label the sync clearly for your workspace, especially when managing multiple Zendesk accounts or environments.

* **Include closed tickets (optional)**
  Sync both open and closed tickets to maintain a complete historical view of customer conversations, resolutions, and team performance.

Zendesk as a source helps centralize customer support insights—making it easier to audit ticket history, build dashboards, correlate support patterns with product issues, and drive proactive decision-making across teams.

<img alt="Zendesk Ticketing Sync Configuration" src={__img3} placeholder="blur" />

***

### Linear

Linear sync brings your product, engineering, and project workflows directly into NocoDB—making it easy to analyze issues, track delivery patterns, and build custom reporting on top of your Linear data.

When setting up a Linear sync, you can:

* **Select your Linear connection**
  Authenticate once and reuse the connection across different sync configurations.

* **Specify a team key**
  Provide the Linear team identifier (e.g., *ENG*) to pull issues from a specific team. This helps maintain clear separation of data when working across multiple teams or departments. To find your team key, go to Linear → Settings → Teams → select your team → copy the Team Identifier (e.g., ENG).

* **Configure issue inclusion options**

  * **Include canceled issues**
    Sync canceled issues to maintain a complete historical timeline of project changes and prioritization decisions.
  * **Include completed issues**
    Sync completed issues for richer analytics on delivery timelines, resolutions, and sprint outcomes.

Linear as a source helps centralize product and engineering operations—allowing teams to correlate progress with other tools, audit issue lifecycle data, and build custom dashboards that reflect true project execution.

<img alt="Linear Ticketing Sync Configuration" src={__img4} placeholder="blur" />

***

### Freshdesk

Freshdesk integration allows you to sync your customer support tickets, agents, and conversations directly into NocoDB. This enables your team to analyze support trends, measure performance, and connect customer data with internal workflows.

When configuring a Freshdesk sync, you can:

* **Connect using an existing Freshdesk integration**
  Authenticate once and reuse the connection for multiple sync configurations. You can also set up a new connection using your Freshdesk domain and API key.

* **Include closed tickets (optional)**
  Sync both open and closed tickets to maintain a complete historical view of customer interactions and resolutions.

<img alt="Freshdesk Ticketing Sync Configuration" src={__img5} placeholder="blur" />

***

### Bitbucket

Bitbucket integration enables you to sync issues, pull requests, and related project activity directly into your NocoDB workspace. This allows your team to track development progress, analyze issue trends, and build custom reports.

When setting up a Bitbucket sync, you can:

* **Connect using an existing Bitbucket integration**
  Authenticate once and reuse the connection across multiple syncs. Both OAuth and App Password methods are supported.

* **Choose one or more repositories**
  Pull data from any repository you manage or collaborate on. You can select multiple repositories to consolidate issues and pull requests in a single NocoDB base.

* **Include closed issues (optional)**
  Sync both open and closed issues to maintain a complete project history. Closed issues are marked accordingly in the Ticket table.

* **Sync pull requests (optional)**
  Bring in pull requests alongside issues to track code reviews, merges, and engineering workflows. Pull requests are represented as tickets with a distinct type.

<img alt="Bitbucket Ticketing Sync Configuration" src={__img6} placeholder="blur" />

***

### Chatwoot

Chatwoot integration allows you to sync conversations, messages, users, and teams directly into NocoDB. This enables your team to analyze customer interactions, measure response trends, and connect communication data with internal workflows.

When configuring a Chatwoot sync, you can:

* **Connect using an existing Chatwoot integration**
  Authenticate once and reuse the connection for multiple sync configurations. You can also set up a new connection using your Chatwoot instance URL and API key.

* **Include resolved conversations (optional)**
  Sync both open and resolved conversations to maintain a complete historical view of customer interactions and resolutions.

<img alt="Chatwoot Ticketing Sync Configuration" src={__img7} placeholder="blur" />

***


# Actions on record
URL: /docs/product-docs/records/actions-on-record

Learn how to perform actions (edit, duplicate, delete, etc) on a record in NocoDB.













## Keyboard navigation within Grid view

A selected cell can be in one of the following states:

1. `Select` state : A single click on the cell selects the cell. When in this state, arrow keys can be used to navigate to adjacent cells.
2. `Edit` state : A double click on the cell puts the cell in edit state. Cursor can be moved within the cell using arrow keys.

<Callout type="note">
  * Double-click on a cell to put it in edit state directly.
  * From Select state, press `Enter` key to enter edit state.
  * Press `Esc` key to exit edit state.
  * From Edit state, press `Enter` key to save the changes.
</Callout>

Edit state for some cells will be a picker. For example, a cell with `Single Select` field type will have a picker with options to choose from. In such cases, arrow keys can be used to navigate between options.

### Keyboard shortcuts for cell navigation

|             Key | Behaviour                                                                            |
| --------------: | :----------------------------------------------------------------------------------- |
|         `⌘` `↑` | Jump to first record in this field (in same page)                                    |
|         `⌘` `↓` | Jump to last record in this field (in same page)                                     |
|         `⌘` `C` | Copy cell contents to clipboard                                                      |
|         `⌘` `V` | Paste clipboard contents to cell                                                     |
|         `Enter` | Switch cell in focus to EDIT mode; opens modal/picker if cell is associated with one |
|           `Esc` | Exit cell EDIT mode                                                                  |
|        `Delete` | Clear cell                                                                           |
|         `Space` | Expand current record                                                                |
| `←` `→` `↑` `↓` | General cell navigation : left, right, top, bottom                                   |
|           `Tab` | Move to next cell horizontally; if on last cell, move to beginning of next record    |

### Update Record

You can start editing by any of the following methods

* Double-click on cell to edit
* Click on cell and start typing (this way it will clear the previous content)
* Click on cell and press enter to start editing

And it will automatically save on blur event or if inactive.

### Bulk Update Records  ☁

You can bulk update records by

1. Selecting multiple records that you wish to update together and then
2. Right-click on the index field area (first column on the grid view) and then select `Bulk Update records` option from the context menu. This will open `Bulk update` modal.
   On the bulk update modal,
3. `Fields area` : Select the fields that you want to update.
4. `Selected fields area` : Enter the new value for the selected fields.
5. Click on the `Bulk Update all` button
6. A confirmation dialog will be displayed. Click on `Confirm` to update the records.

<Callout type="info">
  **This action cannot be undone**
</Callout>

<img alt="Bulk Update" src={__img0} placeholder="blur" />

<img alt="Bulk Update" src={__img1} placeholder="blur" />

<img alt="Bulk Update" src={__img2} placeholder="blur" />

<Callout type="info">
  You can drag drop required fields from the 

  `Fields area`

   to the 

  `Selected fields area`

   & vice versa. You can update multiple fields at a time.
</Callout>

### Delete Record (Single)

Right-click on record and then from the cell context menu, select `Delete Record` option.

<img alt="delete row -1" src={__img3} placeholder="blur" />

### Delete Record (Bulk)

Select multiple records by using the checkbox in first column and then `Delete Selected Records` options from the right click context menu.

<img alt="delete row 2" src={__img4} placeholder="blur" />

### Drag and Drop to reorder records

You can reorder records by dragging and dropping them to the desired position. Use the drag icon on the left side of the record to drag and drop.

<img alt="drag drop" src={__img5} placeholder="blur" />

<Callout type="note">
  * Bulk record drag-drop reordering is not supported currently.
  * Drag-drop is not supported in Group-by view currently.
</Callout>


# Create record
URL: /docs/product-docs/records/create-record

Learn how to create a record in NocoDB.







A new record can be added by using the `New Record` button in the bottom left corner of the grid view. Default behaviour of this button is to add a new empty record at the end of the grid view. Fields for a record can be populated by clicking on the cell and entering the value.

<Callout type="note">
  * An empty record can also be added by using `+` icon in the last record of the grid view.
  * When on last record, `Enter` key can be used to add a new empty record to the grid view.
</Callout>

<img alt="image" src={__img0} placeholder="blur" />

NocoDB also provides convenience of a form to populate fields in a record. To add a new record using a form,

1. Click on the up-arrow in `New Record` button; this expands options for adding a new record.
2. Select `New Record - Form` option. This will reconfigure default behaviour of `New Record` button to add a new record using a form.

<img alt="image" src={__img1} placeholder="blur" />

<Callout type="info">
  To revert back to default behaviour of 

  `New Record`

   button, click on the up-arrow in 

  `New Record`

   button and select 

  `New Record - Grid`

   option
</Callout>

### Insert Anywhere

You can insert a new record anywhere in the grid view by using right-click context menu. Click on any record and select from `Insert above` or `Insert below` options. A new empty record will be added above or below the selected record.

<img alt="insert anywhere" src={__img2} placeholder="blur" />

### Related topics

* [Expanded record view](/docs/product-docs/records/expand-record)


# Expanded record
URL: /docs/product-docs/records/expand-record

Learn how to expand a record & work with it in NocoDB.

































## Overview

`Expanded record` allows you to edit a record data using a form layout. Apart from record information, it also consists of the activity feed such as user comments or record revision history (audit).

<img alt="expanded record" src={__img0} placeholder="blur" />

## Expanding a Record

To expand a record in a grid view, click on `expand` icon that appears on the first column (index column) on hover over a record.

<img alt="expand record icon" src={__img1} placeholder="blur" />

<Callout type="tip">
  Shortcut : Use space bar on any cell to expand associated record.
</Callout>

### Edit record

Expanded form displays all the fields of a record enabled for display in a form layout.

1. You can edit the record data by clicking on the field and entering the value.
2. `Show hidden fields`: Click on `Show hidden fields` button to display all the fields of a record.
3. Click on `Save` button to save the changes. Close the expanded form by clicking on `X` button in the top right corner of the form to discard the changes.
4. Navigate to next/previous record using `Next`/`Previous` button in the top left corner of the form.

<Callout type="info">
  Any changes made to the links field (link/unlink) will be saved automatically
</Callout>

<img alt="edit record" src={__img2} placeholder="blur" />

## Record Audit

In an expanded form,

1. Click on `Audit` tab
2. A list of all the changes made to the record will be displayed

<Callout type="info">
  * You can only view the audit log. You cannot edit or delete the audit log.
  * Audit log is only available in Self-hosted version currently
</Callout>

<img alt="expand record activity feed" src={__img3} placeholder="blur" />

## Record Comment

The Comments feature allows you to collaborate directly within records by leaving comments, making it easier to discuss and track changes. You can also receive [notifications](/docs/product-docs/collaboration/notifications) for updates, ensuring everyone stays informed in real time.

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/U5ZYVlpOGN8?start=12" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

<Callout type="info">
  @mentions & comments resolve feature is only supported in cloud hosted / self-hosted enterprise plans
</Callout>

### Add Comment

In an expanded form,

1. Click on `Comments` tab
2. A list of all the comments made to the record will be displayed
3. Click on input box at the bottom to add a new comment, and press `Enter` to save

<img alt="expand record comment" src={__img4} placeholder="blur" />

### Edit Comment

In comments list of an expanded form,

1. Click on `Edit` icon on the right side of the comment
2. Edit the comment and
3. Click on `Save` icon  OR Press `Enter` to save the changes

<img alt="expand record comment" src={__img5} placeholder="blur" />

<img alt="expand record comment" src={__img6} placeholder="blur" />

<img alt="expand record comment" src={__img7} placeholder="blur" />

<Callout type="note">
  You can only edit your own comments. Changes to comments are also recorded in the audit log.
</Callout>

## Record Actions

### Copy Record URL

In an expanded form, click `Copy Record URL` to share the record form to other authorized users.

### Duplicate record

Using context menu (`...`) in the top right corner of the expanded form, you can duplicate the record. Duplicated record will not be saved by default. You can edit the record and save it.

<img alt="delete record" src={__img8} placeholder="blur" />

### Delete record

Using context menu (`...`) in the top right corner of the expanded form, you can delete the record.

<img alt="delete record" src={__img9} placeholder="blur" />

On the confirmation dialog, click on `Delete` button to delete the record.

<img alt="delete record" src={__img10} placeholder="blur" />

## Record view modes

Modern data collaboration requires more than just viewing and editing records—it demands flexible interfaces tailored to specific tasks. Whether you're entering structured data, reviewing files, or engaging in team discussions, having the right record view enhances both productivity and clarity.

This article introduces three powerful modes for interacting with individual records:

* **Field Mode** for structured data entry and editing
* **File Preview Mode** for visually inspecting attachments
* **Discussion Mode** for seamless collaboration and context-rich conversations

Each mode is purpose-built to help you focus on what matters most, ensuring your workflows remain efficient, intuitive, and collaborative.

### Field Mode

Field Mode is designed for editing and viewing all field values of a record. It provides a structured, form-like layout where each field is displayed clearly with its label and value.

<img alt="Field Mode" src={__img11} placeholder="blur" />

### File Preview Mode  ☁

<Callout type="info">
  File Preview Mode is only available in cloud hosted / self-hosted enterprise plans
</Callout>

File Preview Mode prioritizes visual file content by displaying attachments front and center. It’s perfect for image-heavy or document-centric records.

<img alt="File Preview Mode" src={__img12} placeholder="blur" />

1. **Configure attachment field** : File preview mode by default uses first attachment field in the table to display the file. If there are multiple attachment fields, you can choose which one to display by selecting the desired field from the dropdown in the top left corner of the record viewer panel.

2. **Navigate through files** : File preview mode picks up the first file attachment in the record and displays it prominently. If there are multiple attachments, you can hover over left side panel to see a list of all files. Clicking on any file will open it.

3. **Add more files** : You can also add new files directly from this view. Just click on the `+ Add file` icon in the bottom left corner of the file preview panel to upload a new file.

<img alt="File Preview Mode" src={__img13} placeholder="blur" />

#### Supported files

File Preview Mode supports a wide range of media types:

##### 📄 Pdf

##### 🖼️ Image Files

```
.jpeg, .jpg, .png, .gif, .svg, .bmp, .ico, .webp, .avif, .heif, .heifs, .heic, .heic-sequence
```

##### 🔊 Audio Files

```
.mp3, .flac, .wav, .m4a
```

##### 🎞️ Video Files

```
.webm, .mpg, .mp2, .mpeg, .ogg, .mp4, .m4v, .avi, .wmv, .mov, .qt, .flv, .mkv, .3gp, .3g2, .vob, .ts, .mp4a
```

### Discussion mode  ☁

<Callout type="info">
  Discussion Mode is only available in cloud hosted / self-hosted enterprise plans
</Callout>

Discussion Mode brings conversations into context. It shows all comments and threads related to a specific record, fostering collaboration and communication.

<img alt="Discussion Mode" src={__img14} placeholder="blur" />

### Switching between modes

To switch between modes, select a record and look for the mode switcher in the top-right corner of the record viewer panel. Click the icons to toggle between views.

<img alt="Switching modes" src={__img15} placeholder="blur" />


# Records
URL: /docs/product-docs/records

Learn how to create, import, and manage records in NocoDB.

Records in NocoDB are fundamental components within a database, serving as individual entries or data points within a table. Each default table in NocoDB is meticulously organized into a structured grid of records, fields (columns), and cells. These records constitute the backbone of data storage and retrieval within NocoDB, encapsulating a diverse range of information types, including text, numerical values, dates, file attachments, and even links to other records, either within the same table or across different tables. This versatile approach allows users to create highly customizable databases tailored to their specific data management needs, all centered around the concept of records.

In essence, a record can be envisaged as a horizontal collection of data within a NocoDB table, each record representing a distinct piece of information. These records play a pivotal role in organizing, categorizing, and presenting data in a comprehensible and efficient manner, offering users a structured and organized platform for data management.

You can perform a variety of actions to efficiently manage your data. To get started, you can [create a new record](/docs/product-docs/records/create-record) to input essential information. If you need to make updates to an existing record, you can [modify it](/docs/product-docs/records/actions-on-record#update-record) or even perform a [bulk update](/docs/product-docs/records/actions-on-record#bulk-update-records--) for multiple records simultaneously. For records that are no longer needed, you have the option to [delete](/docs/product-docs/records/actions-on-record#delete-record-single) or [duplicate](/docs/product-docs/records/expand-record#duplicate-record) them with ease. When you're working with records, you can also benefit from our expanded form for a more detailed view, complete with a [record change log](/docs/product-docs/records/expand-record#record-audit) to track all modifications and a feature to [write comments](/docs/product-docs/records/expand-record#record-comment) for more context and collaboration. Additionally, you can [share records](/docs/product-docs/records/expand-record#copy-record-url) quickly by generating a shareable URL.

In this section, we'll explore the various aspects of records in NocoDB, equipping you with the knowledge to effectively manage your own data.

## Related topics

* [Create Record](/docs/product-docs/records/create-record)
* [Modify an existing Record](/docs/product-docs/records/actions-on-record#update-record)
* [Bulk Update Records](/docs/product-docs/records/actions-on-record#bulk-update-records--)
* [Delete Record](/docs/product-docs/records/actions-on-record#delete-record-single)
* [Duplicate Record](/docs/product-docs/records/expand-record#duplicate-record)
* [Working with records using an expanded form](/docs/product-docs/records/expand-record)
* [Record change log](/docs/product-docs/records/expand-record#record-audit)
* [Writing comments for a record](/docs/product-docs/records/expand-record#record-comment)
* [Share Record](/docs/product-docs/records/expand-record#copy-record-url)
* [Record Templates](/docs/product-docs/records/record-templates)


# Record Templates
URL: /docs/product-docs/records/record-templates

Learn how to create and use record templates in NocoDB to quickly add records with pre-filled values.





















<Callout type="info">
  Record Templates is available only in cloud-hosted and self-hosted enterprise plans.
</Callout>

Record Templates allow you to define reusable sets of pre-filled field values for a table. When you use a template, NocoDB creates a new record with all the values you defined — including linked records up to three levels deep. This is useful when you frequently create records that share common field values, eliminating the need to fill in the same information repeatedly.

## Manage Templates

The `Manage Templates` modal lets you view, create, edit, enable/disable, and delete all record templates across every table in the current base.

To open the modal, click the up-arrow on the `New Record` button at the bottom of the grid view and select `Manage Templates`.

<img alt="Open Manage Templates from New Record menu" src={__img0} placeholder="blur" />

When no templates have been created yet, the modal displays an empty state with a prompt to create your first template.

<img alt="Empty Manage Templates modal" src={__img1} placeholder="blur" />

Once templates exist, the modal displays a table with the following columns:

* **Enabled** — Toggle to enable or disable a template. Disabled templates are hidden from the add-new-row menu but remain available in the manager.
* **Name** — Template name (must be unique per table).
* **Table** — The table this template belongs to.
* **Sub Records** — Number of linked sub-records (blueprints) defined in the template.
* **Added On** — Date the template was created.
* **Usage** — Number of times the template has been used.
* **Actions** — Use (`+`), Edit, or Delete the template.

<img alt="Manage Templates modal" src={__img2} placeholder="blur" />

You can search templates by name using the search bar, and filter templates by table using the table filter dropdown.

<img alt="Filter templates by table" src={__img3} placeholder="blur" />

## Create a template

1. Open the `Manage Templates` modal.
2. Click the `Create Template` button.
3. Select the **table** for the template using the table selector dropdown at the top left.
4. Enter a **template name**. The name must be unique within the table.
5. Fill in the desired default values for the fields you want pre-populated when the template is used. Leave fields empty to have them remain blank.
6. Optionally, configure linked record fields to include sub-records (see [Sub-records](#sub-records-blueprints) below).
7. Click `Create Template` to save.

<img alt="Create template form" src={__img4} placeholder="blur" />

<img alt="Select table for template" src={__img5} placeholder="blur" />

## Edit a template

1. Open the `Manage Templates` modal.
2. Click the context menu (`⋮`) on the template row and select `Edit`.
3. Modify the template name, field values, or linked record configuration as needed.
4. Click `Save Template` to apply changes.

<img alt="Edit and Delete actions" src={__img6} placeholder="blur" />

## Delete a template

1. Open the `Manage Templates` modal.
2. Click the context menu (`⋮`) on the template row and select `Delete`.
3. Confirm the deletion in the dialog that appears.

## Use a template

There are two ways to create a new record from a template:

### From the Manage Templates modal

Click the **Use** (`+`) action button next to any template in the manager. A new record will be created in the corresponding table with all the template's pre-filled values.

<img alt="Manage Templates modal" src={__img7} placeholder="blur" />

### From the Add New Row menu

1. Click the up-arrow on the `New Record` button at the bottom of the grid view.
2. Select a template from the list. Only **enabled** templates for the current table are shown.
3. A new record is created with the template's pre-filled values.

<img alt="Use template from add new row menu" src={__img8} placeholder="blur" />

## Sub-records (Blueprints)

Record templates can include **sub-records** for linked record fields (Link to Another Record). When a template is used, NocoDB will automatically create the linked records alongside the main record.

Sub-records support nesting up to **3 levels deep**. For example, a `Project` template could include linked `Task` records, each of which could include linked `Subtask` records.

To add sub-records to a template:

1. While creating or editing a template, click `+ New <Table> Record` below a linked record field.
2. Fill in the desired field values for the sub-record. A banner at the bottom confirms you are editing a sub-record that will be created and linked each time the template is used.
3. You can add further nested sub-records in the same way, up to 3 levels.

<img alt="Sub-record blueprint form" src={__img9} placeholder="blur" />

## Enable / Disable a template

Use the toggle in the **Enabled** column of the Manage Templates modal to enable or disable a template. Disabled templates:

* Are **not shown** in the add-new-row template dropdown.
* Remain visible in the Manage Templates modal and can be re-enabled at any time.

## Related topics

* [Create Record](/docs/product-docs/records/create-record)
* [Expanded Record](/docs/product-docs/records/expand-record)
* [Community Edition vs Enterprise Edition](/docs/product-docs/cloud-enterprise-edition/community-vs-paid-editions)


# Field Permissions
URL: /docs/product-docs/roles-and-permissions/field-permissions

Learn about working with field permissions in NocoDB.













<Callout type="info">
  Available on NocoDB Cloud from the 

  **Plus**

   plan onwards, and in 

  **Self-hosted Enterprise**

   editions.
</Callout>

Field permissions in NocoDB allow you to control who can edit values in specific fields in a table. This feature is particularly useful for managing sensitive data or ensuring that only authorized users can modify certain information.

## Enabling Field Permissions

To configure field permissions for a specific table:

1. Access field context menu from the field header.
2. Select **Edit field permissions**.
3. Use the dropdowns to control who can edit the field.

<img alt="Field permissions" src={__img0} placeholder="blur" />

<img alt="Field permissions" src={__img1} placeholder="blur" />

## Permission Levels

You can assign different levels of access to each field. The available options are:

| Option             | Who gets access                                                      |
| ------------------ | -------------------------------------------------------------------- |
| **Editors & up**   | Members with **Editor**, **Creator**, or **Owner** roles *(default)* |
| **Creators & up**  | Members with **Creator** or **Owner** roles                          |
| **Specific users** | Selected members or teams                                            |
| **Nobody**         | No one can edit this field                                           |

By default, users with **Editor** role and above can edit data in all fields in a table.

* Select **Creators & up** to prevent editors from editing values in this field.
* Select **Nobody** to disable editing values for all users in this field.
* Choose **Specific users** to allow only selected members or teams to edit this field.

<Callout type="info">
  Only members and teams with 

  **Editor**

  , 

  **Creator**

  , or 

  **Owner**

   roles can be selected for specific access configuration.
</Callout>

<img alt="Field permissions" src={__img2} placeholder="blur" />

### **Additional Notes on Field Permissions**

* Field permissions **do not control field visibility** — users with access can still view all field data, but their ability to edit values in specific fields depends on the configured permissions.
* Permissions are applied at the **field level**, affecting all records in the table for that specific field. They cannot be configured for individual or selected records.
* Field permissions operate **independently** of table permissions. You can configure field permissions without enabling table permissions, and vice versa.
* Field permissions also apply to **API calls** and **shared forms**, restricting the ability to modify field values through these interfaces.
* Field permissions can be set for all field types except the following, as these are **calculated or system fields** and cannot be edited directly:
  * *Formula*, *Rollup*, *Lookup*, *Created By*, *Last Updated By*, *Created At*, *Last Updated At*, *Button*, *QR Code*, *Barcode*
* For **Link to Another Record (LTAR)** fields, only the source table’s LTAR field permission determines editability (add/remove links). The related table’s LTAR permissions are not considered.
  * *Example:* If **Country** has many **Cities**, and a user has permission to edit the LTAR field in the **Country** table, they can add or remove links to **City** records from the **Country** table — even if they lack edit permission for the **City** table’s corresponding LTAR field.

## Permissions Overview

Permissions overview provides a quick summary of the current table & field permissions in a consolidated tabular view.

To access the permissions overview:

1. Go to base homepage (Click `Overview` in the sidebar).
2. Click the **Permissions** tab.

<img alt="Permissions overview" src={__img3} placeholder="blur" />

Subsequently, you can select the table for which you want to view the permissions overview. The overview will display field permissions in addition to table permissions, allowing you to see who can create or delete records in each table, as well as which fields are editable and by whom.

<img alt="Permissions overview" src={__img4} placeholder="blur" />

`Permissions overview` can also be accessed from the table / field permission configuration modal.

<img alt="Permissions overview" src={__img5} placeholder="blur" />


# Roles & permissions
URL: /docs/product-docs/roles-and-permissions

Learn about roles and permissions in NocoDB.

In NocoDB, roles define what users or teams can do at three levels — **Organization**, **Workspace**, and **Base**.
They govern access control, ensuring that members and teams have appropriate privileges based on their responsibilities.

<Callout type="info">
  Teams feature availability: 

  **Business**

   plan onwards in cloud and On-premise 

  **Enterprise**

   edition
</Callout>

NocoDB follows a hierarchical structure:

```
Organization (Enterprise only)
└── Workspace
    └── Base
```

Organization-level roles govern who can manage the org, its members, and org-wide teams. Workspace and base roles control what users can do with data and collaboration features. These two layers are independent — a user's org role does not affect their workspace or base permissions, and vice versa.

## Organization-level Roles

<Callout type="info">
  Availability: 

  **Enterprise**

   plan only (Cloud & On-premise)
</Callout>

An Organization sits at the top of the NocoDB hierarchy, grouping one or more Workspaces under a single administrative unit. On **Cloud**, an organization is automatically created when a workspace is upgraded to the Enterprise plan. On **On-premise** Enterprise, a single default organization is created automatically for the instance.

All users within an organization are **Org Members**. Each org member is assigned one of three roles:

### **Org Viewer**

* Can access workspaces and bases they have been invited to.
* Cannot create new workspaces.
* Cannot manage org-level settings, members, or teams.

### **Org Creator**

* Has the same access as an Org Viewer, plus the ability to **create new workspaces** within the organization.
* Cannot manage org membership — only the Org Admin can invite or remove users from the organization.

### **Org Admin**

* Has complete access to the organization, including all workspaces and bases.
* Can manage org members (invite, remove, change roles), configure SSO and SCIM, manage domains, manage billing, update org settings (name, logo), and create and manage org-level teams.
* Has access to the [Admin Panel](/docs/product-docs/cloud-enterprise-edition/admin-panel).

<Callout type="info">
  Currently, each organization supports a single Org Admin — the user who creates the organization (or whose workspace is upgraded to Enterprise) is automatically assigned this role. Support for multiple Org Admins per organization is planned for a future release.
</Callout>

<Callout type="info">
  Org roles are separate from workspace and base roles. For example, a user can be an 

  **Org Viewer**

   but a 

  **Workspace Creator**

   — their org role does not restrict their workspace-level permissions.
</Callout>

### Removing an Org Member

When a member is removed from the organization, the removal cascades — the user is also removed from all workspaces, bases, and teams within that organization. Only the Org Admin can remove members from the organization.

## Workspace & Base Roles

You can assign the following roles at the workspace or base level:

* Owner
* Creator
* Editor
* Commenter
* Viewer
* No Access

& a special role "Inherit" discussed below.

If a role is assigned at the base level, it takes precedence over the workspace-level role. Roles are hierarchical — higher roles include all permissions of the roles below them, allowing flexibility and clarity in managing access across your workspace and bases. Details about each role and their permissions are provided below.

### Role Assignment

Roles define access privileges in NocoDB and can be assigned at two levels — **Workspace** and **Base**.

When a member or team is invited to a workspace with a specific role (for example, **Editor**), they automatically receive that level of access across all bases within the workspace, unless overridden at the base level.
Base owners or creators can further refine permissions at the base level to meet specific collaboration needs.

This dual-level role structure provides granular control, balancing workspace-wide consistency with base-specific customization.

Workspace-level roles do not automatically grant access to **Private Bases**. Members must be explicitly invited to a Private Base to gain access, regardless of their workspace role. Learn more about Priavte Bases in the [Private Bases documentation](/docs/product-docs/bases/private-base).

The following sections detail each role and its associated permissions.

### **Owner**

* Assigned automatically to the person who creates a workspace or base.
* Has full administrative privileges, including the ability to delete the workspace or base.
* Only **individual members** can be assigned the Owner role. **Teams** cannot be assigned this role.

### **Creator**

* Has full control over the workspace or base except for deletion privileges, which are exclusive to the Owner.
* Can manage users, schema, automations, and all data operations.
* Suitable for administrators and key project leads.

### **Editor**

* Can add, edit, and delete records within tables.
* Cannot modify the schema, such as adding or removing tables, fields, or relationships.
* Has access to toolbar features like **Filter**, **Sort**, and **Group By** for managing data views.
* Ideal for contributors responsible for day-to-day data management.

### **Commenter**

* Can view records and leave comments on existing entries.
* Cannot edit, delete, or add records.
* **Toolbar access** (Filter, Sort, Group By) is not available.
* Best suited for reviewers or collaborators providing feedback.

### **Viewer**

* Has read-only access to records and comments.
* Cannot make any data changes or leave comments.
* **Toolbar access** (Filter, Sort, Group By) is not available.
* Ideal for external stakeholders who need view-only access.

### **No Access**

* Revokes access entirely to a workspace or base.
* When applied at the workspace level, the user or team cannot access any bases within it.
* When applied at the base level, it restricts access to that base only.

### **Inherit**

"Inherit" is a special role that allows users to derive their permissions based on team assignments within a workspace. It functions as follows:

* At the **workspace** level, allows users to derive their role from team assignments within the workspace.
* At the **base** level, adopts the role defined at the workspace level.
* Offers flexibility in managing roles across multiple bases within a workspace.
* Note: The Inherit role cannot be directly assigned at the workspace level.

If a user is invited to a workspace with the **Inherit** role and then added to a team with the **Viewer** role, the user will have **Viewer** access across all bases within that workspace.
If the user is invited to the workspace with the **No Access** role and later added to a team with the **Editor** role, the user will still have **No Access** in all bases within that workspace.

The **Inherit** role is the only explicit role that allows role derivation from team assignments. For all other roles, explicit workspace roles take precedence over corresponding team roles.

At base level, if a user is assigned the **Inherit** role, their effective role will be determined by their workspace-level role or team-derived role, following the effective role resolution rules outlined below.

## Effective Role Resolution

<Callout type="info">
  Organization-level roles do not participate in workspace or base role resolution. Org roles govern access to the Admin Panel and org-scoped operations only. Workspace and base access is resolved independently using the rules below.
</Callout>

Effective permissions for a user at base level are determined by combining explicit (individual) assignments and team-derived assignments using the following precedence rules:

1. Explicit individual role at Base (highest precedence)
2. Best (most permissive) role among Team roles assigned at Base
3. Explicit individual role at Workspace level other than "Inherit"
4. Best (most permissive) role among Team roles assigned at Workspace
5. No-access (default)

**Notes**

* An explicit individual assignment always overrides any team-derived role at the same level.
* Lower-level roles (Base) override higher-level roles (Workspace) when an explicit assignment exists at the lower level.
* When multiple team roles apply, the system chooses the most permissive role (for example, between Viewer and Editor it will choose Editor).

**Base hierarchy**:

`Individual Base role` > `Team Base role` > `Individual Workspace role` > `Team Workspace role` > `No Access`

**Workspace hierarchy**:

`Individual Workspace role` > `Team Workspace role` > `No Access`

When a user belongs to multiple teams, their Team role is determined by the highest (most permissive) role among all their team assignments.

## Roles for Teams

Teams function as a collective access unit for easier management. When a team is assigned a workspace or base role:

* All team members inherit that role automatically.
* Individual user roles can override team-assigned roles if explicitly set.
* A team can be invited at both workspace and base levels for broader or limited access.
* Teams **cannot** be assigned the **Owner** role.
* Teams **cannot** be assigned the **Inherit** role at the workspace level.

<Callout type="info">
  If a team is invited at the workspace level, all its members receive that workspace role unless an individual or base-level role provides different access.
</Callout>

Learn more about Teams & Collaboration here

* [Teams documentation](/docs/product-docs/collaboration/teams)
* [Workspace collaboration](/docs/product-docs/workspaces/workspace-collaboration)
* [Base collaboration](/docs/product-docs/bases/base-collaboration)

***

### Workspace level permissions

The individual who creates the workspace is automatically designated as a Workspace owner.
A workspace can have only one Owner. Access to bases within that workspace is granted to members based on their roles
within the parent workspace. When a member becomes part of a workspace, the role at the workspace level is
automatically applied to them for all bases in that workspace, unless a specific exception is configured
to override at base level.

| Task                                           | Owner | Creator | Editor | Commenter | Viewer |
| ---------------------------------------------- | :---: | :-----: | :----: | :-------: | :----: |
| Invite member to workspace (\***1**)           |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Manage member access to workspace  (\***2**)   |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Remove member access from workspace  (\***3**) |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| View members in workspace                      |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Create a new base                              |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Access existing bases at assigned roles        |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Delete Workspace                               |   ✔️  |    ️    |        |           |        |
| Billing & upgrade options                      |   ✔️  |    ️    |        |           |        |

(\***1**) Members can invite others at or below their own role.

(\***2**) Members can manage access for others at or below their own role.

(\***3**) Members can remove others at or below their own role.

### Base level permissions

#### Collaboration

| Task                                      | Owner | Creator | Editor | Commenter | Viewer |
| ----------------------------------------- | :---: | :-----: | :----: | :-------: | :----: |
| Invite member to base (\***1**)           |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Manage member access to base  (\***2**)   |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Remove member access from base  (\***3**) |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| View members in a base                    |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Share base                                |   ✔️  |    ✔️   |        |           |        |
| Share view                                |   ✔️  |    ✔️   |        |           |        |

(\***1**) Members can invite others at or below their own role.

(\***2**) Members can manage access for others at or below their own role.

(\***3**) Members can remove others at or below their own role.

#### Table & view operations

| Task                                | Owner | Creator | Editor | Commenter | Viewer |
| ----------------------------------- | :---: | :-----: | :----: | :-------: | :----: |
| Add / modify / delete table         |   ✔️  |    ✔️   |        |           |        |
| Add / modify / delete fields        |   ✔️  |    ✔️   |        |           |        |
| Add / modify / delete views         |   ✔️  |    ✔️   |        |           |        |
| Add / modify / delete view sections |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Hide / un-hide / reorder fields     |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Add / modify / delete sort          |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Add / modify / delete filters       |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Add / modify / delete group-by      |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Add / modify / delete row colour    |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |
| Add / modify / delete cell colour   |   ✔️  |    ✔️   |   ✔️   |     ️     |    ️   |

#### Record operations

| Task                           | Owner | Creator | Editor | Commenter | Viewer |
| ------------------------------ | :---: | :-----: | :----: | :-------: | :----: |
| Add / modify / delete record   |   ✔️  |    ✔️   |   ✔️   |           |        |
| View & add comment on a record |   ✔️  |    ✔️   |   ✔️   |     ✔️    |        |
| View record                    |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| Manage record-level security   |   ✔️  |    ✔️   |        |           |        |

<Callout type="info">
  Record visibility can be further refined using 

  [Record-Level Security](/docs/product-docs/roles-and-permissions/record-level-security)

   policies, which allow you to control which records each role, team, or user can access within a table.
</Callout>

#### Automations & advanced

| Task                            | Owner | Creator | Editor | Commenter | Viewer |
| ------------------------------- | :---: | :-----: | :----: | :-------: | :----: |
| Add / modify / delete Webhook   |   ✔️  |    ✔️   |        |           |        |
| ERD (Project & Table relations) |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| API Snippet                     |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |
| API Token                       |   ✔️  |    ✔️   |   ✔️   |     ✔️    |   ✔️   |


# Record-Level Security
URL: /docs/product-docs/roles-and-permissions/record-level-security

Define filter-based policies to control which records each role, team, or user can access in a table.

















Record-Level Security (RLS) lets you define **filter-based policies** that control which records each role, team, or user can see within a table. Unlike table or field permissions that govern entire tables or columns, RLS operates at the **record level** — ensuring users only see the data relevant to them.

<Callout type="info">
  Available in NocoDB Cloud 

  **Enterprise**

   plan and on self-hosted 

  **Enterprise**

   plans.
</Callout>

**When to use RLS:**

* Sales reps should only see their own deals
* Regional managers should see records for their team's territory
* Support agents should only access tickets assigned to them
* Department heads should see records across their team hierarchy

## Enabling Record-Level Security

1. Open the table where you want to configure RLS.
2. Click the `⋯` icon next to the table name in the sidebar and select **Record-Level Security**.

<img alt="Accessing Record-Level Security from table context menu" src={__img0} placeholder="blur" />

The RLS management panel opens, where you can create and manage policies for this table.

<img alt="RLS management panel — empty state" src={__img1} placeholder="blur" />

<Callout type="note">
  Only base 

  **Owners**

   and 

  **Creators**

   can configure Record-Level Security policies.
</Callout>

## Key Concepts

### Policy Types

RLS uses two types of policies:

* **Default Policy** *(optional)* — A fallback policy that applies when no scoped policy matches the current user. Each table can have at most one default policy. If no default policy is configured, unmatched users can see all records.
* **Scoped Policies** — Policies that target specific roles, users, or teams. A table can have multiple scoped policies.

### Default Policy Behaviors

The default policy defines what happens when a user doesn't match any scoped policy:

| Behavior      | Effect                                               |
| ------------- | ---------------------------------------------------- |
| **Show all**  | All records are visible — no filtering applied       |
| **Deny all**  | No records are visible — complete access denial      |
| **Condition** | Apply filter conditions to determine visible records |

When no RLS policies are configured on a table, all records are visible to all users (equivalent to "Show all").

### Subjects

Each scoped policy is applied to one or more **subjects** — the roles, users, or teams the policy targets:

| Subject type | Description                                              |
| ------------ | -------------------------------------------------------- |
| **Role**     | A base-level role: Viewer, Commenter, Editor, or Creator |
| **User**     | A specific individual member of the base                 |
| **Team**     | A team group, with configurable hierarchy scope          |

For team subjects, you can choose the hierarchy scope:

* **Self only** — The policy applies only to direct members of the selected team.
* **Self and descendants** *(default)* — The policy applies to members of the selected team and all its sub-teams.

### Filter Conditions

Policies use the standard NocoDB filter builder to define conditions. Only records matching the filter conditions are visible to users who match the policy's subjects.

Filters support all standard operators (equals, contains, greater than, etc.) and can reference any field in the table. You can also build nested filter groups using AND/OR logic.

### Policy Resolution Order

When a user requests data from a table with RLS enabled, NocoDB evaluates policies in the following order:

1. **Check scoped policies** — If the user matches one or more scoped policies (by role, user ID, or team membership), those policies' filters are combined using **OR** logic and applied.
2. **Fall back to default policy** — If no scoped policy matches, the default policy behavior is applied (show all, deny all, or condition-based filtering).
3. **No policies configured** — If no RLS policies exist on the table, all records are visible.

RLS filters are combined with any existing view filters using **AND** logic. This means a record must satisfy both the view filter and the RLS policy filter to be visible.

## Managing Policies

### Creating a Default Policy

1. Open the RLS panel for the table.
2. Click **Add Default Policy**.
3. Choose the default behavior:
   * **Show all** — All records visible to unmatched users.
   * **Deny all** — No records visible to unmatched users.
   * **Condition** — Define filter conditions for unmatched users.
4. If you selected **Condition**, configure the filter conditions using the filter builder.

<img alt="Default policy editor — behavior options" src={__img2} placeholder="blur" />

### Creating a Scoped Policy

1. Open the RLS panel for the table.
2. Click **Add Policy**.
3. Enter a **policy name** (e.g., "Sales reps see own deals").
4. In the **Apply To** section, select the subjects this policy targets:
   * Choose from **Roles**, **Members** (users), or **Teams**.
   * You can select multiple subjects of different types.
   * For teams, choose the hierarchy scope (self only or self and descendants).
5. Configure the **filter conditions** that determine which records are visible.
6. Save the policy.

<img alt="New scoped policy editor" src={__img3} placeholder="blur" />

<img alt="Selecting subjects — roles, members, and teams" src={__img4} placeholder="blur" />

<img alt="Scoped policy with subjects and filter conditions configured" src={__img5} placeholder="blur" />

### Enabling and Disabling Policies

Each policy has an **enable/disable toggle**. Disabled policies are ignored during evaluation — they remain configured but do not affect record visibility.

### Editing and Deleting Policies

* To **edit** a policy, click the edit icon next to it in the policy list. Modify the name, subjects, or filter conditions as needed.
* To **delete** a policy, click the delete icon and confirm the deletion.

<img alt="Policy list with default and scoped policies — toggle, edit, and delete controls" src={__img6} placeholder="blur" />

<img alt="Policy list with multiple scoped policies" src={__img7} placeholder="blur" />

## Example: Sales Pipeline

Consider a "Sales Pipeline" table tracking deals across a sales organization:

| Field       | Type             | Description                                                         |
| ----------- | ---------------- | ------------------------------------------------------------------- |
| Deal Name   | Single line text | Name of the deal                                                    |
| Value       | Currency         | Deal value                                                          |
| Stage       | Single select    | Pipeline stage (Lead, Qualified, Proposal, Closed Won, Closed Lost) |
| Assigned To | Email            | Email of the assigned sales rep                                     |
| Region      | Single select    | Sales region (North, South, East, West)                             |

**Goal:** Sales reps see only their own deals. Regional sales managers see deals in their region. Everyone else is blocked by default.

### Policy 1: Default Policy — Deny All

Create a default policy with behavior set to **Deny all**. This ensures that any user who doesn't match a scoped policy cannot see any records.

### Policy 2: Sales Reps See Own Deals

| Setting     | Value                                          |
| ----------- | ---------------------------------------------- |
| Policy name | Sales reps – own deals                         |
| Apply to    | Role: **Editor**                               |
| Filter      | `Assigned To` **is equal** `alice@company.com` |

Sales reps (with Editor role) see only the deals assigned to them. Create a separate policy per rep, or assign them by user subject.

### Policy 3: Regional Managers See Team Deals

| Setting     | Value                                             |
| ----------- | ------------------------------------------------- |
| Policy name | Managers – regional deals                         |
| Apply to    | Team: **North Sales Team** (self and descendants) |
| Filter      | `Region` **is equal** `North`                     |

Members of the North Sales Team (and its sub-teams) see all deals in the North region. Create similar policies for other regions as needed.

### How It Works

* **Alice** (Editor role, Assigned To: [alice@company.com](mailto:alice@company.com)) — Matches Policy 2. Sees only deals where `Assigned To = alice@company.com`.
* **Bob** (member of North Sales Team) — Matches Policy 3. Sees all deals where `Region = North`.
* **Carol** (VP of Sales, Creator role, not matched by any scoped policy) — Since Creators are not subjects in any scoped policy, the default policy applies. Carol sees no records. To give Carol full access, either add Creator as a subject in a scoped policy with a "show all" condition, or change the default policy to **Show all** and restrict others instead.
* **Dave** (Viewer role, not in any sales team) — No scoped policy matches. Default policy applies: **Deny all**. Dave sees nothing.

<Callout type="tip">
  When using a 

  **Deny all**

   default policy, remember to create scoped policies for every role or team that needs access, including senior roles like Creator.
</Callout>

## Notes and Limitations

* **Permissions required** — Only base **Owners** and **Creators** can create, edit, or delete RLS policies.
* **Per-table limit** — There is a configurable limit on the number of scoped policies per table (the default policy does not count toward this limit).
* **Fail-closed** — If an error occurs during policy evaluation, access is denied. This ensures that records are never exposed due to a system error.
* **API and views** — RLS policies apply across all views of the table and to API calls. Records filtered out by RLS are not accessible through any interface.
* **Table visibility first** — RLS is evaluated only after [table visibility](/docs/product-docs/roles-and-permissions/table-permissions#table-visibility). If a table is hidden from a user, RLS does not apply — the table is simply inaccessible.
* **View filter interaction** — RLS filters combine with view filters using AND logic. A record must pass both the view filter and the RLS policy filter to be visible.
* **Real-time updates** — Policy changes take effect immediately for all connected users.

***

**Related topics**

* [Roles & Permissions](/docs/product-docs/roles-and-permissions)
* [Table Permissions](/docs/product-docs/roles-and-permissions/table-permissions)
* [Field Permissions](/docs/product-docs/roles-and-permissions/field-permissions)


# Table Permissions
URL: /docs/product-docs/roles-and-permissions/table-permissions

Learn about working with table permissions in NocoDB.





















Table permissions in NocoDB allow you to control **what users can see** and **what actions they can perform** within a table. Visibility determines whether a table exists for a user, while record permissions allow you to define who can create or delete records in that table.

<Callout type="info">
  Table Permissions are available on NocoDB Cloud from the 

  **Plus**

   plan onwards, and on self-hosted 

  **Enterprise**

   editions.
</Callout>

## Table Visibility

Table Visibility determines whether a table and its views are discoverable and accessible to a user within a base. When a table is visible, the user can access and interact with it according to their assigned roles & permissions. When a table is not visible, it is treated as non-existent for that user.

<Callout type="note">
  Only 

  **Base Owners**

   can configure table visibility settings.
</Callout>

Information below lists down various visibility options:

| Option                      | Who can see the table                                    |
| --------------------------- | -------------------------------------------------------- |
| **Creators & up**           | Members with **Creator** or **Owner** roles              |
| **Editors & up**            | Members with **Editor**, **Creator**, or **Owner** roles |
| **Specific users or teams** | Only selected members or teams                           |
| **Everyone**                | All members of the base *(default)*                      |

<Callout type="note">
  Note:

  * By default, all tables are visible to everyone in the base.
  * Table visibility is evaluated before checking record permissions. If a table is not visible to a user, they cannot access it or perform any actions within it, regardless of their record permissions.
  * Hidden tables will be excluded from APIs, Automations, Scripts & Extensions that list or access tables.
</Callout>

### Configuring Visibility

To configure the visibility of a specific table:

1. Click the `⋯` icon next to the table name in the sidebar.
2. Select **Edit table permissions**.
3. Use the dropdown menus against **Who can see this table?** to define visibility.
4. If you select **Specific users or teams**, choose the members or teams who should have access to the table.

<img alt="Table visibility" src={__img0} placeholder="blur" />

<img alt="Table visibility" src={__img1} placeholder="blur" />

<img alt="Table visibility" src={__img2} placeholder="blur" />

Note that, only Base Owners can modify table visibility settings. Other members will not see this option in the menu.

### Visibility Notes

**Shared bases and shared views**
Table visibility affects shared access. Only tables with the visibility option set to **Everyone** are accessible in a shared base or shared view.

**Relational fields**
When a table is hidden from a user, relational fields linking to that table will list only the **display values** of the linked records. Based on their role (Editor+), the user may still link or unlink records from the source table, but cannot open or access the linked records themselves. Lookup and Rollup fields continue to function and display values from the hidden table, without granting visibility or access to that table.

Edit modal for relational fields linking to hidden tables would display table & view names as "Private Table" and "Private View" respectively.

<img alt="Relational field visibility" src={__img3} placeholder="blur" />

**Duplicating bases**
When duplicating a base, only the tables visible to the duplicating user are copied to the new base. Tables hidden from that user are excluded from the duplicated base. Hence, relational fields linking to hidden tables will also be excluded. Formula fields referencing such relational fields may display errors due to missing references.

## Table Record Permissions

Table Record Permissions determine what actions a user can perform on records within a table. When permissions are granted, users can create or delete records according to their assigned roles and configured access levels. When permissions are restricted, those actions are disabled, while the table and its records may still remain visible to the user.

### Configuring Record Permissions

To configure record access permissions for a specific table:

1. Click the `⋯` icon next to the table name in the sidebar.
2. Select **Edit table permissions**.
3. Use the dropdown menus to define who can:
   * Create records
   * Delete records

<img alt="Table permissions" src={__img4} placeholder="blur" />

<img alt="Table permissions" src={__img5} placeholder="blur" />

#### Permission Levels

You can assign different access levels for each action (create or delete record). The available options are:

| Option                      | Who gets access                                                      |
| --------------------------- | -------------------------------------------------------------------- |
| **Editors & up**            | Members with **Editor**, **Creator**, or **Owner** roles *(default)* |
| **Creators & up**           | Members with **Creator** or **Owner** roles                          |
| **Specific users or teams** | Selected members or teams                                            |
| **Nobody**                  | No one can perform this action                                       |

By default, members with the **Editor** role and above can create and delete records in a table.

* Choose **Creators & up** to restrict these actions to creators and owners.
* Choose **Nobody** to disable record creation or deletion entirely.
* Choose **Specific users or teams** to grant access only to selected members or teams.

<Callout type="info">
  Only members and teams with 

  **Editor**

  , 

  **Creator**

  , or 

  **Owner**

   roles can be selected for specific access configuration.
</Callout>

<img alt="Table permissions" src={__img6} placeholder="blur" />

### Record Permission Notes

* Table permissions **do not control record visibility** — users with access can still view all records. However, their ability to create or delete records depends on the configured permissions.
* Permissions are applied at the **table level** and affect all records within that table. They cannot be defined for individual records or specific subsets.
* Table permissions function **independently** of field permissions; each can be configured separately.
* Table permissions also apply to:
  * Record creation or deletion via **APIs**, and
  * Record creation through **shared forms**.

## Permissions Overview

The permissions overview provides a consolidated summary of table and field permissions across the base.

To access the permissions overview:

1. Go to the base homepage (click **Overview** in the sidebar).
2. Click the **Permissions** tab.

<img alt="Permissions overview" src={__img7} placeholder="blur" />

Select the table you want to review. The overview displays both table and field permissions, showing who can see the table, create records, delete records, and the visibility of each field within that table.

<img alt="Permissions overview" src={__img8} placeholder="blur" />

You can also open the **Permissions overview** directly from the table or field permission configuration modal.

<img alt="Permissions overview" src={__img9} placeholder="blur" />

***


# Upload & Download
URL: /docs/product-docs/table-operations/download





NocoDB offers users the ability to export data from the spreadsheet grid in a variety of formats. This feature can be used in conjunction with the **Filter** and **Sort** feature to further refine your data.

## Download Data

To export data as CSV from NocoDB, follow these steps:

1. Click `:` icon in the toolbar to access the table additional operation's menu.
2. Choose the **Download** option.
3. Select the **CSV** as file format.

<img alt="Export" src={__img0} placeholder="blur" />

## Upload Data

To upload data into NocoDB, you can import CSV files directly into your tables. For more information on how to upload data, refer [here](/docs/product-docs/tables/import-data-into-existing-table).

## FAQ

* **I'm having trouble exporting data—it says the pop-up window is blocked.**

  This is a browser-specific issue, not related to NocoDB. If you're using Chrome, follow these [instructions](https://support.google.com/chrome/answer/95472?hl=en\&co=GENIE.Platform%3DDesktop) to unblock pop-ups.

***


# Hide & reorder fields
URL: /docs/product-docs/table-operations/field-operations

Learn how to hide and reorder fields in NocoDB.













Use the **Fields** button in the toolbar to manage

* field visibility
* field order
* cover image in Gallery and Kanban views.
* show / hide system fields
* add new field
* add lookup field using existing relational fields

<img alt="Fields Menu" src={__img0} placeholder="blur" />

## Show / hide fields

To show or hide fields, open the `Fields` menu and toggle the switch next to each field name.

<Callout type="tip">
   For better customization, create multiple grid views with different sets of visible fields. 
</Callout>

<img alt="Show/Hide Fields" src={__img1} placeholder="blur" />

## Rearranging fields

To rearrange field positions, open the `Fields` menu and drag fields using the `⋮⋮` (drag icon) next to each field name.
<img alt="Reorder Fields" src={__img2} placeholder="blur" />

## Show / hide system fields

By default, system fields are hidden — you can enable them by selecting **Show system fields**.

<Callout type="info">
  In Gallery and Kanban views, this option appears as 

  **Edit Cards**

   in the toolbar.
</Callout>

<img alt="Show system fields" src={__img3} placeholder="blur" />

## Change cover field

In Gallery and Kanban views, you can change the cover field by clicking `Cover image` field in the `Edit Cards` menu. Only fields of type Attachment can be used as cover fields. You can also use the Settings button in the same menu to adjust image display properties like `Fit image` or `Cover image`.

<div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
  <img src="/img/v2/table-operations/fields-gallery-1.png" alt="Change cover field 1" style={{ maxWidth: '48%' }} />

  <img src="/img/v2/table-operations/fields-gallery-2.png" alt="Change cover field 2" style={{ maxWidth: '48%' }} />
</div>

## Add new field

To add a new field, click the `+ New Field` button at the bottom of the `Fields` menu. This opens the field creation modal where you can select the field type and configure its properties.

## Add lookup field using existing relational fields

To add a lookup field based on an existing relational field, click relational field in the `Fields` menu. This opens a modal where you can select the target field to create a lookup field. Click `Add n lookup field(s)` to complete the process.

<img alt="Add Lookup Field" src={__img4} placeholder="blur" />

## Hide field labels ☁

<Callout type="new">
  This feature is available on NocoDB Cloud and Enterprise plans.
</Callout>

In **Gallery** and **Kanban** views, you can hide field labels (headers) shown inside each record tile/card. This helps create a cleaner, more compact card layout—especially useful when cards are used for visual scanning.

**Steps**

Open the **Gallery** or **Kanban** view.

1. Click the **More options (⋮)** menu in the view toolbar.
2. Select **Hide field header** / **Show field header** to toggle the setting.

<img alt="Hide Field Header" src={__img5} placeholder="blur" />

Once enabled, field names (labels) are hidden and only field values are shown on the record tiles/cards.

<Callout type="info">
  This setting is view-specific and applies only to Gallery and Kanban views. Grid view is not affected.
</Callout>

<Callout type="tip">
  Use this option along with field reordering and cover image settings to design compact, dashboard-friendly cards.
</Callout>

***


# Filtering records
URL: /docs/product-docs/table-operations/filter

Learn how to filter records in NocoDB.

























<img alt="Filter" src={__img0} placeholder="blur" />

Filters help you narrow down and organize data based on specific conditions. NocoDB supports:

* **Nested filters**: Combine multiple conditions across different fields.
* **AND / OR logic**: Choose how filters are grouped.

Use filters to focus only on the records that matter to you.

<Callout type="tip">
  You can also 

  [create filters using natural language with NocoAI](/docs/product-docs/noco-ai/create-filter)

  . Just describe what data you want to see, and AI will set up the filter conditions for you.
</Callout>

## Add or edit filters

1. Click the **Filter** button in the toolbar.
2. Choose **Add filter** or **Add filter group**.
3. Set up each filter by selecting a **Field**, **Operation**, and (if needed) a **Value**.
4. To refine results further, combine multiple filters using **AND** or **OR** logic.

<img alt="Add Filter" src={__img1} placeholder="blur" />

### Group filters

You can group multiple filters together using a `Filter Group` to build complex, nested conditions. This allows you to combine filters using either `AND` or `OR` logic, enabling more precise control over your data. To create a filter group, click the `Filter` button in the toolbar and choose `+ Add filter group`. Within a group, you can add individual filters or even nest additional groups.

<img alt="Grouped Filters" src={__img2} placeholder="blur" />

## Delete filters

<Callout type="info">
  NocoDB supports upto 5 levels of nested filter groups.
</Callout>

To remove a filter, click on the trash / bin icon located to the right of the respective filter.

<img alt="Delete Filter" src={__img3} placeholder="blur" />

## Filter by current user ☁

<Callout type="info">
  This feature is available in NocoDB Cloud and NocoDB Enterprise Edition.
</Callout>

You can filter records based on the currently logged-in user using the **Current User** option when configuring filters on **User fields** and their derivatives (such as `createdBy` and `updatedBy`). This is especially useful for creating views that show only the records relevant to the user viewing them.

<img alt="Filter by Current User" src={__img4} placeholder="blur" />

When a dynamic **Current User** filter is applied, the toolbar shows an **@** icon next to the filter count as an indicator.

<img alt="Filter by Current User" src={__img5} placeholder="blur" />

<Callout type="warning">
  **Current User**

   filters do not apply in publicly shared views. If no other filters are present, the shared view will display no records.
</Callout>

## Toggle filters ☁

<Callout type="info">
   This feature is available on the Plus plan and above in NocoDB Cloud and NocoDB Enterprise Edition.
</Callout>

Toggle filters let you temporarily enable or disable individual filters without deleting them. This is useful when you want to quickly compare filtered and unfiltered views, or try different combinations of conditions without rebuilding them each time.

Each filter row includes a **checkbox** on the left side. Unchecking it disables the filter — the condition is preserved but no longer applied to the view. The toolbar badge shows a count in the format **enabled/total** (e.g., `2/5`) when some filters are disabled, so you always know how many are active.

<img alt="Toggle Filters" src={__img6} placeholder="blur" />

Toggle filters work with both individual filters and filter groups. When a filter group is disabled, all filters within that group are also disabled. Disabled filters remain saved in the view and can be re-enabled at any time.

## Pinned filters ☁

<Callout type="info">
  This feature is available on the Plus plan and above in NocoDB Cloud and NocoDB Enterprise Edition.
</Callout>

Pinned filters give you quick, one-click access to frequently used filters directly from the toolbar — without needing to open the filter menu. A pinned filter appears as a compact pill in the toolbar showing the field name and current value. Clicking the pill opens a dropdown where you can search and change the value instantly.

<img alt="Pinned Filters" src={__img7} placeholder="blur" />

### Pin a filter

1. Click the **Filter** button in the toolbar and locate the filter you want to pin.
2. Click the **Pin** icon to the right of the filter row.
3. The filter appears as a pill in the toolbar, ready for quick access.

To unpin a filter, click the **Pin** icon again on the filter row — it will be highlighted for pinned filters.

### Using pinned filters

Clicking a pinned filter pill opens a dropdown panel directly in the toolbar. From here you can search for values, select or deselect options, and changes are applied to the view immediately. The dropdown also includes a **Clear value** option to reset the filter.

<img alt="Pinned Filter Actions" src={__img8} placeholder="blur" />

Each pill includes a **toggle icon** to quickly enable or disable the filter without opening the filter menu.

### Negated operators

When a pinned filter uses a negated operator (e.g., **is not**, **is not any of**), the pill displays a **diagonal strikethrough line** over the selected values. This visual cue makes it easy to distinguish between inclusive and exclusive filters at a glance.

<img alt="Pinned Filter Negated" src={__img9} placeholder="blur" />

### Supported field types

Pinned filters are supported for the following field types:

* **Single Select**
* **Multi Select**
* **User**
* **Created By**
* **Last Modified By**

### Limitations

<Callout type="info">
  You can pin up to 

  **3 filters**

   per view.
</Callout>

Only one filter per field can be pinned at a time — if a field already has a pinned filter, additional filters on the same field cannot be pinned. Filter groups cannot be pinned; only individual filters support pinning.

Pinned filters are not available for editor roles in collaborative or locked views. In personal views, editors have full access to pin and interact with pinned filters.

## Filters for editor role

In **collaborative and locked views**, editors have limited control over filters. Filters configured by creators are displayed as **read-only** — editors can see them but cannot modify, delete, toggle, or pin them. Editors can add their own filters, but these are **temporary** and do not persist across page refreshes. The toolbar badge reflects the combined count of both persisted (creator) and temporary (editor) filters.

In **personal views**, editors have full control — they can create, edit, delete, toggle, and pin filters just like creators.

## Enabling NULL and EMPTY filters

By default, filters like `is null`, `is not null`, `is empty`, and `is not empty` are hidden in the filter menu. To use them explicitly, go to [Base settings](/docs/product-docs/bases/actions-on-base#base-settings) and enable **Show NULL and EMPTY filter**.

Before enabling the setting:

<img alt="Show isBlank" src={__img10} placeholder="blur" />

After enabling it, you’ll see additional options like `is null` and `is empty`, which let you filter out cells with `NULL` or empty values.

<img alt="Show NULL and EMPTY Filter" src={__img11} placeholder="blur" />

Alternatively, you can use **is blank** and **is not blank** filters to handle both NULL and EMPTY values in a simplified way.


# Full Screen
URL: /docs/product-docs/table-operations/full-screen

Learn how to use the Full Screen mode in NocoDB for an enhanced data viewing experience.





The **Fullscreen Mode** button, available in the toolbar, allows you to expand any view area to occupy the entire screen. This helps you focus on your data by hiding navigation menus and other interface elements.

### Enable Fullscreen Mode

To enable fullscreen, click the **Enter Fullscreen** button on the toolbar.

<img alt="image" src={__img0} placeholder="blur" />

Once activated, the grid view will stretch to cover the entire workspace area.

### Exit Fullscreen Mode

To exit fullscreen, click the **Exit Fullscreen** button that appears in the same position.

<img alt="image" src={__img1} placeholder="blur" />

This feature is especially useful when working with large datasets, as it maximizes screen space for better visibility and navigation.


# Grouping records
URL: /docs/product-docs/table-operations/group-by

Learn how to group records in NocoDB.









<img alt="Grouping records" src={__img0} placeholder="blur" />

Grouping records in NocoDB helps you organize data by categories using **Groups** and **Subgroups**. You can group records by up to **three levels**, making it easier to analyze and navigate complex datasets.

## Add or edit groups

1. Click **Group By** in the toolbar.
2. Select the field to group records by.
3. (Optional) Sort the groups in ascending or descending order.
4. (Optional) Use `+ New Subgroup` to create a subgroup within the selected group.

<img alt="Group By" src={__img1} placeholder="blur" />

<Callout type="info">
  You can add up to 

  **three levels of grouping**

   to further refine your data view.
</Callout>

## Delete groups

1. Click **Group By** in the toolbar.
2. Click the 🗑 icon next to the group you want to remove.

<Callout type="info">
  To return to the standard grid view, remove all configured groups.
</Callout>

<img alt="Group By" src={__img2} placeholder="blur" />

## Group level field aggregations

You can perform aggregations on fields at each group level. This allows you to summarize data within each group, such as calculating totals or averages.

<img alt="Group Aggregation" src={__img3} placeholder="blur" />


# Table operations
URL: /docs/product-docs/table-operations

Learn how to work with filters, sort, group by, and more in NocoDB.

The toolbar provides a set of tools to interact with the data in the table. The toolbar is located at the top of the view area.

### Available Tools

* [Hide & Reorder Fields](/docs/product-docs/table-operations/field-operations)
* [Filter](/docs/product-docs/table-operations/filter)
* [Sort](/docs/product-docs/table-operations/sort)
* [GroupBy](/docs/product-docs/table-operations/group-by)
* [Row height](/docs/product-docs/table-operations/row-height)
* [Quick Search](/docs/product-docs/table-operations/search)
* [Full Screen](/docs/product-docs/table-operations/full-screen)
* [Download](/docs/product-docs/table-operations/download)

For a visual guide on how to use the toolbar and its features, check out this video:

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/pvwoZ7vzWNI?si=eZ00r_p5hhuE1mQW?&start=16" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>


# Colouring records
URL: /docs/product-docs/table-operations/record-colouring

Learn how to colour records and individual fields in NocoDB.

















<Callout type="info">
  In NocoDB Cloud, row colouring is available on the Plus plan and higher, while cell colouring is available on the Business plan and higher. In Self-hosted deployments, both row colouring and cell colouring are available only with the Enterprise License.
</Callout>

<img alt="Record colouring" src={__img0} placeholder="blur" />

In NocoDB, you can apply colours to records in a table to visually distinguish them based on specific criteria. This feature is particularly useful for highlighting important information or categorizing records. Record colouring is available for Grid, Gallery, Kanban & Calendar views.

When using conditions-based colouring, you can choose between two colouring modes:

* **Row colouring** — applies colour to the entire record (available on Plus plan and higher)
* **Cell colouring** — applies colour to a specific field within the record (available on Business plan and higher)

Colouring is applied at view level; hence, configuring colour in one view will not affect the same record in another view.

## Add record colour

You can access the record colouring options by clicking the `Colour` button in the toolbar of any table view.
<img alt="Colour records" src={__img1} placeholder="blur" />

You can colour your records based on

1. Single select field
2. Conditions

### Based on single select field

To colour records based on a single select field, follow these steps:

1. Click the `Colour` button in the toolbar.
2. Select the `Using Single select field` option.
3. Choose the single select field you want to use for colouring records from the dropdown menu.

When colouring records using a single select field, each record inherits the colour associated with its selected option in that field. Records without a value in the selected field will not be coloured. This behaviour is predefined and cannot be customized.

<img alt="Colour records based on single select field" src={__img2} placeholder="blur" />

Row colouring by default applies a left border to the records in the table view. You can additionally apply background colour to the records by toggling the `Background colour` option.

<img alt="Background colour" src={__img3} placeholder="blur" />

### Based on conditions

To colour records based on conditions, follow these steps:

1. Click the `Colour` button in the toolbar.
2. Select the `Using Conditions` option.
3. Choose the colour you want to apply from the colour picker.
4. Select the colouring mode — `Row` or `Cell` — from the dropdown next to the colour picker.
5. If you selected `Cell`, choose the target field from the field dropdown that appears.
6. Configure the conditions for colouring as required.

{/* ![Colour records based on conditions](/img/v2/table-operations/row-colouring-5.png) */}

You can add multiple conditions to colour records based on different criteria. The conditions are evaluated in the order they are added, and the **first matching condition will determine the colour** applied to the record or cell.

#### Row colouring

When the colouring mode is set to `Row`, the colour is applied to the entire record. This is the default mode.

Row colouring by default applies a left border to the records in the table view. You can additionally apply background colour to the records by toggling the `Background colour` option.

<img alt="Row colouring with conditions" src={__img4} placeholder="blur" />

#### Cell colouring

<Callout type="info">
  Cell colouring requires the Business plan or higher.
</Callout>

When the colouring mode is set to `Cell`, the colour is applied only to the specific field you select. This is useful when you want to draw attention to a particular field value without colouring the entire row.

To configure cell colouring:

1. Select `Cell` from the colouring mode dropdown next to the colour picker.
2. Choose the target field from the field selector that appears.
3. Configure the conditions and toggle the `Background colour` option as needed.

<img alt="Cell colouring configuration" src={__img5} placeholder="blur" />

When background colour is enabled, the selected field's cell is highlighted with the chosen colour. When background colour is disabled, a vertical colour indicator bar appears on the left edge of the field.

{/* ![Cell colouring in grid view](/img/v2/table-operations/cell-colouring-grid.png) */}

{/* ![Cell colouring in grid view - background mode](/img/v2/table-operations/cell-colouring-grid-bg.png) */}

<Callout type="note">
  Cell colouring is available only in Grid view.
</Callout>

#### Combining row and cell colouring

You can configure both row and cell colouring conditions within the same view. Each condition can independently be set to either `Row` or `Cell` mode. When both row and cell colouring apply to the same record, the cell colour takes precedence over the row colour for the targeted field, while the remaining fields display the row colour.

{/* ![Combined row and cell colouring](/img/v2/table-operations/combined-row-cell-colouring.png) */}

## Modify record colour

* For record colouring based on single select field, you can modify the colour associated with each option in the single select field by using edit-field option.
* For record colouring based on conditions, you can modify the conditions, colouring mode (`Row` or `Cell`), target field, and the associated colours as required from the dropdown menu that appears when you click the `Colour` button in the toolbar.

Note that, it's not possible to have different colour for single select field options in different views. The colour associated with each option in the single select field is consistent across all views where that field is used for colouring records.

## Remove record colour

You can remove the colouring applied to records in a table view by following these steps:

### Single select field case

* Click the `Colour` button in the toolbar.
* Remove conditions one by one by clicking the `delete` button next to each condition.
  <img alt="Remove colouring" src={__img6} placeholder="blur" />

### Conditions case

* Click the `Colour` button in the toolbar.
* Click "Remove colouring" button from the dropdown.
  <img alt="Remove colouring" src={__img7} placeholder="blur" />

***


# Record height
URL: /docs/product-docs/table-operations/row-height

Learn how to adjust the height of records in NocoDB.











NocoDB offers users the flexibility to adjust the display height of records within the spreadsheet grid to four distinct levels: **Short** (the default setting), **Medium**, **Tall**, and **Extra**. This feature proves valuable when working with extensive text fields and multi-select fields, as it enables users to present a greater amount of content within each cell.

<img alt="record height" src={__img0} placeholder="blur" />

### Short

<img alt="Short" src={__img1} placeholder="blur" />

### Medium

<img alt="Medium" src={__img2} placeholder="blur" />

### Tall

<img alt="Tall" src={__img3} placeholder="blur" />

### Extra

<img alt="Extra" src={__img4} placeholder="blur" />

***


# Search
URL: /docs/product-docs/table-operations/search

Learn how to search for records in NocoDB.







NocoDB provides a quick search feature in the toolbar that helps you locate records efficiently across large datasets. You can search by a specific field or across all fields, and combine this with filters to narrow down the results further.

To use search:

1. Click the **Search** button in the toolbar.
2. (Optional) Select the **Field** to search within.
3. Enter your search term in the search bar.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />
<img alt="image" src={__img2} placeholder="blur" />


# Sorting records
URL: /docs/product-docs/table-operations/sort

Learn how to sort records in NocoDB.







<img alt="Sorting records" src={__img0} placeholder="blur" />

Sorting enables you to arrange your data alphabetically (A → Z) or (Z → A) for text based types and in ascending or descending order for numerical types. NocoDB supports nested sorting, allowing you to select fields and the order in which to apply nested sorting.

### Add or edit sort

1. Click the `Sort` button in the toolbar menu.
2. Choose the `Field` to sort by.
3. Configure the sorting `Direction` : ascending or descending
4. Use `+ Add Sort Option` to add additional fields for sorting.

<img alt="Sort Field" src={__img1} placeholder="blur" />

<Callout type="info">
  The field listed at the top is used for 

  **primary sorting**

  , followed by other fields in 

  **top-down order**

   for secondary and tertiary sorting.
</Callout>

### Delete sort

* Click the `Sort` button in the toolbar.
* Click on the trash / bin icon to the right of the sort you wish to delete.

<img alt="Delete Sorting" src={__img2} placeholder="blur" />

***


# Actions on table
URL: /docs/product-docs/tables/actions-on-table

Learn how to rename, duplicate, and delete a table in NocoDB.



















## Rename table

1. Click the `...` (ellipsis) next to the table name in the left sidebar and select `Rename table` from the context menu.
   * Alternatively, double-click on the table name in the left sidebar to make it editable.
2. Enter the new name for the table in the input field that appears. Use the `Enter` key to confirm the new name or click outside the input field to save changes.

<img alt="image" src={__img0} placeholder="blur" />

<img alt="image" src={__img1} placeholder="blur" />

## Change table icon

1. Click the current table icon next to the table name in the left sidebar.
2. Choose a new icon from the available options.

<img alt="image" src={__img2} placeholder="blur" />

## Duplicate table

1. Click the `...` (ellipsis) next to the table name in the left sidebar and select `Duplicate table`.
2. (Optional) In the dialog:
   * Use **Include data** to copy the table with or without its records.
   * Use **Include views** to copy it with or without its saved views.
3. Click **Duplicate Table**.

A new table will be created based on your selected options.

<img alt="image" src={__img3} placeholder="blur" />

<img alt="image" src={__img4} placeholder="blur" />

**Additional notes**

* Duplicate table will be created in the same base as the original table
* Duplicate table will carry suffix ` Copy` in its name.
* Duplicate table option is not available for `External DB` bases

## Delete table

<Callout type="info">
  **This action cannot be undone**
</Callout>

1. Click the `...` (ellipsis) next to the table name in the left sidebar and select `Delete table`.
2. In the confirmation dialog, click `Delete Table` to confirm.
   <img alt="image" src={__img5} placeholder="blur" />

<img alt="image" src={__img6} placeholder="blur" />

## Add / edit table description

Table description can be added by clicking on the `Add Description` button on the table creation modal or by clicking on the `Edit Description` button from the table context menu. Description for a table will be visible as a tooltip when hovering over the `info` icon next to the table name in the left sidebar.

<img alt="image" src={__img7} placeholder="blur" />

## Table permissions

<Callout type="info">
  Table permissions are available in NocoDB cloud- Plus plan onwards and Self hosted Enterprise plans
</Callout>

Table permissions in NocoDB let you control who can create or delete records in each table. Find more details [here](/docs/product-docs/roles-and-permissions/table-permissions)

## Find table ID

Each table in NocoDB has a unique ID (prefixed with `m`, short for *model*) that identifies it within a base.

You can find the table ID in the URL when viewing a table.

Example:

```
https://app.nocodb.com/#/wqd7e84kkpg8169/pqh6trao813gar7/mxo5v3uj1l1xjpz
```

In this example, the table ID is: `mxo5v3uj1l1xjpz`

You can also copy the table ID by clicking the `...` (ellipsis) next to the table name and selecting **Copy Table ID**.

<img alt="image" src={__img8} placeholder="blur" />

**Usage**: Table IDs are commonly used in API calls, scripting, and integrations where you need to reference a specific table.

***


# Create table via import
URL: /docs/product-docs/tables/create-table-via-import

Learn how to create a table in NocoDB via import from CSV, Excel or JSON.











## Import table from CSV / Excel / JSON

### Accessing import modal

There are two ways to access import modal:

#### 1. From the base dashboard

<img alt="import data" src={__img0} placeholder="blur" />

<img alt="import from dashboard" src={__img1} placeholder="blur" />

#### 2. From the base context menu

<img alt="import from sidebar" src={__img2} placeholder="blur" />

### Importing file

To import a file, follow the steps below:

1. There are two ways to upload source file:
   * **Upload** : Upload from local directory. Either click 'browse file' or drag and drop file.
   * **Add from URL** : Specify the URL of the file.
2. (*optional*) Select character encoding. By default, it is set to `UTF-8`.
3. (*optional*) Configure [Advance Settings](#advanced-settings)
4. Click on `Import` button.
5. (*optional*) Specify the table name. By default, the file name will be used as the table name.
6. (*optional*) Select the columns from the CSV to be included in the table. By default, all fields are included.
7. (*optional*) Modify the field name. By default, the field name is the same as the column name in the CSV.
8. Click on `Import` button to start importing the file.

<img alt="import data" src={__img3} placeholder="blur" />
<img alt="import data" src={__img4} placeholder="blur" />

Additional notes

* Multiple files can be imported at once.
* Supported file formats: CSV, Excel, JSON
* Maximum file size: 5 MB
* All fields are imported by default as `Single line text`. Field type as required can be changed after file is imported.
* By default, the first field will be chosen as Display Value.

### Advanced Settings

* **Use first record as header**: Enabled by default. If selected, the first record in the spreadsheet will be treated as the header record and its contents will be used as field names.
* **Import data**: Enabled by default. If selected, all data will be imported; otherwise, only the table will be created.

***


# Create table
URL: /docs/product-docs/tables/create-table

Learn how to create a table in NocoDB.







## Create a new table

To create a table from scratch:

1. Click **+ Create New** in the left sidebar.
2. From the dropdown, select **Table**.
3. (Optional) Provide a name for the table in the modal that appears.
4. (Optional) Use **Add Description** to include additional context or details.
5. Click **Create Table** to complete the setup.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

## Creating table Using AI

<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

NocoAI can provide a set of suggested tables based on your current schema and context. The tables thus created will include relevant fields and will be linked to existing tables where applicable. This allows you to quickly expand your database structure without manually defining each table and its relationships.

<img alt="image" src={__img2} placeholder="blur" />

For more details on how to use this feature, refer to the [NocoAI documentation](/docs/product-docs/noco-ai/create-table).

***


# Date Dependencies
URL: /docs/product-docs/tables/date-dependency

Define which records are dependent on others. When you reschedule a record, dependent records are automatically rescheduled.









<Callout type="info">
  **Plan availability:**

   Cloud — Business and above · On-Premise — Enterprise Scale and above
</Callout>

Date dependencies let your project schedule update itself. When one record shifts, every record that depends on it automatically adjusts — no manual updates needed.

For example: if a design phase runs a week late, the development and QA records that follow it will automatically move forward to stay in sequence.

{/* ![Grid view showing a Tasks table with Start Date, End Date, Duration, Predecessors, and Status fields](/img/v2/tables/date-dependency/date-dependency-field-icon-tooltip.png) */}

### Requirements

Your table needs the following fields before you can enable date dependencies:

| Field            | Type                                                         | Purpose                                                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Start Date       | Date                                                         | When the record begins                                                                                                                                                                    |
| End Date         | Date                                                         | When the record ends                                                                                                                                                                      |
| Duration         | Number or Duration                                           | How many days the record lasts. A Number field stores days directly; a Duration field is internally converted to days. Optional — NocoDB can calculate duration from start and end dates. |
| Predecessor Link | Link (self-referencing Has-Many, One-to-Many, or One-to-One) | Which record must happen before this one. Optional — only needed if you want records to cascade automatically.                                                                            |

<Callout type="info">
  The 

  **Predecessor Link**

   field is a self-referencing link field (Has-Many, One-to-Many, or One-to-One) that points back to the same table — it creates a relationship between records. For example, if "Development" depends on "Design", you'd link "Design" as the predecessor of "Development".
</Callout>

### Setting up date dependencies

1. Click `...` next to the table name in the left sidebar.
2. Select **Date Dependencies**.

<img alt="Table context menu showing Date Dependencies option" src={__img0} placeholder="blur" />

The dialog opens with date dependencies disabled.

<img alt="Date Dependencies dialog with toggle disabled" src={__img1} placeholder="blur" />

3. Toggle **Enable Date Dependencies** on.
4. Select your **Start Date** and **End Date** fields from the dropdowns.
5. Optionally, select a **Duration** field (Duration or Number type).
6. Optionally, select a **Predecessor Link** field to enable automatic cascading across records.
7. Click **Save**.

<img alt="Date Dependencies dialog fully configured" src={__img2} placeholder="blur" />

<Callout type="info">
  Start Date and End Date must be different fields.
</Callout>

### Include weekends

By default, date calculations include all calendar days (weekends included). Turn off **Include weekends** to skip Saturdays and Sundays in every calculation.

When **Include weekends** is turned off:

* **Duration** counts only business days (Mon–Fri). A record spanning Monday to Friday = 5 days, not 7.
* **End Date** skips weekends. A record starting Monday with a 6-day duration ends on the following Monday (skipping Saturday and Sunday).
* **Cascading** places dependent records on the next business day — never on a Saturday or Sunday.

### How fields stay in sync within a record

Once enabled, NocoDB keeps the date fields in sync whenever you edit a record:

| You change…    | NocoDB auto-updates…                        |
| -------------- | ------------------------------------------- |
| **Start Date** | End Date moves to keep the same duration    |
| **End Date**   | Duration recalculates to match the new span |
| **Duration**   | End Date adjusts to the new length          |

When all three fields are present, Start Date and End Date take priority and duration is recalculated.

Duration counting is **inclusive** — a record from Jan 1 to Jan 10 has a duration of 10 days (both start and end dates are counted). A duration of **0** is valid and represents a same-day task where start and end dates are equal.

All calculations respect the **Include weekends** setting.

### Row propagation

When you set a Predecessor Link field, NocoDB can automatically shift dependent records to keep your timeline consistent. Cascading works in **both directions**:

* **Forward** — when a predecessor's dates change, successors shift later to avoid overlap.
* **Backward** — when a successor is moved earlier and collides with its predecessor, the predecessor shifts earlier to make room.

<Callout type="warning">
  Row propagation (cascade updates across linked records) is only supported on 

  **PostgreSQL**

   and 

  **MySQL 8+**

   data sources. On other databases, only within-record field sync applies.
</Callout>

#### Scheduling mode

Choose how linked records respond when dates change:

| Mode         | What happens                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------- |
| **Off**      | No automatic rescheduling across linked records. Only within-record field sync applies.            |
| **Flexible** | Only adjust when dates overlap or violate the gap. If there's already enough space, nothing moves. |
| **Strict**   | Always snap to the exact gap — no slack allowed. Records shift even when there's no overlap.       |

##### Flexible vs Strict — example

Consider two records with **End → Start** connection and **Gap = 2 days**:

```
Before — gap is 9 days (well above the required 2):

Design:      ████████████
Development:                              ████████████
             Jan 1    Jan 10              Jan 20    Jan 29
                              ←── 9 days ──→
```

Now you move Design's End Date to **Jan 14**:

```
Flexible — gap shrinks to 5, still ≥ 2, so nothing moves:

Design:      ████████████████
Development:                              ████████████
             Jan 1        Jan 14          Jan 20    Jan 29
                              ←─ 5 days ─→  ✓ no violation
```

```
Strict — snaps to exact gap of 2, Development shifts:

Design:      ████████████████
Development:                     ████████████
             Jan 1        Jan 14  Jan 17    Jan 26
                           ←2→
```

Put simply: **Flexible** only prevents overlap, **Strict** enforces the exact spacing at all times.

#### Connection type

Choose how predecessor and successor records relate to each other:

| Type              | Meaning                                   | Example                                                     |
| ----------------- | ----------------------------------------- | ----------------------------------------------------------- |
| **End → Start**   | Successor starts after predecessor ends   | Design ends → Development begins. Most common.              |
| **Start → Start** | Successor starts after predecessor starts | Design begins → QA monitoring begins alongside it.          |
| **End → End**     | Successor ends after predecessor ends     | Development ends → Documentation wraps up at the same time. |
| **Start → End**   | Successor ends after predecessor starts   | Setup must be done before the event kicks off.              |

##### Connection type examples

The examples below use **Strict** mode with **Gap = 0** to show how each connection type works. The predecessor is **Design** (Jan 1 – Jan 10, 10 days).

**End → Start** — Development starts the day after Design ends:

| Record      | Start Date | End Date | Duration |
| ----------- | ---------- | -------- | -------- |
| Design      | Jan 1      | Jan 10   | 10 days  |
| Development | **Jan 11** | Jan 20   | 10 days  |

If Design's End Date moves to Jan 15, Development shifts to start on **Jan 16**.

**Start → Start** — Development starts the same day as Design:

| Record      | Start Date | End Date | Duration |
| ----------- | ---------- | -------- | -------- |
| Design      | Jan 1      | Jan 10   | 10 days  |
| Development | **Jan 1**  | Jan 10   | 10 days  |

If Design's Start Date moves to Jan 5, Development shifts to start on **Jan 5**.

**End → End** — Development ends the same day as Design:

| Record      | Start Date | End Date   | Duration |
| ----------- | ---------- | ---------- | -------- |
| Design      | Jan 1      | Jan 10     | 10 days  |
| Development | Jan 1      | **Jan 10** | 10 days  |

If Design's End Date moves to Jan 15, Development shifts so it ends on **Jan 15** (Start Date adjusts to Jan 6 to maintain duration).

**Start → End** — Development ends the same day as Design starts:

| Record      | Start Date | End Date  | Duration |
| ----------- | ---------- | --------- | -------- |
| Design      | Jan 1      | Jan 10    | 10 days  |
| Development | Dec 23     | **Jan 1** | 10 days  |

If Design's Start Date moves to Jan 5, Development shifts so it ends on **Jan 5** (Start Date adjusts to Dec 27 to maintain duration).

<Callout type="info">
  Note that 

  **End → Start**

   is the only connection type with a +1 offset — the successor starts the 

  *day after*

   the predecessor ends. All other types align dates to the 

  *same day*

  . Use the 

  **Gap (days)**

   setting to add spacing between records for any connection type.
</Callout>

#### Gap (days)

Set a minimum buffer between records. For example, with **End → Start** connection type:

* **Gap = 0** — the successor starts the day right after the predecessor ends.
* **Gap = 3** — there's a 3-day buffer between the predecessor ending and the successor starting.

When **Include weekends** is turned off, gap days count only business days.

### Examples

#### Basic cascade (Strict, End → Start, Gap = 0)

Three records in sequence — **Design → Development → QA**:

```
Before:

Design:      ██████████
Development:           ██████████
QA:                               ██████████
             Jan 1  Jan 10  Jan 20  Jan 30
```

Design overruns — you move its End Date to **Jan 20**. NocoDB shifts the rest automatically:

```
After — cascade ripples forward:

Design:      ████████████████████
Development:                     ██████████
QA:                                         ██████████
             Jan 1            Jan 20     Jan 30     Feb 9
```

Each successor keeps its original duration and the sequence stays intact.

#### Backward cascade (Strict, End → Start, Gap = 0)

Same three records. You move **Development** backward so it starts on **Jan 5** — colliding with Design which ends Jan 10:

```
Before:

Design:      ██████████
Development:           ██████████
QA:                               ██████████
             Jan 1  Jan 10  Jan 20  Jan 30
```

```
You move Development to Jan 5 — it now overlaps Design:

Design:      ██████████
Development:     ██████████
                 Jan 5  Jan 14
                 ↑ collision!
```

NocoDB pushes Design earlier to make room:

```
After — Design shifts backward:

Design: ██████████
Development:       ██████████
QA:                                    ██████████
        Dec 26  Jan 4  Jan 5  Jan 14   Jan 21  Jan 30
```

Design keeps its original duration and shifts backward so Development can start on Jan 5 without overlap.

#### Working days cascade

Same setup but with **Include weekends** turned off. Design ends on **Friday Jan 10**:

| Record      | Start Date      | End Date    | Duration |
| ----------- | --------------- | ----------- | -------- |
| Design      | Mon, Jan 6      | Fri, Jan 10 | 5 days   |
| Development | **Mon, Jan 13** | Fri, Jan 17 | 5 days   |

Development starts on **Monday** — the next business day — not Saturday.

### Automations and webhooks

When NocoDB automatically reschedules dependent records, any automations or webhooks configured on the table will fire for those updated records — so you can notify your team, update a connected tool, or trigger any follow-up action.

### Things to know

* Each table supports one date dependency configuration.
* Start Date and End Date must be **Date** fields (not DateTime).
* Duration must be a **Duration** or **Number** field.
* The Predecessor Link must be a self-referencing link field (**Has-Many**, **One-to-Many**, or **One-to-One**).
* **Include weekends** applies everywhere — both within-record field sync and cascading across records.
* Row propagation (cascade across linked records) is only supported on **PostgreSQL** and **MySQL 8+** data sources.
* When dependent records are automatically rescheduled, they are briefly highlighted with a **light yellow background** in the grid to indicate which records were modified. The highlight fades after about 2 seconds.

<img alt="Grid view showing yellow-highlighted rows after a cascade update" src={__img3} placeholder="blur" />

* Fields that are part of an active date dependency configuration are marked with a small icon in their column header. Hovering the icon shows a **"Date dependencies enabled"** tooltip.
* If you delete a **Start Date** or **End Date** field that is referenced by a date dependency configuration, the configuration is automatically **deactivated**. Deleting a Duration or Predecessor Link field clears only that field reference — the configuration may remain active.
* Cascade-propagated row updates are logged as a distinct **cascade update** in the audit trail, so you can distinguish them from manual edits.
* **Sibling records are not re-propagated.** When a record is moved backward and its predecessor is pushed earlier, other successors of that predecessor (sibling records) are not automatically re-evaluated. Only the direct chain — predecessors upward and successors downward from the edited record — is adjusted. To update sibling records, edit any one of them to trigger a fresh cascade.

### FAQs

**What's the difference between Flexible and Strict?**

**Flexible** only moves records when they would overlap or violate the gap — if there's already enough space, nothing changes. **Strict** always enforces the exact gap you've set, moving records even when there's no overlap.

**What if two records depend on each other in a loop?**

NocoDB detects circular dependencies and stops the cascade safely. No records will be updated in a loop.

**Do automations fire when dates are rescheduled automatically?**

Yes — any automations or webhooks on the table fire for all records that are updated as part of a cascade.

**What does "Include weekends" do?**

When turned on (default), all calendar days including weekends are counted. When turned off, Saturdays and Sundays are skipped in all date calculations — duration counts only Mon–Fri, end dates land on weekdays, and rescheduled records never start on a weekend.

**Which databases support row propagation?**

Cascade propagation across linked records requires **PostgreSQL** or **MySQL 8+**. On other databases (SQLite, etc.), only within-record field sync (Start Date / End Date / Duration calculations) is available.


# Upload data into a table
URL: /docs/product-docs/tables/import-data-into-existing-table

Learn how to upload data into an existing table in NocoDB.







## Import data from CSV / Excel

### Accessing import modal

1. Click on `⋮` context menu from the toolbar.
2. Select `Upload` from the dropdown menu.
3. Select `CSV` / `Excel` option.

<img alt="image" src={__img0} placeholder="blur" />

### Importing file data

1. Select file to upload

   There are two ways to upload source file:

   * **Upload** : Upload from local directory. Either click 'browse file' or drag and drop file.
   * **Add from URL** : Specify the URL of the file.
2. (*optional*) Select character encoding. By default, it is set to `UTF-8`.
3. Advanced Settings : **Use first record as header**
   * Enabled by default. If selected, the first record in the spreadsheet will be treated as the header record and its contents will be used as field names.
4. Click on `Upload files` button.
5. **Mapping Fields** (Optional)
   * You can reconfigure the mapping by utilizing the dropdown menu that appears when you click on the destination field.
   * Existing field names are listed under **NocoDB field** (column to the right), while new fields identified from the import file are listed under **Field** (column to the left).
   * NocoDB automatically maps field names in the import file based on the NocoDB field names.
6. **Exclude fields** (Optional)
   * Uncheck checkbox to exclude a field from being imported.
7. **Allow create missing select field options** (Optional)
   * If enabled, NocoDB will create new options for select fields that are not already present in the table.
8. **Initiate Import**
   * Click on the `Upload` button to commence the file import process.

<img alt="image" src={__img1} placeholder="blur" />

<img alt="image" src={__img2} placeholder="blur" />

On completion, the imported data will be appended to the existing table.

***


# Tables
URL: /docs/product-docs/tables

Learn how to create, import, and manage tables in NocoDB.

Tables are where your data lives in NocoDB — made up of **records** (rows) and **fields** (columns). Each base can have multiple tables, and you can link them to create relationships between datasets.

NocoDB tables function like spreadsheets, with added flexibility:

* View data as a grid, kanban board, gallery, or calendar.
* Perform operations like sorting, filtering, and aggregation.

You can:

* [Create a new table](/docs/product-docs/tables/create-table)
* [Import a table from CSV, Excel, or JSON](/docs/product-docs/tables/create-table-via-import)
* [Import data into an existing table](/docs/product-docs/tables/import-data-into-existing-table)
* [Rename](/docs/product-docs/tables/actions-on-table#rename-table), [duplicate](/docs/product-docs/tables/actions-on-table#duplicate-table), or [delete a table](/docs/product-docs/tables/actions-on-table#delete-table)

Use tables to organize your data your way — flexible, powerful, and easy to manage.

***


# Actions on view
URL: /docs/product-docs/views/actions-on-view

Learn how to delete, rename, duplicate a a view in NocoDB.













































## View context menu

The view context menu provides a set of tools to interact with the view. The view context menu can be accessed by clicking on the ellipsis symbol (`...`) located next to view in the left sidebar.

<img alt="image" src={__img0} placeholder="blur" />

## Rename view

1. Click on the ellipsis symbol (`...`) next to view name located in the left sidebar.
2. Click on the `Rename` option from the view context menu.
3. Enter the desired new view name into the provided field.
4. Use `Enter` key to finalize the renaming process.

<img alt="image" src={__img1} placeholder="blur" />

## Change view icon

1. Click on the existing view icon to the left of the view name in the left sidebar.
2. Select the desired icon from the list of available options.

<img alt="image" src={__img2} placeholder="blur" />

## Duplicate view

1. Click on the ellipsis symbol (`...`) next to view name located in the left sidebar.
2. Click on the `Duplicate` option from the view context menu.
3. Enter the desired new view name into the provided field.
4. Click on the `Duplicate View` button in the confirmation dialog.

<img alt="image" src={__img3} placeholder="blur" />
<img alt="image" src={__img4} placeholder="blur" />

## Delete view

<Callout type="info">
  **This action cannot be undone**
</Callout>

1. Click on the ellipsis symbol (`...`) next to view name located in the left sidebar.
2. Click on the `Delete` option from the view context menu.
3. Click on the `Delete View` button in the confirmation dialog.

<img alt="image" src={__img5} placeholder="blur" />
<img alt="image" src={__img6} placeholder="blur" />

## Lock / Unlock view

Locked views prevent members from modifying view configurations. To lock a view, change the permission type to `Locked` from the view context menu. To unlock a view, change the permission type back to `Collaborative`.

<img alt="Lock / Unlock view" src={__img7} placeholder="blur" />

You can also add a custom message to inform members why the view is locked. This message is visible to all members when they attempt to unlock the view.

<img alt="Lock view message" src={__img8} placeholder="blur" />
<img alt="Unlock view message" src={__img9} placeholder="blur" />

Locked views in sidebar appears with a `lock` icon next to the view name.
<img alt="Locked view sidebar" src={__img10} placeholder="blur" />

## Personal Views ☁

<Callout type="note">
  Personal Views are available in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

Personal Views give exclusive control over view configurations to the owner, while other members have read-only access to view configurations. To assign a view as Personal View, change the permission type to `Personal` from the view context menu. To revert back to Collaborative or Locked view, change the permission type accordingly.

<img alt="Personal view" src={__img11} placeholder="blur" />

You can also assign or change the owner of a Personal View from the left sidebar view context menu.

<img alt="Change personal view owner" src={__img12} placeholder="blur" />
<img alt="Change personal view owner" src={__img13} placeholder="blur" />

Personal view in sidebar appears with a `user` icon next to the view name.
<img alt="Personal view sidebar" src={__img14} placeholder="blur" />

## Add / edit view description

View description can be added by clicking on the `Add Description` button on the view creation modal or by clicking on the `Edit Description` button from the view context menu.

<img alt="Add view description" src={__img15} placeholder="blur" />
<img alt="Edit view description" src={__img16} placeholder="blur" />

Description for a view will be visible as a tooltip when hovering over the `info` icon next to the view name.

<img alt="View description" src={__img17} placeholder="blur" />

## Copy another view's configuration ☁

<Callout type="info">
  Cloud / On-Premises Enterprise Feature
</Callout>

You can copy view configurations from another view to quickly apply the same settings to your current view. This is useful when you want to replicate filters, sorting, field visibility, and other configurations across multiple views.

**Steps to copy view configuration**

1. Click on the vertical ellipsis symbol `⋮` in the toolbar.
2. Select **"Copy another view's configuration"** from the view context menu.
3. In the modal dialog, select the source view from the **Select view to copy from** dropdown. All the views available in the current table will be listed here.
4. Check the **configuration(s)** you want to copy:
   * Field visibility - Copy which fields are visible/hidden
   * Field order - Copy the column arrangement
   * Column width - Copy column width settings
   * Row height - Copy row height settings
   * Filter condition - Copy applied filters
   * Group - Copy grouping settings
   * Sort - Copy sorting settings
   * Row coloring - Copy row color settings
5. Click **"Copy configuration"** to apply the selected settings to your current view.

<img alt="Copy view configuration" src={__img18} placeholder="blur" />
<img alt="Copy view configuration" src={__img19} placeholder="blur" />

Selective "Copy from another view" menu option is also available for various toolbar items like Filter, Group and Sort. This opens up the same copy configuration modal with the respective configuration option pre-selected. You can then choose to copy additional configurations as needed.

<div style={{ maxWidth: '500px' }}>
  <div>
        <img alt="Copy view configuration - Filter" src={__img20} placeholder="blur" />
  </div>
</div>

Note that,

* When copying configurations, the system will only apply settings that are compatible with the current view type. Incompatible settings will be disabled in the copy configuration modal.
* Only views from the same table can be selected as source views for copying configurations.

## Views filtered by `Current User` ☁

NocoDB allows you to filter views based on the currently logged-in user. This is particularly useful for creating personalized views that display records relevant to the user currently logged in. Find more details on how to filter by current user in the [Filtering records by current user](/docs/product-docs/table-operations/filter#filter-by-current-user-) section.

## URL based record filtering

NocoDB enables users to dynamically filter records using query parameters directly in the URL. This is useful when creating sharable views or automating filtered data access in embedded dashboards or internal workflows.

**Basic Syntax**

Filtering is controlled using the `where` query parameter in the following format:

```plaintext
?where=(<field>,<operator>,<value>)
```

**Example**

```plaintext
https://<your-nocodb-url>/#/workspaceId/baseID/tableID?where=(country,eq,France)
https://<your-nocodb-url>/#/workspaceId/baseID/tableID/viewID?where=(country,eq,France)
```

This filters records where the field `country` is equal to `France`.

### Supported Operators

List of supported operators for filtering across various data types are listed below

* [Comparison Operators](/docs/product-docs/developer-resources/rest-apis#comparison-operators)
* [Comparison Sub Operators](/docs/product-docs/developer-resources/rest-apis#comparison-sub-operators)
* [Logical Operators](/docs/product-docs/developer-resources/rest-apis#logical-operators)

### Combining Filters

Multiple conditions can be joined using logical operators:

* `~and` → logical AND
* `~or` → logical OR

**Example**

```plaintext
?where=((country,eq,France)~or(country,eq,Germany))
```

This retrieves records where `country` is either France or Germany.

```plaintext
?where=((country,eq,France)~and(status,eq,Active))
```

This retrieves records where both conditions are true.

***

Conditions can be grouped using nested parentheses to form complex logic:

```plaintext
?where=(((country,eq,France)~or(country,eq,Germany))~and(status,eq,Active))
```

### Filter Precedence: Toolbar vs URL

<Callout type="info">
  Toolbar filters take precedence over URL filters
</Callout>

This means:

* Filters applied manually via the **Filter** menu are evaluated first.
* Then, the URL query parameter filters (`?where=...`) are applied on top of the results.

**Visual Indicator**: As shown in the screenshot below, the toolbar clearly lists both types of filters:

* The user-applied filter: `Segment is equal to Government`
* The URL-applied filter: `Country is equal to France` (listed under **URL Filters**)

<img alt="Filter Menu with URL and Toolbar Filters" src={__img21} placeholder="blur" />

### Additional Notes

* Field names must be exact (case-sensitive).
* URL values must be URL-encoded if they include spaces or special characters.


# Create view
URL: /docs/product-docs/views/create-view

Learn how to create a new view in NocoDB.





## Create new view

1. Click on `+ New View` button below `table name`.
2. Select view type from the dropdown modal.
3. Fill view name in the pop-up modal.
   * For Kanban view, select the `Single select` field to be used as the Kanban field.
   * For Calendar view, select the `Date` OR `DateTime` field to be used as the Calendar field.
   * For Map view, select the `GeoData` field to be used as the Mapped By field.
   * For Timeline view, select the `Date`, `DateTime`, `CreatedTime`, or `LastModifiedTime` field to be used as the start date. Optionally, add an end date field.
4. Click on `Create View` button.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />


# View
URL: /docs/product-docs/views

Learn about Views in NocoDB.



Views in NocoDB allow you to customize how your data is displayed while maintaining independent control over sorting, filtering, and field visibility. Each view retains its own configuration, ensuring that changes made to one view do not affect any others.

This flexibility enables users to organize and visualize data efficiently, providing tailored perspectives for different workflows or team members.

<Callout type="info">
  A View represents data from a table. Any updates made to records in one view are reflected across all other views of the same table.
</Callout>

## Supported View Types

1. [Grid View](/docs/product-docs/views/view-types/grid)
2. [Form View](/docs/product-docs/views/view-types/form)
3. [Gallery View](/docs/product-docs/views/view-types/gallery)
4. [Kanban View](/docs/product-docs/views/view-types/kanban)
5. [Calendar View](/docs/product-docs/views/view-types/calendar)
6. [List View](/docs/product-docs/views/view-types/list) ☁
7. [Map View](/docs/product-docs/views/view-types/map) ☁
8. [Timeline View](/docs/product-docs/views/view-types/timeline) ☁

View the video below for a quick overview of NocoDB Views:

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/gVk5ZwMwANU?si=JcUazOp0SFWyJ6a-&start=24" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

## View Permission Types

Permissions can be applied to each view. By default, all views are **Collaborative**. To view or modify a view’s permission type, open the **View Toolbar Menu** as shown below.

<img alt="Lock / Unlock view" src={__img0} placeholder="blur" />

<Callout type="info">
  All views within a base are visible to every member. Only the ability to edit or modify view configurations can be controlled through view permission type settings.
</Callout>

View configurations include the following items in the toolbar:

* Field visibility
* Field order
* Field width
* Filters
* Sorts
* Groups
* Row Colors
* Row Height

Toolbar access is determined by the member's role. Members with **Editor**, **Creator**, or **Owner** roles have toolbar access by default. Members with **Commenter** or **Viewer** roles do not have toolbar access.

### Collaborative Views (Default)

By default, views are set to **Collaborative**, allowing members with edit permissions or higher to modify view configurations. In this mode, all members with toolbar access can modify view configurations such as field visibility, order, filters, sorts, groups, colors, and row height.

### Locked Views

In a **Locked View**, view configurations cannot be edited until the view is unlocked. Members can read data but cannot modify view settings or content. This mode is ideal for sharing consistent data presentations with others while preventing accidental changes.

Learn more about [Locking and Unlocking Views](/docs/product-docs/views/actions-on-view#lock--unlock-view).

### Personal Views ☁

<Callout type="note">
  Personal Views are available in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

**Personal Views** give exclusive control over view configurations to the owner, while other members have read-only access to view configurations. This mode is similar to Locked Views but allows only the view owner to make configuration changes.

* The owner can reassign ownership or convert the view to **Collaborative** or **Locked**.
* The base owner or creator also retains the ability to manage ownership and lock status.
* For older views without an assigned owner, ownership defaults to the base owner.

Learn more about [Personal Views](/docs/product-docs/views/actions-on-view#personal-views-).

***

## Organizing Views with Sections ☁

As the number of views in a table grows, you can group related views into collapsible **[View Sections](/docs/product-docs/views/view-sections)** in the left sidebar. Sections act as folders — they help you organize views by purpose (e.g., "Reports", "Data Entry", "Team Views") without affecting the data or configuration of the views inside them.

<Callout type="note">
  View Sections are available on the 

  **Business**

   plan and above in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

## General Notes

* When a table is opened, the default view displayed is the first common (non-personal) view, which can be either **Collaborative** or **Locked**.
* Each table must contain at least one common (non-personal) grid view. The last remaining common view cannot be deleted or converted into a personal view.
* The field display order for linked records is determined by the first common (non-personal) grid view of the source table.

***


# Share view
URL: /docs/product-docs/views/share-view

Learn how to share a view publicly in NocoDB.

















Sharing a specific view of a table becomes highly valuable when you need to collaborate with individuals outside your organization who need access to specific sections of your database. This shared view provides a read-only perspective, accessible to anyone, regardless of their workspace affiliation. You have control over which data fields and records are visible to these external viewers, ensuring that any sensitive data remains hidden. Furthermore, if you decide to make changes to the visible fields or records within the view, the shared link will promptly reflect these adjustments, updating in real-time.

## Generate Share View

1. Click `Share` button on the top right of the toolbar
2. Toggle `Enable public viewing` to create shared view link
3. Click `Copy` button to copy the link to clipboard

<img alt="share button" src={__img0} placeholder="blur" />

<img alt="shared view" src={__img1} placeholder="blur" />

### Share view options

### Custom URL

You can customize the URL of the shared view by entering a custom URL in the input field. The custom URL should be unique and should not contain special characters from the set (`/`, `?`, `#`). If the custom URL is already taken, you will be prompted to enter a different custom URL.

To enable custom URL,

1. Click on the `Custom URL` toggle
2. Enter the custom URL in the input field
3. Click on the `Save` button to save the changes

<img alt="custom url" src={__img2} placeholder="blur" />

<Callout type="info">
  Note that, the custom URL is case-sensitive.
</Callout>

#### Password protection

You can enable `Restrict access with a password` if you want a password-protected view

<img alt="password protection" src={__img3} placeholder="blur" />

#### Download options

You can toggle `Allow Download` button to enable or disable download CSV/XLSX options in the shared view link

<img alt="download options" src={__img4} placeholder="blur" />

### Share Form View Options

Form view has additional customizations for shared view. You can enable/disable the following options for shared form view:

1. `Survey mode`: This option when enabled, will display the form in survey mode.
2. `RTL Orientation`: This option when enabled, will display the form in RTL orientation.
3. `Themes`: You can select a theme for the form from the dropdown.
   <img alt="form view options" src={__img5} placeholder="blur" />

## Access Share View

To access the shared view, please follow the steps below:
Click on the `Shared View URL`. If the URL is password-protected, you will be prompted to enter the password to unlock it. Please input the required password to proceed.

<img alt="password modal" src={__img6} placeholder="blur" />

Once the password is successfully entered and authenticated, you will gain access to the shared view.
In the event that the URL is not password-protected, you will be directed to the shared view directly, without the need for a password.

<img alt="share-view" src={__img7} placeholder="blur" />

Users with the shared view link can only view the data and cannot make any changes to the view or its content. Records and fields in the shared view will be updated in real-time as changes are made to the original view. Users accessing shared view can apply filters and sort records as per their requirements.

<Callout type="info">
  Filters & sorts applied to shared view will not be persisted. These filters & sorts will be reset when the shared view is accessed again.
</Callout>

***


# View sections
URL: /docs/product-docs/views/view-sections

Learn how to organize views into collapsible sections in NocoDB.























<Callout type="note">
  View Sections are available on the 

  **Business**

   plan and above in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

View Sections allow you to organize your views into collapsible folders within the left sidebar. As the number of views in a table grows, sections help you group related views together, making it easier to navigate and manage your workspace. For example, you could create sections like "Reports", "Data Entry", or "Team Views" to keep things tidy.

<img alt="View sections overview" src={__img0} placeholder="blur" />

## Create a section

There are two ways to create a new section:

### From the Create View menu

1. Click the `+ Create View` button in the left sidebar, below the table name.
2. Click the `Section` option at the bottom of the dropdown menu.
3. A new section is created with a default name (e.g., "View section"). You can immediately rename it by double-clicking on the section name.

<img alt="Create section from menu" src={__img1} placeholder="blur" />

### From the Move to menu

1. Right-click on a view or click the ellipsis symbol (`...`) next to a view name to open the view context menu.
2. Hover over `Move to...` to open the submenu.
3. Click `New section` to create a new section and automatically move the selected view into it.

<img alt="Create section from move-to" src={__img2} placeholder="blur" />

<Callout type="info">
  Each new section is automatically assigned a unique name. If "View section" already exists, subsequent sections are named "View section 2", "View section 3", and so on.
</Callout>

## Rename a section

1. Double-click on the section name in the left sidebar to enter edit mode.
2. Type the new name.
3. Press `Enter` to save, or press `Escape` to cancel.

Alternatively, you can rename a section from the context menu:

1. Click the ellipsis symbol (`...`) on the section header.
2. Select `Rename section`.
3. Type the new name and press `Enter`.

<img alt="Rename section" src={__img3} placeholder="blur" />

<Callout type="info">
  Section names must be unique within a table. If you enter a name that already exists, an error message is displayed.
</Callout>

## Move views into a section

1. Click the ellipsis symbol (`...`) next to the view you want to move, or right-click on the view name.
2. Hover over `Move to...` in the context menu.
3. Select the target section from the submenu.

<img alt="Move view to section" src={__img4} placeholder="blur" />

The submenu displays all existing sections. You can also:

* Click `New section` to create a new section and move the view into it in a single step.
* Click `Remove from section` (visible only when the view is already in a section) to move the view back to the top level.

## Remove a view from a section

1. Click the ellipsis symbol (`...`) next to the view name inside a section.
2. Hover over `Move to...` in the context menu.
3. Click `Remove from section`.

The view is moved back to the top-level view list, outside of any section.

<img alt="Remove from section" src={__img5} placeholder="blur" />

## Expand and collapse sections

Sections are collapsible, allowing you to hide views you are not currently working with.

* Click on a **section header** to toggle it between expanded and collapsed states.
* When collapsed, views inside the section are hidden from the sidebar (except the currently active view, which always remains visible).

<img alt="Expand collapse section" src={__img6} placeholder="blur" />

### Expand all / Collapse all

To quickly expand or collapse every section at once:

1. Click the ellipsis symbol (`...`) on any section header.
2. Select `Expand all` or `Collapse all`.

<img alt="Expand all collapse all" src={__img7} placeholder="blur" />

<Callout type="info">
  Your expand/collapse preferences are saved per table in your browser and persist across sessions.
</Callout>

## Change section icon colour

Each section displays a folder icon whose colour can be customized.

1. Click the ellipsis symbol (`...`) on the section header to open the context menu.
2. A colour palette is displayed under `Icon colour`.
3. Click on any colour to apply it, or click the `More colours` option to pick a custom colour.

<img alt="Change section colour" src={__img8} placeholder="blur" />

## Reorder sections

You can drag and drop sections to rearrange their order in the sidebar.

1. Click and hold a section header.
2. Drag it to the desired position among other sections.
3. Release to drop it in place.

{/* ![Reorder sections](/img/v2/views/view-sections/reorder-sections.png) */}

## Delete a section

<Callout type="info">
  **This action cannot be undone.**
</Callout>

1. Click the ellipsis symbol (`...`) on the section header.
2. Click `Delete section`.
3. A confirmation dialog appears, informing you that views inside the section will be moved to the top level.
4. Click `Delete` to confirm.

<img alt="Delete section" src={__img9} placeholder="blur" />

<Callout type="info">
  Deleting a section does 

  **not**

   delete the views inside it. All views are automatically moved back to the top-level view list.
</Callout>

## Default section

When at least one section exists in a table, a virtual **Default** section is automatically displayed at the bottom of the section list. This section contains all views that have not been assigned to any section. The Default section cannot be renamed, deleted, or reordered, but it can be expanded and collapsed like any other section.

<img alt="Default section" src={__img10} placeholder="blur" />

***

## Notes

* View Sections are an organizational tool — they do not affect the data or configuration of the views inside them.
* Sections are scoped to individual tables. Each table has its own independent set of sections.
* All members of a workspace can see sections. Only members with **Editor** permissions or above can create, rename, reorder, or delete sections.
* When a section is collapsed, the currently active view remains visible in the sidebar regardless of which section it belongs to.


# Actions on workspace
URL: /docs/product-docs/workspaces/actions-on-workspace

Learn how to rename or delete a workspace in NocoDB.







## Rename workspace

1. Click on the workspace name in the sidebar to open workspace settings.
2. Open the **Settings** tab.
3. Under **Workspace Appearance**, update the **Name** field.
4. Click **Save** to apply changes.

<img alt="image" src={__img0} placeholder="blur" />

## Delete workspace

Permanently deletes the workspace and all its bases, tables, and data.

<Callout type="warning">
  **This action is irreversible.**

   This will permanently remove the workspace and all its contents.
</Callout>

<Callout type="info">
  Only the 

  **workspace owner**

   can delete a workspace.
</Callout>

1. Click on the workspace name in the sidebar to open workspace settings.
2. Open the **Settings** tab.
3. Under **Danger Zone**, click **Delete Workspace**.
4. Confirm by entering the workspace name in the dialog.

<img alt="image" src={__img1} placeholder="blur" />
<img alt="image" src={__img2} placeholder="blur" />

## Leave workspace

If you no longer need access to a workspace, you can leave it. You will not be able to access the workspace unless re-invited.

1. Click on the workspace name in the sidebar to open workspace settings.
2. Open the **Settings** tab.
3. Under **Danger Zone**, click **Leave Workspace**.

## Find workspace ID

Each workspace has a unique ID displayed on the **Settings** tab next to the workspace name. The ID is also visible in the URL when viewing a workspace.

Example:

```
https://app.nocodb.com/w7kjha1w/...
```

In this example, the workspace ID is `w7kjha1w`.


# Subscription & billing
URL: /docs/product-docs/workspaces/billing

Manage your NocoDB subscription, change plans, and access billing information easily.









NocoDB offers flexible pricing and simple subscription management through the billing dashboard.

## Billing dashboard

Access the billing dashboard by clicking the workspace name in the sidebar and selecting the **Billing** tab.

<img alt="dashboard" src={__img0} placeholder="blur" />

The dashboard shows:

* **Current Plan** and renewal date
* **Next invoice** amount and date
* **Billed users** count
* **Records** — usage against plan limit
* **Storage used** — attachments storage against plan limit
* **Webhook calls** — usage against monthly limit
* **API calls** — usage against monthly limit
* **Past Invoices** — date, plan, total, status, and download link

## Change your plan

1. Click the workspace name in the sidebar and open the **Billing** tab.
2. Click **Upgrade Workspace**.
3. Select the desired plan and follow the prompts to confirm.

<img alt="dashboard" src={__img1} placeholder="blur" />

<Callout type="info">
  Upgrades take effect immediately. Downgrades apply at the end of your billing cycle.
</Callout>

## Manage subscription

Click **Manage Subscription** on the billing dashboard to open the Stripe billing portal. From there you can:

* Update your card details
* View upcoming payments
* Add or change your payment method
* Cancel your subscription

<img alt="dashboard" src={__img2} placeholder="blur" />

## Download invoices

1. Scroll to the **Past Invoices** section on the billing dashboard.
2. Click **View invoice** next to the invoice you want.
3. A PDF copy will open in a new tab.

<img alt="dashboard" src={__img3} placeholder="blur" />

## Cancel plan

1. Click the workspace name in the sidebar and open the **Billing** tab.
2. Click **Manage Subscription** to open the Stripe billing portal.
3. Click **Cancel subscription** and confirm when prompted.

<Callout type="info">
  Your workspace remains on the current plan until the end of the billing period. After cancellation, it switches to the Free plan automatically.
</Callout>

Alternatively, you can downgrade directly:

1. From the **Billing** tab, click **Upgrade Workspace**.
2. Select **Choose Free**.
3. Click **Proceed** and follow the prompts.

For assistance, contact the [Support team](mailto:support@nocodb.com).


# Create workspace
URL: /docs/product-docs/workspaces/create-workspace

Learn how to create a workspace in NocoDB





When you sign up for NocoDB, a default workspace is automatically created for you. You can [rename this workspace](/docs/product-docs/workspaces/actions-on-workspace#rename-workspace) or create additional ones as needed.

<Callout type="info">
  The ability to create additional workspaces depends on your subscription plan. Refer to the 

  [pricing page](https://nocodb.com/pricing)

   for details.
</Callout>

## Create a workspace

1. Click **+ New Workspace** at the bottom of the sidebar.
2. Enter a name for your workspace.
3. Click **Create Workspace**.

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />

Once created, you become the **owner** of the workspace. You can then [create bases](/docs/product-docs/bases/create-base) and [invite collaborators](/docs/product-docs/workspaces/workspace-collaboration) to work with you.


# Workspaces
URL: /docs/product-docs/workspaces

Overview of workspaces in NocoDB.



Workspaces in NocoDB help organize and manage your data collaboratively. Each workspace can contain one or more bases, bringing together related tables, views, and other elements under a unified structure. You can control access by assigning roles to workspace members, enabling secure and efficient teamwork.

You can [invite team members](/docs/product-docs/workspaces/workspace-collaboration) to collaborate, [assign roles](/docs/product-docs/workspaces/workspace-collaboration#modify-roles-for-members-or-teams) to control access, and [rename](/docs/product-docs/workspaces/actions-on-workspace#rename-workspace) or [delete](/docs/product-docs/workspaces/actions-on-workspace#delete-workspace) workspaces as needed.

<Callout type="info">
  A default workspace is provided for all users. The ability to create additional workspaces depends on your subscription plan. Refer to the 

  [pricing page](https://nocodb.com/pricing)

   for details on plan-specific features.
</Callout>

## Workspace overview

The sidebar lists all workspaces you have access to. Click a workspace name to view its bases, members, integrations, billing, audits, and settings.

<img alt="image" src={__img0} placeholder="blur" />


# Workspace audit logs
URL: /docs/product-docs/workspaces/workspace-audit

Learn how to access and use audit logs to track workspace activity in NocoDB.







<Callout type="warning">
  This article covers 

  **workspace-level**

   audit logs. For 

  **record-level**

   logs (e.g., changes to individual records), refer to the 

  [record audit section](/docs/product-docs/records/expand-record#record-audit)

  .
</Callout>

<Callout type="info">
  Audit logs are available only in the 

  **Enterprise Edition**

  , both for self-hosted and cloud deployments.
</Callout>

The **Audit Logs** feature in NocoDB provides a comprehensive, time-stamped record of user activity across your workspace. It enables workspace owners to monitor key actions, ensuring transparency, traceability, and accountability.

## Accessing audit logs

Only **workspace owners** can access audit logs.

To view them:

1. Click on the workspace name in the sidebar to open workspace settings.
2. Select the **Audits** tab.

<img alt="image" src={__img0} placeholder="blur" />

***

## Audit log details

The audit list displays the following columns:

* **User**: Name and email of the user who performed the action
* **Timestamp**: Time of the event (e.g., “3h ago”)
* **Base**: Name and ID of the base involved
* **Event**: Type of action performed (e.g., *View Field Update*, *Table Create*)
* **IP Address**: IP of the user who performed the action

Click a log entry to view the **Audit Details** panel, which includes the performer, IP address, OS and browser info, base, event type, and the full event payload in JSON format.

<img alt="image" src={__img1} placeholder="blur" />

***

## Logged events

| Category                      | Events                                                                                                                       |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Data**                      | Insert, Update, Delete, Bulk Insert/Update/Delete/All Delete/All Update, Cascade Update, Link, Unlink, Import, Export        |
| **User & Auth**               | Sign Up, Sign In, Sign In Failed, Sign Out, Invite, Email Verify, Profile Update, Password Change/Reset/Forgot               |
| **Workspace**                 | Create, Update, Delete, Rename, Member Invite/Update/Remove, Team Invite/Update/Remove                                       |
| **Base**                      | Create, Update, Delete, Rename, Duplicate, Member Invite/Update/Resend, Team Invite/Update/Remove, Shared Base Create/Delete |
| **Table**                     | Create, Update, Delete, Rename, Duplicate                                                                                    |
| **Field**                     | Create, Update, Rename, Delete, Duplicate, Form Field Update, View Field Create/Update                                       |
| **View**                      | Create, Update, Delete, Rename, Duplicate, Filter Create/Update/Delete, Sort Create/Update/Delete                            |
| **Shared View**               | Create, Update, Delete                                                                                                       |
| **Webhook**                   | Create, Update, Delete, Filter Create/Update/Delete                                                                          |
| **Source**                    | Create, Update, Delete, Rename                                                                                               |
| **Integration**               | Create, Update, Delete                                                                                                       |
| **Dashboard**                 | Create, Update, Delete, Duplicate, Shared Dashboard Create/Update/Delete                                                     |
| **Widget**                    | Create, Update, Delete, Duplicate, Filter Create/Update/Delete                                                               |
| **Script**                    | Create, Update, Delete, Duplicate                                                                                            |
| **Workflow**                  | Create, Update, Delete, Duplicate                                                                                            |
| **Document (NocoDocs)**       | Create, Update, Delete, Comment Create/Update/Delete                                                                         |
| **Permission**                | Create, Update, Delete                                                                                                       |
| **RLS**                       | Policy Create, Update, Delete                                                                                                |
| **Record Template**           | Create, Update, Delete, Use                                                                                                  |
| **Date Dependency**           | Update, Delete                                                                                                               |
| **API Token**                 | Create, Update, Delete                                                                                                       |
| **Snapshot**                  | Create, Delete, Restore                                                                                                      |
| **Team**                      | Create, Update, Delete, Move, Member Add/Update/Remove                                                                       |
| **SCIM** *(Enterprise)*       | User Provision, Update, Deactivate, Reactivate, Delete                                                                       |
| **Airtable Import**           | Import, Import Error                                                                                                         |
| **Org Users** *(Self-hosted)* | Invite, Resend Invite                                                                                                        |

***

## Filtering logs

Use the filter bar at the top of the **Audits** tab to narrow results by:

* **User**
* **Base**
* **Event** type
* **Range** — All Time, Last 24H, Past Week, Past Month, Past Year, or Custom Date Range

<img alt="image" src={__img2} placeholder="blur" />


# Workspace collaboration
URL: /docs/product-docs/workspaces/workspace-collaboration

This article explains how to invite members or teams to your workspace, manage their roles, and remove them when needed.





















<Callout type="info">
  A comprehensive guide regarding roles and permissions can be accessed 

  [here](/docs/product-docs/roles-and-permissions)
</Callout>

<Callout type="info">
  Teams feature availability: 

  **Business**

   plan onwards in cloud and On-premise 

  **Enterprise**

   edition
</Callout>

## Invite Members to Workspace

1. Click on the workspace name in the sidebar to open workspace settings.
2. Open the **Members** tab.
3. Click **Add Members**.
4. Enter one or more email addresses.
5. Select a role from the dropdown — **Creator**, **Editor**, **Commenter**, or **Viewer**.
6. Click **Invite to Workspace**.

<Callout type="info">
  Any user can invite members to the workspace, but they can only assign a role that is at most equal to their own role.
</Callout>

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />
<img alt="image" src={__img2} placeholder="blur" />

## Invite Teams to Workspace ☁

Teams can be invited to a workspace for simplified collaboration, with a workspace-level role assigned to all team members.

1. Click on the workspace name in the sidebar to open workspace settings.
2. Open the **Members** tab.
3. Click **Add Teams**.
4. Select one or more teams from the dropdown.
5. Choose a role for the selected teams.
6. Click **Add Teams** to confirm.

<Callout type="info">
  Teams cannot be assigned the 

  **Owner**

   role. You can only assign roles that are at most equal to your own role.
</Callout>

<Callout type="info">
  When a team is invited, all users under that team inherit the assigned workspace-level role unless overridden by an explicit workspace role or base-level role.
</Callout>

<img alt="image" src={__img3} placeholder="blur" />
<img alt="image" src={__img4} placeholder="blur" />
<img alt="image" src={__img5} placeholder="blur" />

To learn more about creating and managing teams, refer to the [Teams documentation](/docs/product-docs/collaboration/teams).

## List Workspace Members and Teams

The **Members** tab displays all users and teams that have access to the workspace.

* Individual members appear with their name, email, role, and date joined.
* Teams are listed with their name, member count, and assigned role.

<Callout type="info">
  The members list is accessible to all workspace members.
</Callout>

<img alt="image" src={__img6} placeholder="blur" />

## Modify Roles for Members or Teams

Access permissions for both members and teams can be updated from the **Members** tab.

1. Click on the role dropdown next to the member or team.
2. Select a new role — **Creator**, **Editor**, **Commenter**, **Viewer**, **No Access**, or **Inherit** (inherits role from workspace-level team).

<Callout type="info">
  You can only assign roles that are at most equal to your own role in the workspace.
</Callout>

<img alt="image" src={__img7} placeholder="blur" />

## Role Precedence

When a user has multiple role assignments through both team and individual access, NocoDB resolves the final permission using a clear precedence order.

* Individual explicit role takes precedence over team-assigned role.
* Base-level roles override workspace-level roles.
* In case of multiple team roles, the **highest** permission applies.

<Callout type="info">
  This ensures users always retain the most permissive access assigned at their lowest configured level.
</Callout>

To learn more about effective role resolution, refer to the [Teams effective role resolution documentation](/docs/product-docs/collaboration/teams#effective-role-resolution).

## Remove Members or Teams from Workspace

You can remove both members and teams from the workspace using the actions menu.

1. Click on the vertical ellipsis `⋮` in the **Actions** column beside the member or team.
2. Select **Remove member** or **Remove team**.

<Callout type="info">
  Only the workspace 

  **owner**

   or 

  **creator**

   can remove members or teams from the workspace.
</Callout>

<img alt="image" src={__img8} placeholder="blur" />
<img alt="image" src={__img9} placeholder="blur" />

## Best Practice

* Invite all users to the workspace first with the **Inherit** role. This will allow them to access workspaces based on their team or base-level roles.
* Use teams for departments or functional groups to manage roles efficiently.
* Adjust team-level permissions instead of managing roles individually for large workspaces.

Learn more [here](/docs/product-docs/collaboration/teams#best-practices).

***


# SSO FAQs
URL: /docs/product-docs/account-settings/authentication/FAQs

Frequently asked questions about Single Sign-On (SSO) in NocoDB.

## Why do I see the error "SSO is not configured for this domain" when trying to sign in?

This error means that the email address you are using does not belong to a domain that has been verified and configured for SSO in your workspace settings. Only users with email addresses under your verified domain(s) can sign in via SSO. For example, if you've verified `example.com`, only users with emails like `user@example.com` will be allowed to sign in through the SSO page.

## How do I verify my domain for SSO?

**For NocoDB Cloud (Both Business and Enterprise Plans):**

1. Access the domain verification section:
   * **Business Plan**: Navigate to **Workspace Settings** > **Authentication** > **Domain Verification**
   * **Enterprise Plan**: Navigate to **Account Settings** > **Authentication** > **Domain Verification**
2. Enter your domain (e.g., `example.com`)
3. Copy the TXT record provided by NocoDB
4. Add the TXT record to your domain’s DNS via your registrar/DNS provider.
5. Wait for DNS propagation (this may take a few minutes to several hours)
6. Click **Verify** button in NocoDB to confirm domain ownership

**For NocoDB Self-hosted/On-prem:** Domain verification is not required. Configure SSO providers directly without DNS verification.

## Do I need to verify my domain when setting up SSO (e.g., Google OAuth)?

**For NocoDB Cloud (Both Business and Enterprise Plans):** Yes. In addition to configuring Google OAuth or other SSO providers, you must also verify your domain in the SSO settings. This is done by adding your domain and verifying it by adding the provided TXT record to your DNS. Only after domain verification will users from that domain be able to sign in via SSO.

**For NocoDB Self-hosted/On-prem:** Domain verification is not required. You can configure SSO providers without verifying your domain via DNS.

## When should I verify my domain?

Domain verification should be completed **before** configuring any SSO providers (Google OAuth, SAML, OIDC) for Cloud users (both Business and Enterprise plans). This ensures that:

1. Only users with email addresses from your verified domain can access the workspace
2. SSO providers are properly configured with domain restrictions
3. The authentication flow works correctly for your organization's users

If you try to configure SSO without domain verification, you may encounter errors or users from unverified domains may not be able to sign in.

## Why does domain verification fail even after adding the TXT record?

DNS propagation can take time to complete. After adding the TXT record to your domain's DNS settings:

* **Typical propagation time**: 5-30 minutes
* **Maximum propagation time**: Up to 24-48 hours (rare)
* **Check propagation**: Use online DNS lookup tools to verify the TXT record is visible
* **Retry verification**: If verification fails, wait a few minutes and try again

If verification fails after 24 hours, ensure the TXT record was added correctly. If issues persist, contact your DNS provider.

## Why do I get a redirection/callback URL or URI error when setting up SSO?

This error usually means that the Redirect URL (sometimes called Callback URL or Redirect URI) configured in your identity provider does not exactly match the one provided by NocoDB. Common reasons include:

* Typo or extra spaces in the URL/URI
* Using HTTP instead of HTTPS (or vice versa)
* Not including the full path as required
* Registering the wrong environment (e.g., using a local URL for production)
* Forgetting to update the Redirect URL after changing your NocoDB domain

**Solution:** Always copy and paste the exact Redirect URL/URI provided by NocoDB into your identity provider's configuration. Any mismatch will result in an error during authentication.

## How do API tokens work with SSO-enabled workspaces?

When a workspace is configured to enforce Single Sign-On (SSO), API access is restricted to tokens generated through an authenticated SSO session. Please find additional details here: [API Tokens with SSO](/docs/product-docs/account-settings/api-tokens#api-token-access-with-sso-enabled-workspaces).


# Google OAuth
URL: /docs/product-docs/account-settings/authentication/google-oauth

Learn about different methods available for authentication with NocoDB.

NocoDB offers a functionality that allows users to connect with Google OAuth 2.0, enabling them to log into their NocoDB accounts using their Google authentication credentials. This article provides a step-by-step guide to integrating Google OAuth 2.0 with NocoDB.

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
   

  **Domain Verification Required (Cloud Plans)**

  \


  \


  Before configuring Google OAuth, your domain must be verified in NocoDB (applies to both Business and Enterprise plans).
  Only users with email addresses from verified domains can sign in via SSO.
  See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details. 
</Callout>

## Accessing Google OAuth Settings

Accessing **NocoDB Google OAuth** section depends on your plan:

* **Cloud version**: Go to `Workspace Settings` > `Authentication` > `Google OAuth`
* **On-prem version**: Go to `Account Settings` > `Authentication` > `Google OAuth`

## Steps to Configure Google OAuth

1. **Verify your domain** (Cloud plans only) :
   * See [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification).
2. Copy `Redirect URL` from [NocoDB Google OAuth](#accessing-google-oauth-settings) section
3. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project.
4. **Configure the OAuth consent screen**
   * Navigate to **APIs & Services** > **OAuth consent screen**
   * Provide app details and select user access type
   * Add authorized domains where NocoDB is hosted
   * Click **Create**
5. **Generate OAuth credentials**
   * Go to **APIs & Services** > **Credentials**
   * Click **Create Credentials** > **OAuth Client ID**
   * Select **Web application** as the application type
6. **Set up application details**
   * **Authorized JavaScript origins**: Enter your app domain (e.g., `https://app.nocodb.com`)
   * **Authorized Redirect URIs**: Paste the Redirect URL copied from step 2
7. **Create credentials and copy values**
   * Click **Create**
   * Copy the **Client ID** and **Client Secret** from the generated OAuth 2.0 Client ID
8. **Add credentials to NocoDB**
   * Paste the **Client ID** and **Client Secret** into the respective fields in [NocoDB Google OAuth](#accessing-google-oauth-settings) section

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>

***


# Authentication & SSO
URL: /docs/product-docs/account-settings/authentication

Learn about different methods available for authentication with NocoDB.







This section provides an overview about different mechanisms available for authentication in NocoDB.

# Email and password based

This is the default form based authentication mechanism available in NocoDB. Users can sign up using email and password and then login using the same credentials.

# Single Sign On (SSO)

<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

SSO is a session and user authentication service that permits a user to use one set of login credentials to access multiple applications. The service authenticates the end user for all the applications the user has been given rights to and eliminates further prompts when the user switches applications during the same session.

SSO functionality is achieved by establishing a connection with an identity provider (IdP), which serves as a repository for managing users digital identities within the digital or cloud-based ecosystem. Through the use of protocols like the Security Assertion Markup Language (SAML 2.0), such as in the case of NocoDB, SSO facilitates the secure exchange of authentication data between the identity provider and the service providers.

<Callout type="warning">
  Once SSO is enabled for a workspace, API access is restricted to tokens generated after signing in via the configured identity provider (IdP). Tokens created before SSO was enabled will no longer work for that workspace and must be regenerated through an SSO-authenticated session. 

  [Know more](/docs/product-docs/account-settings/api-tokens#api-token-access-with-sso-enabled-workspaces)

  . 
</Callout>

### Google OAuth

Google OAuth, short for Open Authorization, is a widely used and standardized protocol that facilitates secure authentication and authorization processes, particularly in the context of web and mobile applications. Developed by Google, OAuth enables users to grant third-party applications limited access to their resources without exposing their credentials. This authorization framework is based on token-based authentication, where users can log in using their Google credentials, and developers can obtain an access token to interact with Google APIs on the user's behalf.

Please follow the details in the article to integrate with [Google OAuth](/docs/product-docs/account-settings/authentication/google-oauth)

### Security Assertion Markup Language (SAML)

The Security Assertion Markup Language (SAML) stands as a critical protocol in the realm of secure authentication and authorization processes. Developed to enable Single Sign-On (SSO) functionality, SAML facilitates the exchange of authentication and authorization data between an identity provider (IdP) and a service provider (SP). This XML-based protocol ensures the secure transfer of user identity information, allowing individuals to access multiple applications and services with a single set of credentials. SAML operates on a trust model, wherein the identity provider asserts the user's identity to the service provider, which, in turn, grants or denies access based on the provided assertions.

Please follow the details in the article below to integrate with various popular SAML providers.

1. [Okta](/docs/product-docs/account-settings/authentication/saml-sso/okta)
2. [Auth0](/docs/product-docs/account-settings/authentication/saml-sso/auth0)
3. [Ping Identity](/docs/product-docs/account-settings/authentication/saml-sso/ping-identity)
4. [Active Directory](/docs/product-docs/account-settings/authentication/saml-sso/azure-ad)
5. [Keycloak](/docs/product-docs/account-settings/authentication/saml-sso/keycloak)

### OpenID Connect (OIDC)

The OpenID Connect (OIDC) protocol is a modern authentication layer built on top of the OAuth 2.0 framework, designed to address user authentication and authorization challenges in web and mobile applications. OIDC provides a standardized and secure way for applications to verify the identity of end-users. Leveraging JSON Web Tokens (JWTs), OIDC enables the exchange of user identity information between the identity provider (IdP) and the Service provider, typically a web application.

Please follow the details in the article below to integrate with various popular OIDC providers.

1. [Okta](/docs/product-docs/account-settings/authentication/oidc-sso/okta)
2. [Auth0](/docs/product-docs/account-settings/authentication/oidc-sso/auth0)
3. [Ping Identity](/docs/product-docs/account-settings/authentication/oidc-sso/ping-identity)
4. [Active Directory](/docs/product-docs/account-settings/authentication/oidc-sso/azure-ad)

## Accessing the SSO Configuration Menu

The location of the **SSO configuration menu** varies depending on your plan.

* If you're on the **Business plan**, you can access SSO settings from the **Workspace Settings**.
* For **Enterprise plan** users, the SSO menu is available under the **Admin Panel**.

Please follow the steps relevant to your plan to locate and configure SSO.

### Business Plan

To access the SSO configuration menu in the Business plan, navigate to the **Workspace Settings**. Here, you can manage your SSO settings, including adding new identity providers and configuring existing ones.

<img alt="SSO Configuration" src={__img0} placeholder="blur" />

Alternatively, you can directly access the SSO configuration screen using the URL:
`https://app.nocodb.com/#/workspaceID/settings?tab=sso`

### Enterprise Plan

For users on the Enterprise plan, the SSO configuration menu is located in the **Account Settings**. This allows for more advanced SSO configurations and management options across the entire organization.

1. Click on the user icon in the bottom left corner of the NocoDB interface.
2. Select **Account Settings** from the menu.
3. Navigate to the **Single Sign-on (SSO)** tab.

<img alt="SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SSO Configuration" src={__img2} placeholder="blur" />

Alternatively, you can directly access the SSO configuration screen using the URL:
`https://your-domain/#/account/authentication`

### Domain Verification

For **NocoDB Cloud** users (both Business and Enterprise plans), domain verification is required before configuring SSO providers. This ensures that only users with email addresses from your verified domain can access the workspace through SSO.

**Domain Verification Process:**

1. Access the domain verification section:

* **Business Plan**: Navigate to **Workspace Settings** > **Authentication** > **Domain Verification**
* **Enterprise Plan**: Navigate to **Account Settings** > **Authentication** > **Domain Verification**

2. Enter your domain (e.g., `example.com`)
3. Copy the TXT record provided by NocoDB
4. Add the TXT record to your domain’s DNS via your registrar/DNS provider.
5. Wait for DNS propagation (this may take a few minutes to several hours)
6. Click **Verify** button in NocoDB to confirm domain ownership

Once verified, only users with email addresses under your verified domain(s) will be able to sign in via SSO. For example, if you've verified `example.com`, only users with emails like `user@example.com` will be allowed to sign in through the SSO page.

<Callout type="info">
  **On-premise deployments**

   do not require domain verification. Configure SSO providers directly without DNS verification.
</Callout>

## SCIM Provisioning

<Callout type="info">
  SCIM provisioning is available on 

  **Enterprise**

   plans.
</Callout>

SCIM (System for Cross-domain Identity Management) v2.0 enables automatic user and group provisioning from your identity provider to NocoDB. When configured alongside SSO, SCIM automates the full identity lifecycle — from onboarding (creating organization members) to offboarding (deactivating access) — without manual intervention.

SCIM is configured from the **Admin Panel** by the Org Admin. NocoDB supports SCIM provisioning with Okta and Azure AD (Entra ID). For a detailed overview of SCIM features and configuration, see the [SCIM Provisioning guide](/docs/product-docs/account-settings/authentication/scim).

***


# SCIM
URL: /docs/product-docs/account-settings/authentication/scim

Learn how to configure SCIM v2.0 for automatic user and group provisioning in NocoDB.











<Callout type="info">
  SCIM provisioning is available on 

  **Enterprise**

   plans. Please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)

   for access.
</Callout>

## Overview

SCIM (System for Cross-domain Identity Management) is an open standard protocol (v2.0) that automates the exchange of user and group identity information between your identity provider (IdP) and NocoDB. Instead of manually adding and removing users from your organization, SCIM lets your IdP handle it automatically.

With SCIM provisioning enabled, your identity provider can:

* **Create users** — automatically add users to your NocoDB organization when they're assigned in the IdP
* **Update users** — sync profile changes (display name, email, etc.) from the IdP to NocoDB
* **Deactivate users** — soft-delete organization members when they're unassigned or deactivated in the IdP
* **Manage groups** — create, update, and delete org-level teams in NocoDB that mirror your IdP group structure

<Callout type="note">
  SCIM provisioning handles 

  **identity lifecycle management**

   (who has access). It is complementary to SSO (SAML/OIDC), which handles 

  **authentication**

   (how users sign in). For best results, configure both SSO and SCIM with the same identity provider.
</Callout>

## Enabling SCIM in NocoDB

### Prerequisites

* An **Enterprise** NocoDB organization (cloud or on-premise)
* **Org Admin** access in NocoDB
* Admin access to your identity provider (Okta, Azure AD / Entra ID, etc.)
* SSO configured with the same IdP (recommended, not required)

### Step 1: Navigate to SCIM settings

1. Open the **Admin Panel** from the user menu in the bottom-left corner of the NocoDB interface
2. Select **SCIM** from the sidebar menu

<img alt="Navigate to SCIM settings" src={__img0} placeholder="blur" />

### Step 2: Enable SCIM provisioning

Click the **Configure** button in the SCIM Provisioning section. NocoDB will generate the SCIM endpoint URL and a provisioning token, and automatically enable provisioning.

### Step 3: Copy the SCIM endpoint and token

Once SCIM is configured, you'll see the following details:

* **SCIM Endpoint URL** — the base URL for all SCIM API calls (e.g., `https://app.nocodb.com/api/v3/meta/orgs/{orgId}/scim/v2`)
* **Bearer Token** — a bearer token used to authenticate SCIM requests

<img alt="SCIM configured with token visible" src={__img1} placeholder="blur" />

<Callout type="warning">
  The bearer token is shown 

  **only once**

   when first generated. Copy it immediately and store it securely. If you lose it, you can regenerate it, but the previous token will be invalidated.
</Callout>

### Step 4: Configure your identity provider

Use the SCIM Endpoint URL and Provisioning Token to configure SCIM in your IdP. NocoDB supports SCIM provisioning with Okta and Azure AD (Entra ID). Refer to your identity provider's documentation for SCIM application configuration steps.

### Step 5: Assign users and groups

In your IdP, assign users and/or groups to the NocoDB SCIM application. The IdP will then push these assignments to NocoDB via the SCIM API.

## How it works

### User provisioning

When a user is assigned to the NocoDB application in your IdP, the IdP sends a SCIM `POST /Users` request. NocoDB creates an organization member with the configured [default role](#default-role-for-new-users) (Org-Viewer by default). Once provisioned, org members can be:

* Invited into **org-level teams**
* Assigned roles at the **workspace** or **base** level
* Added to **workspace teams**

Org Admins can change the org role from within NocoDB at any time.

If a user is **unassigned** or **deactivated** in the IdP, NocoDB soft-deletes the organization member. The user's data and contributions are preserved, but they lose access to the organization and all its workspaces.

If a previously deactivated user is **re-assigned** in the IdP, NocoDB reactivates their organization membership with the current [default role](#default-role-for-new-users) (not their previous role). Any workspace, base, or team memberships the user held before deactivation are **not** automatically restored — the user must be re-invited to each workspace and base individually to regain access.

### Group provisioning

SCIM groups map to **org-level Teams** in NocoDB. When a group is pushed from the IdP, NocoDB creates a corresponding organization team with a `SCIM` badge and "Identity Provider" shown as the creator. Members of the IdP group are automatically added to the NocoDB team.

Changes to group membership in the IdP (adding or removing members) are synced to NocoDB in real time via SCIM PATCH operations.

<img alt="SCIM-provisioned teams" src={__img2} placeholder="blur" />

### SCIM-managed vs. manually-created users

Users provisioned through SCIM are marked as **SCIM-managed** with a blue `SCIM` badge in the User Management list. Key differences:

* SCIM-managed users' lifecycle (activation/deactivation) is controlled by the IdP
* Org roles can still be changed by the Org Admin within NocoDB
* Manually created users are unaffected by SCIM operations
* SCIM-managed users cannot be removed directly from NocoDB — removal must be done from your identity provider

<img alt="SCIM managed users in members list" src={__img3} placeholder="blur" />
<img alt="SCIM managed user actions" src={__img4} placeholder="blur" />

## Managing SCIM

### Toggling provisioning

You can **pause** SCIM provisioning without deleting the configuration by toggling the SCIM switch in the Admin Panel > SCIM settings. When paused, NocoDB will reject incoming SCIM requests until provisioning is re-enabled.

### Default role for new users

The default role determines the org-level role assigned to SCIM-provisioned users. You can configure this from the SCIM settings page using the **Default Role for New Users** dropdown. Available options:

| Role            | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| **Org-Viewer**  | Can access workspaces and bases they are invited to; cannot create new workspaces (default) |
| **Org-Creator** | Same as Org-Viewer, plus can create new workspaces within the organization                  |

### Regenerating the token

If the provisioning token is compromised or lost:

1. Go to **Admin Panel** > **SCIM**
2. Click the **Regenerate** button next to the provisioning token
3. Copy the new token and update it in your IdP configuration

<Callout type="warning">
  Regenerating the token immediately invalidates the previous token. Your IdP will fail to sync until you update it with the new token.
</Callout>

### Disabling SCIM

To completely remove SCIM provisioning:

1. Go to **Admin Panel** > **SCIM**
2. Click **Remove** in the danger zone section
3. Confirm the deletion

<Callout type="note">
  Disabling SCIM stops all provisioning but does 

  **not**

   remove SCIM-managed users from the organization. They remain as regular organization members.
</Callout>


# Actions on script
URL: /docs/product-docs/automation/scripts/actions-on-script

Learn how to rename, duplicate and delete a script in NocoDB.

### Rename Script

To duplicate a Script

* Use `...` actions button to the right of the script name in the Scripts list
* Select `Renamne`

### Duplicate Script

To duplicate a Script

* Use `...` actions button to the right of the script name in the Scripts list
* Select `Duplicate`

A copy of the script will be created with a suffix ` - Copy`

### Delete Script

To delete a Script

* Use `...` actions button to the right of the script name in the Scripts list
* Select `Delete`

### Print/Export Script Logs to PDF

Export your script execution results to PDF.

**To export:**

* Run your script to generate output
* Click the **Print** button in the toolbar
* Select page size (Letter, Legal, or A4) and orientation (Portrait or Landscape)
* Click **Generate PDF**
* Save as PDF or print from the browser dialog

**Note:** The Print button is disabled until you run the script at least once.

## Additional Resources

The following resources can help you get started with NocoDB scripts:

* [Script Documentation](/docs/scripts)
* [Script Examples](/docs/scripts/examples/find-and-replace)
* [Script API Reference](/docs/scripts/api-reference/base)


# Create script
URL: /docs/product-docs/automation/scripts/create-script

Learn how to create a script in NocoDB.





To create your first script, you can either

* From the sidebar, click on the `Create New` button and select `New Script`
* From the base homepage, select `All Scripts` tab and click on the `+ Create Empty Script` button

<img alt="Create Script" src={__img0} placeholder="blur" />

## Layout

1. All scripts are listed in the `Automations` section accessible from the left sidebar. You can also view the scripts in the `All Scripts` tab on the base homepage.
2. Central area is the script **editor** where you can write and run your JavaScript code.
3. The right sidebar is the **execution area** where you can see the output of your script, view logs, and manage script settings.
4. Use the `settings` icon in the top-right corner to configure script settings. Use the `Run` button to execute your script. Use the `Print` button to export script output to PDF.
5. Access quick links to documentation, support, and settings from the bottom-right corner.

<img alt="All Scripts" src={__img1} placeholder="blur" />

## Additional Resources

The following resources can help you get started with NocoDB scripts:

* [Script Documentation](/docs/scripts)
* [Script Examples](/docs/scripts/examples/find-and-replace)
* [Script API Reference](/docs/scripts/api-reference/base)


# Scripts
URL: /docs/product-docs/automation/scripts

Overview of the scripts feature in NocoDB

<Callout type="note">
  The Scripts feature is currently in beta release & is available on NocoDB cloud and on-premise licensed deployments.
</Callout>

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

## Additional Resources

The following resources can help you get started with NocoDB scripts:

* [Script Documentation](/docs/scripts)
* [Script Examples](/docs/scripts/examples/find-and-replace)
* [Script API Reference](/docs/scripts/api-reference/base)


# Actions on webhook
URL: /docs/product-docs/automation/webhook/actions-on-webhook

Learn how to enable/disable, duplicate and delete webhooks.









### Enable/disable Webhook

To disable a Webhook

* Open `Webhook` tab to find list of webhooks created
* Toggle `Activate` button to enable/disable

<img alt="Webhook List" src={__img0} placeholder="blur" />

### Edit Webhook

To edit a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on webhook to be edited
* This will open up the webhook configuration page, which is similar to the page used for [creating webhook](/docs/product-docs/automation/webhook/create-webhook). Reconfigure the webhook as required
* Click on `Save` button to save the changes

### Duplicate Webhook

To duplicate a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on `...` actions button associated with the webhook to be duplicate
* Select `Duplicate`

<img alt="Webhook context menu" src={__img1} placeholder="blur" />

A copy of the webhook will be created (disabled by default) with a suffix `copy`

### Delete Webhook

To delete a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on `...` actions button associated with the webhook to be deleted
* Select `Delete`

<img alt="Webhook context menu" src={__img2} placeholder="blur" />

### Webhook Logs ☁

<Callout type="note">
  This feature is only available in the paid plans, in both cloud & self-hosted.
</Callout>

Webhook logs in NocoDB provide a detailed record of webhook execution attempts, including request payloads, response status, and error messages (if any). These logs help in monitoring webhook activity, debugging failures, and verifying successful deliveries. Logs can be accessed from the webhook configuration panel for each webhook.

<img alt="webhook v3 logs" src={__img3} placeholder="blur" />


# Create webhook
URL: /docs/product-docs/automation/webhook/create-webhook

Learn how to create a webhook in NocoDB.













import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

### Accessing webhook page

1. Click on table for which webhook needs to be configured on the left sidebar
2. Open `Details` tab in topbar,
3. Click on `Webhooks` tab
4. Click `Add New Webhook`

<img alt="Accessing webhook" src={__img0} placeholder="blur" />

### Configuring webhook

<img alt="Configuring webhook" src={__img1} placeholder="blur" />

1. **Name the webhook** - Give a clear & descriptive name.

2. Select the **Trigger Source** type :\
   <Callout type="info">Trigger Source type **View** and **Field** are only available in the cloud & self-hosted enterprise plans.</Callout>

   * **Record** - Triggers when a record is inserted, updated, or deleted, or for all actions if “Send me everything” is selected.
   * **View** - Triggers when a view is created, updated, or deleted, or for all actions if “Send me everything” is selected.
   * **Field** - Triggers when a field is created, updated, or deleted, or for all actions if “Send me everything” is selected.
   * **Manual Trigger / Button Trigger**  - Trigger runs when a user manually clicks a webhook configured button.

3. Select **Trigger Event** type : Refer table [here](#trigger-source-and-event) for available events for each source

4. \[Optional] **Trigger based on condition** : details [here](#webhook-with-conditions)
   <Callout type="note">Conditions are only applicable for Record trigger source events</Callout>
   * Specify the condition for which webhook should be triggered
   * You can select multiple conditions
   * If no condition is selected, webhook will be triggered for all records

5. \[Optional] **Trigger for updates in specific fields** : details [here](#webhook-on-field-changes-)
   <Callout type="note">This is only applicable for Record `After Update` event.</Callout>
   * Select the fields for which webhook should be triggered.
   * If no field is selected, any field update will trigger webhook

6. \[Optional] **Trigger only when specific form submitted**: details [here](#webhook-on-specific-form-submission-)
   <Callout type="note">This is only applicable for Record `After Insert` event.</Callout>
   * Select the form for which webhook should be triggered.

7. **Webhook Action** : Select the action to be performed when webhook is triggered. Action can be one of the following:
   * **HTTP Request** : Send an HTTP request to a specified URL. You can configure the HTTP method, headers, parameters, and body of the request.
     * **Method & URL** : Specify the endpoint that the webhook will call when triggered. You can choose from the following HTTP methods: GET, POST, PUT, DELETE, PATCH, and HEAD.
     * **Headers & Parameters** : Configure Request headers & parameters
     * **Body** : Configure request body. You can use [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions) to access and manipulate the data easily. For example, `{{ json event }}` will give you the complete event data (default behaviour if body not configured).

   * **Run Script** : Run a custom script using NocoDB's built-in scripting engine. You can write JavaScript code to perform various actions when the webhook is triggered.
     * **Script** : Select the script to be executed when the webhook is triggered. You can create and manage scripts in the `Scripts` tab in the left sidebar.

8. \[Optional] Click **Test** webhook button to verify if parameter are configured appropriately (with sample payload)

9. Click **Create Webhook** button to complete webhook creation

### Trigger Source and Event

Webhooks in NocoDB can be configured based on the source of the trigger and the type of event. The table below outlines the available combinations:

<Callout type="info">
  Trigger Source type 

  **View**

   and 

  **Field**

   are only available in the cloud & self-hosted enterprise plans.
</Callout>

| **Trigger Source** | **Trigger Event**  | **Description**                                            |
| ------------------ | ------------------ | ---------------------------------------------------------- |
| Record             | Send Me Everything | Triggers on any record insert, update, or delete operation |
|                    | After Insert       | Triggers after one or more records are inserted            |
|                    | After Update       | Triggers after one or more records are updated             |
|                    | After Delete       | Triggers after one or more records are deleted             |
| View               | Send Me Everything | Triggers on any view create, update, or delete operation   |
|                    | After Create       | Triggers after a view is created                           |
|                    | After Update       | Triggers after a view is updated                           |
|                    | After Delete       | Triggers after a view is deleted                           |
| Field              | Send Me Everything | Triggers on any field create, update, or delete operation  |
|                    | After Create       | Triggers after a field is created                          |
|                    | After Update       | Triggers after a field is updated                          |
|                    | After Delete       | Triggers after a field is deleted                          |
| Button Trigger     | —                  | Triggers when a button field is clicked                    |

For more details on using **Button Trigger** webhooks with the **Button** field, see the [Button field documentation](/docs/product-docs/fields/field-types/custom-types/button).

***

### Run Script action ☁

<Callout type="note">
  This feature is only available in the paid plans, in both cloud & self-hosted.
</Callout>

The **Run Script** action enables you to execute custom JavaScript code directly within NocoDB whenever a webhook is triggered. It is ideal for use cases where data needs to be processed or transformed internally. When triggered, the associated script runs within NocoDB’s secure scripting engine and automatically receives an `event` object (see example below) containing the webhook context, such as record creation, update, or deletion details.

```javascript
/*
  Update record on trigger; This script updates the 'Department' and 'Employment Status' fields when a new record is inserted. Note the usage of `cursor.row` to access the record that triggered the webhook.
*/

const record = cursor.row;

// Exit if no record found (safeguard)
if(!record) {
  return
}

// Get the table
const table1 = base.getTable("Employee")

// Update the record
await table1.updateRecordAsync(record.id, {
  "Department": "New Hire",
  "Employment Status": "Active"
})
```

Refer to the [Scripts documentation](/docs/scripts#getting-started) for detailed guide on creating and managing scripts. Note that, scripts that seek explicit user input (such as `input.textAsync()`) cannot be used in webhook context, since webhooks run in the background without user interaction.

### Webhook with conditions

Webhooks (record trigger related) in NocoDB can be configured to trigger only when specific conditions are met. For example, you may choose to trigger a webhook only when the `Status` field is set to `Complete`. You can define multiple conditions using logical operators like `AND` or `OR`—such as triggering the webhook on record update only when `Status` is `Complete` **and** `Priority` is `High`.

<img alt="Webhook with conditions" src={__img2} placeholder="blur" />

A webhook will only be triggered if the condition transitions from **not met** to **met** during a record event. For instance (for above example), if the original record has `Status = Complete` and `Priority = Low`, and you update it to `Priority = High`, the webhook will trigger—since the condition was not met before but is met after the update. However, if a record already satisfies the condition (`Status = Complete` and `Priority = High`) and you update unrelated fields, the webhook will not be triggered.

**In short**, a webhook is triggered only when the condition changes from **false** (old record) to **true** (new record).

<Callout type="note">
  Conditions are not applicable for Manual Trigger webhook.
</Callout>

### Webhook on field changes ☁

<Callout type="note">
  This feature is only available in the paid plans, in both cloud & self-hosted.
</Callout>

For **After Update** event, you can configure webhook to trigger only when **certain fields are updated**. For example, trigger webhook only when `Status` is updated. You can also configure multiple fields.

<img alt="Webhook on field changes" src={__img3} placeholder="blur" />

### Webhook on specific form submission ☁

<Callout type="note">
  This feature is only available in the paid plans, in both cloud & self-hosted.
</Callout>

For **After Insert** event, you can configure webhook to trigger only when a **specific form is submitted**. For example, if you have multiple forms for a table, you can choose to trigger webhook only when `Form A` is submitted.

<img alt="Webhook on specific form submission" src={__img4} placeholder="blur" />

### Webhook with custom payload

Custom payload lets you fully control the body a webhook sends when an event is triggered. You can send the entire event object, a specific field, a compact row summary, or transform rows into arrays/objects that downstream services expect.

NocoDB exposes the current event as `event` inside custom payload. These are processed with [Handlebars-like expressions](https://handlebarsjs.com/guide/#simple-expressions) and a built-in `json` helper ([examples below](#examples)).

#### Example event object

This is the sample event generated by NocoDB after a record is inserted.

```json
{
  "type": "records.after.insert",
  "id": "0698517a-d83a-4e72-bf7a-75f46b704ad1",
  "version": "v3",
  "data": {
    "table_id": "m969t01blwprpef",
    "table_name": "Table-2",
    "view_id": "vwib3bvfxdqgymun",
    "view_name": "Table-2",
    "rows": [
      {
        "Id": 1,
        "Tags": "Sample Text",
        "CreatedAt": "2024-04-11T10:40:20.998Z",
        "UpdatedAt": "2024-04-11T10:40:20.998Z"
      }
    ]
  }
}
```

In custom payload, you will typically access paths such as `event.data.table_name` or `event.data.rows.[0].Tags`.

#### Adding a custom payload

To add a custom payload, open your webhook in NocoDB's UI and follow these steps:

1. Click on the **Body** tab
2. Enter your template using Handlebars expressions and the `json` helper.
3. Create/update Webhook or use the **Test Webhook** action to verify rendering.

<img alt="Webhook custom payload" src={__img5} placeholder="blur" />

<Callout type="info">
  Some applications require specific headers to process webhook payloads correctly. For example, if you're sending JSON data, ensure you include the appropriate 

  `Content-Type`

   header in your webhook configuration (commonly 

  `application/json`

  ).
</Callout>

The `json` helper is used to safely serialize values into valid JSON, whether they’re strings, objects, or arrays. It ensures proper quoting and escaping, preventing common errors with quotes, newlines, or special characters. For example, `{{ json event }}` outputs the full event object, while `{{ json event.data.rows.[0].Title }}` safely inserts a single field as a JSON string. This makes it the most reliable way to embed dynamic values in webhook payloads.

Handlebars expressions allow you to dynamically access and manipulate data within templates, similar to how the json helper works for serialization. You can reference fields using dot or bracket notation, iterate over arrays with `{{#each ...}}`, and conditionally include content with `{{#if ...}}`. Learn more about using Handlebars expressions in [Handlebars documentation](https://handlebarsjs.com/guide/#simple-expressions).

#### Examples

Here are some common payload templates you can use as a starting point:

1. **Full event object:**
   Sends the complete event data as JSON

```text
{
  "event": {{ json event }}
}
```

2. **Single field value:**
   Sends just the `Title` field of the first row

```text
{
  "content": {{ json event.data.rows.[0].Title }}
}
```

3. **Compact row summary:**
   Sends all fields of the first row as a JSON object

```text
{
  "row": {{ json event.data.rows.[0] }}
}
```

4. **All rows as array:**
   Sends all rows in the event as a JSON array

```text
{
  "rows": {{ json event.data.rows }}
}
```

5. **Custom object with metadata:**
   Sends an object with table name, row count, and all rows

```text
{
  "table": {{ json event.data.table_name }},
  "count": {{ json event.data.rows.length }},
  "rows": {{ json event.data.rows }}
}
```

6. **Custom text with field value:**
   Sends a simple message including the `Title` field

```text
{
  "message": "New record created with title: {{ event.data.rows.[0].Title }}"
}
```

7. **Handlebar logic example:**
   Sends different payloads based on whether rows exist

```text
{{#if event.data.rows.length}}
{
  "hasRows": true,
  "rows": {{ json event.data.rows }}
}
{{else}}
{
  "hasRows": false
}
{{/if}}
```

8. **Multiple rows with formatting:**
   Sends all rows with only `Id` and `Title`, formatted as a JSON array

```text
{
  "records": [
    {{#each event.data.rows}}
      {{#if @first}}{{else}},{{/if}}
      {
        "Id": {{ Id }},
        "Title": {{ json Title }}
      }
    {{/each}}
  ]
}
```

***

### Webhook response sample

#### Record trigger

<Tabs items={['After Insert', 'After Update', 'After Delete']}>
  <Tab value="After Insert">
    ```bash
    {
      "type": "records.after.insert",
      "id": "c245c528-8759-4e10-b7d5-e2626dd7c321",
      "version": "v3",
      "data": {
        "table_id": "mbmppjnstflsqq1",
        "table_name": "Features",
        "rows": [
          {
            "Id": 4,
            "CreatedAt": "2025-05-07 17:18:37+00:00",
            "UpdatedAt": null,
            "Title": "Task-2",
            "Status": "Ongoing",
            "Priority": "Low"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Update">
    ```bash
    {
      "type": "records.after.update",
      "id": "f5e6a827-fb37-4a04-8cd9-be7831f9d897",
      "version": "v3",
      "data": {
        "table_id": "mbmppjnstflsqq1",
        "table_name": "Features",
        "previous_rows": [
          {
            "Id": 3,
            "CreatedAt": "2025-05-07 17:18:33+00:00",
            "UpdatedAt": null,
            "Title": null,
            "Status": null,
            "Priority": null
          }
        ],
        "rows": [
          {
            "Id": 3,
            "CreatedAt": "2025-05-07 17:18:33+00:00",
            "UpdatedAt": "2025-05-07 17:18:37+00:00",
            "Title": "Task-1",
            "Status": "Complete",
            "Priority": "High"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Delete">
    ```bash
    {
      "type": "records.after.delete",
      "id": "4cad2ff8-9ee6-4889-8c85-9969361a1df0",
      "version": "v3",
      "data": {
        "table_id": "mbmppjnstflsqq1",
        "table_name": "Features",
        "rows": [
          {
            "Title": "Task-2",
            "Id": 2,
            "Status": "Ongoing",
            "Priority": "Low"
          },
          {
            "Title": "Task-1",
            "Id": 3,
            "Status": "Complete",
            "Priority": "High"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

#### View trigger

<Tabs items={['After Create', 'After Update', 'After Delete']}>
  <Tab value="After Create">
    ```bash
    {
      "type": "view.after.create",
      "id": "2f62c921-4dcc-4f37-8e3d-fd3612aaf269",
      "version": "v3",
      "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "views": [
          {
            "id": "vw45okb4letthls6",
            "table_id": "ma334932sjnwp3e",
            "title": "Grid-1",
            "type": "grid",
            "lock_type": "collaborative",
            "created_at": "2025-09-22 06:51:13+00:00",
            "updated_at": "2025-09-22 06:51:13+00:00",
            "description": "Grid view sample description",
            "created_by": "usq6o3vavwf0twzr",
            "fields": [
              {
                  "field_id": "cc5i4wkzktyqedh",
                  "show": true
              },
              {
                  "field_id": "ct41ytilwlxf7u3",
                  "show": true
              },
              {
                  "field_id": "cmbcaa8aoxtpdr9",
                  "show": true
              }
            ],
            "options": {
              "row_height": "short"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Update">
    ```bash
    {
      "type": "view.after.update",
      "id": "08faf0d1-6c02-4f66-8851-2e6405c6c76b",
      "version": "v3",
      "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "previous_views": [
          {
            "id": "vw45okb4letthls6",
            "table_id": "ma334932sjnwp3e",
            "title": "Grid-1",
            "type": "grid",
            "lock_type": "collaborative",
            "created_at": "2025-09-22 06:51:13+00:00",
            "updated_at": "2025-09-22 06:51:13+00:00",
            "description": "",
            "created_by": "usq6o3vavwf0twzr",
            "fields": [
              {
                "field_id": "cc5i4wkzktyqedh",
                "show": true
              },
              {
                "field_id": "ct41ytilwlxf7u3",
                "show": true
              }
            ],
            "options": {
              "row_height": "short"
            }
          }
        ],
        "views": [
          {
            "id": "vw45okb4letthls6",
            "table_id": "ma334932sjnwp3e",
            "title": "Grid-1 Renamed",
            "type": "grid",
            "lock_type": "collaborative",
            "created_at": "2025-09-22 06:51:13+00:00",
            "updated_at": "2025-09-22 07:08:29+00:00",
            "description": "",
            "created_by": "usq6o3vavwf0twzr",
            "fields": [
              {
                "field_id": "cc5i4wkzktyqedh",
                "show": true
              },
              {
                "field_id": "ct41ytilwlxf7u3",
                "show": true
              }
            ],
            "options": {
              "row_height": "short"
            }
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Delete">
    ```bash
    {
      "type": "view.after.delete",
      "id": "af6a6298-91e9-4642-a729-93fb0eae9d61",
      "version": "v3",
        "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "views": [
          {
            "id": "vw45okb4letthls6",
            "table_id": "ma334932sjnwp3e",
            "title": "Grid-1 Renamed",
            "type": "grid",
            "lock_type": "collaborative",
            "created_at": "2025-09-22 06:51:13+00:00",
            "updated_at": "2025-09-22 07:08:29+00:00",
            "description": "",
            "created_by": "usq6o3vavwf0twzr",
            "fields": [
              {
                "field_id": "cc5i4wkzktyqedh",
                "show": true
              },
              {
                "field_id": "ct41ytilwlxf7u3",
                "show": true
              }
            ],
            "options": {
              "row_height": "short"
            }
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

#### Field trigger

<Tabs items={['After Create', 'After Update', 'After Delete']}>
  <Tab value="After Create">
    ```bash
    {
      "type": "field.after.create",
      "id": "2e97d383-1d94-48d7-8214-3a7fd013c801",
      "version": "v3",
      "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "fields": [
          {
            "id": "cqxah2exzt1lxbz",
            "table_id": "ma334932sjnwp3e",
            "title": "Financial Quarter",
            "type": "SingleSelect",
            "default_value": "'Q1'",
            "system": false,
            "options": {
              "choices": [
                {
                  "title": "Q1",
                  "color": "#cfdffe",
                  "id": "shs9oq0ddo1ecnq"
                },
                {
                  "title": "Q2",
                  "color": "#d0f1fd",
                  "id": "s65lkpm9822w8t7"
                },
                {
                  "title": "Q3",
                  "color": "#c2f5e8",
                  "id": "swg8jzbgh99t36f"
                },
                {
                  "title": "Q4",
                  "color": "#ffdaf6",
                  "id": "s9duce07erlzq5n"
                }
              ]
            },
            "description": "Specifies quarter in which this task is required to be included."
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Update">
    ```bash
    {
      "type": "field.after.update",
      "id": "6a4c9326-0bdc-4920-9089-6340394340b4",
      "version": "v3",
      "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "previous_fields": [
          {
            "id": "cqxah2exzt1lxbz",
            "table_id": "ma334932sjnwp3e",
            "title": "Financial Quarter",
            "type": "SingleSelect",
            "default_value": "'Q1'",
            "system": false,
            "options": {
              "choices": [
                {
                  "title": "Q1",
                  "color": "#cfdffe",
                  "id": "shs9oq0ddo1ecnq"
                },
                {
                  "title": "Q2",
                  "color": "#d0f1fd",
                  "id": "s65lkpm9822w8t7"
                },
                {
                  "title": "Q3",
                  "color": "#c2f5e8",
                  "id": "swg8jzbgh99t36f"
                },
                {
                  "title": "Q4",
                  "color": "#ffdaf6",
                  "id": "s9duce07erlzq5n"
                }
              ]
            },
            "description": "Specifies quarter in which this task is required to be included."
          }
        ],
        "fields": [
          {
            "id": "cqxah2exzt1lxbz",
            "table_id": "ma334932sjnwp3e",
            "title": "Financial Quarter",
            "type": "SingleSelect",
            "default_value": "'Quarter-1'",
            "system": false,
            "options": {
              "choices": [
                {
                  "title": "Quarter-1",
                  "color": "#cfdffe",
                  "id": "shs9oq0ddo1ecnq"
                },
                {
                  "title": "Quarter-2",
                  "color": "#d0f1fd",
                  "id": "s65lkpm9822w8t7"
                },
                {
                  "title": "Quarter-3",
                  "color": "#c2f5e8",
                  "id": "swg8jzbgh99t36f"
                },
                {
                  "title": "Quarter-4",
                  "color": "#ffdaf6",
                  "id": "s9duce07erlzq5n"
                }
              ]
            },
            "description": "Specifies quarter in which this task is required to be included."
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab value="After Delete">
    ```bash
    {
      "type": "field.after.delete",
      "id": "8b2b293f-a926-4280-b116-493ac197ba10",
      "version": "v3",
      "data": {
        "table_id": "ma334932sjnwp3e",
        "table_name": "AllTypes",
        "fields": [
          {
            "id": "cqxah2exzt1lxbz",
            "table_id": "ma334932sjnwp3e",
            "title": "Financial Quarter",
            "type": "SingleSelect",
            "default_value": "'Quarter-1'",
            "system": false,
            "options": {
              "choices": [
                {
                  "title": "Quarter-1",
                  "color": "#cfdffe",
                  "id": "shs9oq0ddo1ecnq"
                },
                {
                  "title": "Quarter-2",
                  "color": "#d0f1fd",
                  "id": "s65lkpm9822w8t7"
                },
                {
                  "title": "Quarter-3",
                  "color": "#c2f5e8",
                  "id": "swg8jzbgh99t36f"
                },
                {
                  "title": "Quarter-4",
                  "color": "#ffdaf6",
                  "id": "s9duce07erlzq5n"
                }
              ]
            },
            "description": "Specifies quarter in which this task is required to be included."
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

#### Manual trigger

<Tabs items={["Manual Trigger"]}>
  <Tab value="Manual Trigger">
    ```bash
    {
      "type": "records.manual.trigger",
      "id": "551a2010-d658-4185-a050-cf3fca56a5a9",
      "version": "v3",
      "data": {
        "table_id": "mzo4r3zrbcph43i",
        "table_name": "Features",
        "rows": [
          {
            "Id": 1,
            "Title": "dstala",
            "CreatedAt": "2024-08-12 11:56:15+00:00",
            "UpdatedAt": "2024-08-12 11:56:48+00:00",
            "Button": {
              "type": "url",
              "label": "Button",
              "url": "https://github.com/dstala"
            },
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

#### Discord Webhook

Discord webhook can be configured to send messages to a Discord channel. Discord request body should contain content, embeds or attachments, otherwise request will fail. Below is an example of Discord webhook payload. More details can be found [here](https://birdie0.github.io/discord-webhooks-guide/discord_webhook.html)

```json
{
  "content": "Hello, this is a webhook message",
  "embeds": [
    {
      "title": "Webhook",
      "description": "This is a webhook message",
      "color": 16711680
    }
  ]
}
```

To send complete event data to Discord, use below payload

```
{
  "content" : {{ json ( json event ) }}
}
```

One can also customize the payload as per the requirement. For example, to send only the `Title` field to Discord, use below payload. Note that, the value of `content` is what that will get displayed in the Discord channel.

```
{
   "content": "{{ event.data.rows.[0].Title }}"
}
```

## Environment Variables

In self-hosted version, you can configure the following environment variables to customize the webhook behavior.

* NC\_ALLOW\_LOCAL\_HOOKS: Allow localhost based links to be triggered. Default: false

Find more about environment variables [here](/docs/self-hosting/environment-variables)


# Webhook
URL: /docs/product-docs/automation/webhook

Learn how to create, modify and delete webhooks.

NocoDB supports webhooks to notify external systems in real time whenever records are created, updated, or deleted within a table. This allows seamless integration with third-party services by triggering automated workflows or syncing data changes as they happen.

Webhooks in NocoDB are **configured per table** and can be tailored with custom payloads, headers, and event-specific triggers to fit diverse automation needs.

This article discusses **Webhook v3**, which is the latest version of webhooks in NocoDB. It includes a new user interface and additional features compared to the previous version. For more information on the differences between webhook v2 and v3, please refer to the [Webhook v2 vs v3](/docs/product-docs/automation/webhook/webhook-v2-vs-v3) article.

<Callout type="note">
  [Webhook v2](/docs/product-docs/automation/webhook-v2-deprecated)

   will be deprecated in the future. While it will continue to function for a limited period, all new features and enhancements are exclusive to webhook v3. Users are strongly encouraged to migrate to webhook v3 for continued support and access to the latest functionality.
</Callout>

#### Related Topics

* [Create Webhook](/docs/product-docs/automation/webhook/create-webhook)
* [Disable Webhook](/docs/product-docs/automation/webhook/actions-on-webhook#enabledisable-webhook)
* [Modify Webhook](/docs/product-docs/automation/webhook/actions-on-webhook#edit-webhook)
* [Duplicate Webhook](/docs/product-docs/automation/webhook/actions-on-webhook#duplicate-webhook)
* [Delete Webhook](/docs/product-docs/automation/webhook/actions-on-webhook#delete-webhook)
* [Webhook Logs](/docs/product-docs/automation/webhook/actions-on-webhook#webhook-logs-)
* [Webhook v2 vs v3](/docs/product-docs/automation/webhook/webhook-v2-vs-v3)
* [Upgrade to v3](/docs/product-docs/automation/webhook/webhook-v2-vs-v3#upgrade-to-webhook-v3)


# Webhook v2 vs v3
URL: /docs/product-docs/automation/webhook/webhook-v2-vs-v3

Discover the key differences between webhook v2 and v3 in NocoDB, including event model, payload enhancements, and new features.







NocoDB’s webhook system has evolved significantly in version 3, introducing a more streamlined structure, richer payloads, and enhanced configuration capabilities. This update reflects feedback from real-world usage and aims to simplify integration while giving users more control over what triggers a webhook.

Below is a detailed comparison of key changes between webhook v2 and v3.

### **Unified Event Model for Record Operations**

In webhook v2, separate events were defined for individual and bulk operations—such as

* record.create, records.bulkCreate,
* record.update, records.bulkUpdate, and
* record.delete, records.bulkDelete.

This added complexity for consumers who needed to handle multiple event types for similar actions. Webhook v3 consolidates these into a simplified event model: **after insert, after update and after delete**. These events now apply uniformly to both single and bulk record operations.

### **Versioning in Webhook Payloads**

Starting with v3, the webhook response includes a version identifier in the payload. This enables client systems to reliably parse and process webhook data based on the expected schema, and future-proof integrations as NocoDB continues to evolve its webhook capabilities.

### **Enhanced Payload for Bulk Insert Operation**

Previously in webhook v2, the payload for bulk insert operations contained only the count of records that were inserted. This limited the ability to audit or react to specific insertions.

In v3, "After insert" webhook payload (unified for single insertion & bulk) includes the actual inserted records as an array. This enhancement allows integrators to trace exactly which records were inserted and take action accordingly—such as syncing insertions with external systems or logging for compliance.

### **New "Send Everything" Trigger Option**

Webhook v3 introduces a **"Send everything"** trigger in the UI. This option allows users to configure a webhook that triggers on any change to records within a table—without having to specify individual event types. It's particularly useful when external systems need to stay in sync with all changes, regardless of whether they are inserts, updates, or deletes.

### **Field-Level Change Monitoring**

Another key improvement in webhook v3 is the ability to configure **field-specific triggers**. This feature enables webhooks to fire only when certain fields are changed. For example, a webhook can be set to trigger only when the `Status` or `Priority` field is updated—helping reduce noise and streamline automation logic.

## Summary

| Feature                 | Webhook v2                        | Webhook v3                         |
| ----------------------- | --------------------------------- | ---------------------------------- |
| Event Model             | Separate events for bulk & single | Unified after insert/update/delete |
| Payload Version         | Not available                     | Included in every webhook payload  |
| Bulk Insert Payload     | Only count of records             | Full array of inserted records     |
| Send Everything Trigger | Not available                     | Supported                          |
| Field Change Monitoring | Not supported                     | Supported                          |

## Upgrade to webhook v3

If there are webhook v2 webhooks in your NocoDB instance, you will see a notification in the webhook list view. You can select the webhook that you want to upgrade to v3 and click on the **Upgrade** button. This will take you to the upgrade page where you can see the differences between the v2 and v3 webhook response. You can then click on the **Upgrade** button to upgrade the webhook to v3.

<img alt="webhook-upgrade-1" src={__img0} placeholder="blur" />
<img alt="webhook-upgrade-2" src={__img1} placeholder="blur" />
<img alt="webhook-upgrade-3" src={__img2} placeholder="blur" />


# Actions on webhook
URL: /docs/product-docs/automation/webhook-v2-deprecated/actions-on-webhook

Learn how to enable/disable, duplicate and delete webhooks.







<Callout type="note">
  This article refers to the legacy version of webhooks in NocoDB. Refer to [Webhook v3](/docs/product-docs/automation/webhook) for the latest features and improvements.
</Callout>

### Enable/disable Webhook

To disable a Webhook

* Open `Webhook` tab to find list of webhooks created
* Toggle `Activate` button to enable/disable

<img alt="Webhook List" src={__img0} placeholder="blur" />

### Edit Webhook

To edit a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on webhook to be edited
* This will open up the webhook configuration page, which is similar to the page used for [creating webhook](/docs/product-docs/automation/webhook-v2-deprecated/create-webhook). Reconfigure the webhook as required
* Click on `Save` button to save the changes

### Duplicate Webhook

To duplicate a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on `...` actions button associated with the webhook to be duplicate
* Select `Duplicate`

<img alt="Webhook context menu" src={__img1} placeholder="blur" />

A copy of the webhook will be created (disabled by default) with a suffix ` - Copy`

### Delete Webhook

To delete a Webhook

* Open `Webhook` tab to find list of webhooks created
* Click on `...` actions button associated with the webhook to be deleted
* Select `Delete`

<img alt="Webhook context menu" src={__img2} placeholder="blur" />


# Create webhook
URL: /docs/product-docs/automation/webhook-v2-deprecated/create-webhook

Learn how to create a webhook in NocoDB.





import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="note">
  This article refers to the legacy version of webhooks in NocoDB. Refer to [Webhook v3](/docs/product-docs/automation/webhook) for the latest features and improvements.
</Callout>

## Create Webhook

### Accessing webhook page

1. Click on table for which webhook needs to be configured on the left sidebar
2. Open `Details` tab in topbar,
3. Click on `Webhooks` tab
4. Click `Add New Webhook`

<img alt="Accessing webhook" src={__img0} placeholder="blur" />

### Configuring webhook

1. Name of the webhook
2. Select the event for which webhook needs to be triggered

| Trigger                      | Details                                     |
| ---------------------------- | ------------------------------------------- |
| After Record Insert          | After a single record is inserted           |
| After Record Update          | After a single record is updated            |
| After Record Delete          | After a single record is deleted            |
| After Multiple Record Insert | After bulk records are inserted             |
| After Multiple Record Update | After bulk records are updated              |
| After Multiple Record Delete | After bulk records are deleted              |
| Manual Trigger               | Manually trigger webhook using button field |

3. Method & URL: Configure the endpoint to which webhook needs to be triggered. Supported methods are GET, POST, DELETE, PUT, HEAD, PATCH
4. Headers & Parameters: Configure Request headers & parameters (optional)
5. Condition: Only records meeting the configured criteria will trigger webhook (optional)
6. Test webhook (with sample payload) to verify if parameter are configured appropriately (optional)
7. Save the webhook

<img alt="Configuring webhook" src={__img1} placeholder="blur" />

For more information on **Manual Trigger** webhook & its use with **Button** field, refer [here](/docs/product-docs/fields/field-types/custom-types/button)

### Webhook with conditions

In case of webhook with conditions, only records meeting the configured criteria will trigger webhook. For example, trigger webhook only when `Status` is `Complete`. You can also configure multiple conditions using `AND` or `OR` operators. For example, trigger webhook only when `Status` is `Complete` and `Priority` is `High`.

Webhook will be triggered only when the configured condition wasn't met before the record was updated. For example, if you have configured webhook with condition `Status` `is` `Complete` and `Priority` `is` `High` and you update the record with `Status` `Complete` and `Priority` `Low` to `High`, webhook will be triggered. However, if you update any other fields of the record with `Status` `Complete` and `Priority` `High`, webhook won't be triggered.

In summary, webhook will be triggered only when `Condition(old-record) = false` and `Condition(new-record) = true`.

<Callout type="info">
  Conditions are not applicable for Manual Trigger webhook
</Callout>

### Webhook response sample

<Tabs items={['After Insert', 'After Update', 'After Delete', "After Bulk Insert", "After Bulk Update", "After Bulk Delete", "Manual Trigger"]}>
  <Tab value="After Insert">
    ```bash
    {
        "type" : "records.after.insert",
        "id": "9dac1c54-b3be-49a1-a676-af388145fa8c",
        "data": {
            "table_id": "md_xzru7dcqrecc60",
            "table_name": "Film",
            "view_id": "vw_736wrpoas7tr0c",
            "view_name": "Film",
            "records": [
                {
                    "FilmId": 1011,
                    "Title": "FOO",
                    "Language": {
                        "LanguageId": 1,
                        "Name": "English"
                    },
                }
            ]
        }
    }
    ```
  </Tab>

  <Tab value="After Update">
    ```bash
        {
            "type": "records.after.update",
            "id": "6a6ebfe4-b0b5-434e-b5d6-5212adbf82fa",
            "data": {
                "table_id": "md_xzru7dcqrecc60",
                "table_name": "Film",
                "view_id": "vw_736wrpoas7tr0c",
                "view_name": "Film",
                "previous_records": [
                    {
                        "FilmId": 1,
                        "Title": "ACADEMY DINOSAUR",
                        "Description": "A Epic Drama of a Feminist in The Canadian Rockies",
                        "Actor List": [
                            {
                                "ActorId": 10,
                                "FirstName": "CHRISTIAN"
                            }
                        ],
                    }
                ],
                 "records": [
                    {
                        "FilmId": 1,
                        "Title": "ACADEMY DINOSAUR (Edited)",
                        "Actor List": [
                            {
                                "ActorId": 10,
                                "FirstName": "CHRISTIAN"
                            }
                        ],
                    }
                 ]
            }
        }
    ```
  </Tab>

  <Tab value="After Delete" label="After Delete">
    ```bash
        {
            "type": "records.after.delete",
            "id": "e593079f-70e5-4965-8944-5ff7aeed005c",
            "data": {
                "table_id": "md_xzru7dcqrecc60",
                "table_name": "Film",
                "view_id": "vw_736wrpoas7tr0c",
                "view_name": "Film",
                "records": [
                    {
                        "FilmId": 1010,
                        "Title": "ALL-EDITED",
                        "Language": {
                            "LanguageId": 1,
                            "Name": "English"
                        },
                    }
                ]
            }
        }
    ```
  </Tab>

  <Tab value="After Bulk Insert" label="After Bulk Insert">
    ```bash
    {
        "type": "records.after.bulkInsert",
        "id": "f8397b06-a399-4a3a-b6b0-6d1c0c2f7578",
        "data": {
            "table_id": "md_xzru7dcqrecc60",
            "table_name": "Film",
            "view_id": "vw_3fq2e9q8drkblw",
            "view_name": "GridView",
            "records_inserted": 2
        }
    }
    ```
  </Tab>

  <Tab value="After Bulk Update" label="After Bulk Update">
    ```bash
    {
        "type": "records.after.bulkUpdate",
        "id": "e983cea5-8e38-438e-96a0-048751f6830b",
        "data": {
            "table_id": "md_xzru7dcqrecc60",
            "table_name": "Film",
            "view_id": "vw_3fq2e9q8drkblw",
            "view_name": "Sheet-1",
            "previous_records": [
                [
                    {
                        "FilmId": 1005,
                        "Title": "Q",
                        "Language": {
                            "LanguageId": 1,
                            "Name": "English"
                        },
                    },
                    {
                        "FilmId": 1004,
                        "Title": "P",
                        "Language": {
                            "LanguageId": 1,
                            "Name": "English"
                        }
                    }
                ]
            ],
            "records": [
                [
                    {
                        "FilmId": 1005,
                        "Title": "Q-EDITED",
                        "Language": {
                            "LanguageId": 1,
                            "Name": "English"
                        }
                    },
                    {
                        "FilmId": 1004,
                        "Title": "P-EDITED",
                        "Language": {
                            "LanguageId": 1,
                            "Name": "English"
                        }
                    }
                ]
            ]
        }
    }
    ```
  </Tab>

  <Tab value="After Bulk Delete" label="After Bulk Delete">
    ```bash
        {
            "type": "records.after.bulkDelete",
            "id": "e7f1f4e5-7052-4ca2-9355-241ceb836f43",
            "data": {
                "table_id": "md_xzru7dcqrecc60",
                "table_name": "Film",
                "view_id": "vw_3fq2e9q8drkblw",
                "view_name": "Sheet-1",
                "records": [
                    [
                        {
                            "FilmId": 1022,
                            "Title": "x",
                            "Language": {
                                "LanguageId": 1,
                                "Name": "English"
                            },
                        },
                        {
                            "FilmId": 1023,
                            "Title": "x",
                            "Language": {
                                "LanguageId": 1,
                                "Name": "English"
                            },
                        }
                    ]
                ]
            }
        }
    ```
  </Tab>

  <Tab value="Manual Trigger" label="Manual Trigger">
    ```bash
    {
        "type": "records.manual.trigger",
        "id": "551a2010-d658-4185-a050-cf3fca56a5a9",
        "data": {
            "table_id": "mzo4r3zrbcph43i",
            "table_name": "Features",
            "rows": [
                {
                    "Id": 1,
                    "Title": "dstala",
                    "CreatedAt": "2024-08-12 11:56:15+00:00",
                    "UpdatedAt": "2024-08-12 11:56:48+00:00",
                    "Button": {
                        "type": "url",
                        "label": "Button",
                        "url": "https://github.com/dstala"
                    },
                }
            ]
        }
    }
    ```
  </Tab>
</Tabs>

### Webhook with custom payload ☁

<Callout type="info">
  This feature is only available in the paid plans, in both cloud & self-hosted
</Callout>

In the enterprise edition, you can set up a personalized payload for your webhook. Just head to the `Body` tab to make the necessary configurations. Users can utilize [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions), which allows them to access and manipulate the data easily.

Use `{{ json event }}` to access the event data. Sample response is as follows

```json
{
  "type": "records.after.insert",
  "id": "0698517a-d83a-4e72-bf7a-75f46b704ad1",
  "data": {
    "table_id": "m969t01blwprpef",
    "table_name": "Table-2",
    "view_id": "vwib3bvfxdqgymun",
    "view_name": "Table-2",
    "rows": [
      {
        "Id": 1,
        "Tags": "Sample Text",
        "CreatedAt": "2024-04-11T10:40:20.998Z",
        "UpdatedAt": "2024-04-11T10:40:20.998Z"
      }
    ]
  }
}
```

<Callout type="info">
  The custom payload feature is only available in the enterprise edition
</Callout>

#### Discord Webhook

Discord webhook can be configured to send messages to a Discord channel. Discord request body should contain content, embeds or attachments, otherwise request will fail. Below is an example of Discord webhook payload. More details can be found [here](https://birdie0.github.io/discord-webhooks-guide/discord_webhook.html)

```json
{
  "content": "Hello, this is a webhook message",
  "embeds": [
    {
      "title": "Webhook",
      "description": "This is a webhook message",
      "color": 16711680
    }
  ]
}
```

To send complete event data to Discord, use below payload

```
{
  "content" : {{ json ( json event ) }}
}
```

One can also customize the payload as per the requirement. For example, to send only the `Title` field to Discord, use below payload. Note that, the value of `content` is what that will get displayed in the Discord channel.

```
{
   "content": "{{ event.data.rows.[0].Title }}"
}
```

## Environment Variables

In self-hosted version, you can configure the following environment variables to customize the webhook behavior.

* NC\_ALLOW\_LOCAL\_HOOKS: Allow localhost based links to be triggered. Default: false

Find more about environment variables [here](/docs/self-hosting/environment-variables)


# Webhook v2 (deprecated)
URL: /docs/product-docs/automation/webhook-v2-deprecated

Learn how to create, modify and delete webhooks.

<Callout type="note">
  This article refers to the legacy version of webhooks in NocoDB. Refer to [Webhook v3](/docs/product-docs/automation/webhook) for the latest features and improvements.
</Callout>

You can employ webhooks to notify external systems whenever there are additions, updates, or removals of records within NocoDB. This feature allows you to receive instantaneous notifications for any changes made to your database through NocoDB. NocoDB also offers webhooks for bulk endpoints for creating, updating, or deleting multiple records simultaneously.

Note that, Webhooks currently are specific to associated table.

* [Create Webhook](/docs/product-docs/automation/webhook-v2-deprecated/create-webhook)
* [Disable Webhook](/docs/product-docs/automation/webhook-v2-deprecated/actions-on-webhook#enabledisable-webhook)
* [Modify Webhook](/docs/product-docs/automation/webhook-v2-deprecated/actions-on-webhook#edit-webhook)
* [Duplicate Webhook](/docs/product-docs/automation/webhook-v2-deprecated/actions-on-webhook#duplicate-webhook)
* [Delete Webhook](/docs/product-docs/automation/webhook-v2-deprecated/actions-on-webhook#delete-webhook)


# Actions on workflow
URL: /docs/product-docs/automation/workflow/actions-on-workflow

Learn how to rename, duplicate and delete a workflow in NocoDB.















### Rename Workflow

To rename a workflow:

* Use `...` actions button next to the workflow name in the Workflows list
* Select `Rename workflow`
* Enter a new name and confirm

<img alt="Rename Workflow" src={__img0} placeholder="blur" />

### Duplicate Workflow

To duplicate a workflow:

* Use `...` actions button next to the workflow name in the Workflows list
* Select `Duplicate workflow`

A copy of the workflow is created with a prefix `Copy of`.

<img alt="Duplicate Workflow" src={__img1} placeholder="blur" />

### Delete Workflow

To delete a workflow:

* Use `...` actions button next to the workflow name in the Workflows list
* Select `Delete workflow`
* Confirm deletion

> Deleted workflows cannot be restored.

<img alt="Delete Workflow" src={__img2} placeholder="blur" />

### Enable or Disable Workflow

A workflow when enabled will execute its triggers and actions as configured. Workflow can be enabled or disabled as needed using the toggle button in the workflow toolbar.

<img alt="Enable Disable Workflow" src={__img3} placeholder="blur" />

### Execution Logs

NocoDB provides detailed logs for each workflow execution to help monitor and debug workflows.

To view logs:

* Open the workflow
* On the toolbar, click on the **Logs** tab
* Select a run to view trigger input, node execution status, and outputs

**Execution list**: View all workflow runs with status and timestamps.
<img alt="Workflow Logs" src={__img4} placeholder="blur" />

**Execution summary**: Overview of selected run with trigger details and overall status.
<img alt="Workflow Logs" src={__img5} placeholder="blur" />

**Node execution details**: View input, output, and status for each node in the workflow. Select a node to see detailed information.
<img alt="Workflow Logs" src={__img6} placeholder="blur" />

***


# Create workflow
URL: /docs/product-docs/automation/workflow/create-workflow

Learn how to create a workflow in NocoDB.























### Accessing workflow page

Workflow's in NocoDB are base specific. To create a new workflow, open the desired base and

1. From base **Overview** page, click on the **Create Empty Workflow** button.
   * Alternatively, Click **Create New** in the left sidebar and select **Workflow**.
2. Specify a name for the workflow and click **Create Workflow**.
   * Optionally, provide a description to explain the workflow's purpose.

<img alt="Accessing workflow" src={__img0} placeholder="blur" />
<img alt="Accessing workflow" src={__img1} placeholder="blur" />
<img alt="Accessing workflow" src={__img2} placeholder="blur" />

You will land on the workflow editor page to configure the workflow.

* **Workflow list** : View all workflows in the base in the left sidebar
* **Toolbar** : Access workflow actions and settings
* **Editor** canvas : Design the workflow by adding and connecting nodes
* **Sidebar** : Configure selected node properties

<img alt="Workflow editor" src={__img3} placeholder="blur" />

***

### Configuring workflow

NocoDB Workflow builder provides a visual interface to design automation logic using interconnected nodes. To configure a workflow, follow these steps:

1. **Name the workflow:**
   Provide a clear and descriptive name to identify the workflow easily. Optionally, add a description to explain its purpose.
   <img alt="Naming workflow" src={__img4} placeholder="blur" />
   <img alt="Naming workflow" src={__img5} placeholder="blur" />

2. **Select Trigger:**
   Choose how the workflow should be initiated & configure additional node specific settings (resource & conditions) as required. There can be only one trigger node per workflow. Supported trigger types include:
   * **Record trigger** – Runs when a record is created, updated, or deleted
   * **Manual trigger** – Runs when triggered manually by a user
   * **Scheduled trigger** – Runs at specified time intervals
     <img alt="Adding trigger node" src={__img6} placeholder="blur" />

3. **Add Action nodes:**
   Define what happens when the workflow is triggered. You can chain multiple action nodes to perform sequential operations. Common action nodes include:
   * **Create / Update Record** – Modify data in a table
   * **Send Notification** – Notify users via supported channels
     <img alt="Adding action node" src={__img7} placeholder="blur" />

4. **Include Flow control nodes:**
   \[Optional] Add flow control nodes to manage execution logic, such as:
   * **If / else** – Conditional branching based on field values or runtime data
   * **Iterate** – Loop through a list of items and perform actions for each item
     <img alt="Adding flow control node" src={__img8} placeholder="blur" />

5. **Test workflow:**
   Use **Test Step** to validate individual nodes to verify correct configuration and expected behavior.
   <img alt="Testing workflow node" src={__img9} placeholder="blur" />

6. **Publish workflow:**
   Once satisfied with the configuration, use toggle button in the toolbar to enable the workflow & click **Publish** to save changes. An enabled workflow will run automatically when triggered.
   <img alt="Publishing workflow" src={__img10} placeholder="blur" />

***


# Workflow
URL: /docs/product-docs/automation/workflow

Learn about automation workflows in NocoDB.



**Workflows** in NocoDB enable you to automate repetitive tasks and streamline your processes. By setting up workflows, you can trigger actions based on specific events or conditions within your base. Each automation starts with a trigger and executes one or more actions, optionally controlled by flow logic such as if / else condition or an iteration.

<Callout type="note">
  Workflows are currently in 

  **beta**

   release & are available on NocoDB Cloud and on-premise licensed deployments.
</Callout>

<img alt="Example flow" src={__img0} placeholder="blur" />

A workflow consists of the following building blocks:

1. **Trigger node** – Defines `when` the automation runs
2. **Action nodes** – Defines `what` happens when the automation runs
3. **Flow nodes** – Defines `how` actions are executed (conditional logic, iteration)

## Trigger Node

A **Trigger** determines when an automation starts. Each automation must have exactly one trigger.

### When manually triggered

Runs the automation only when triggered manually by a user.
Useful for testing workflows or running one-off operations.

### At scheduled time

Runs the automation on a fixed schedule.

**Use cases**

* Daily or weekly reports
* Periodic data cleanup
* Scheduled reminders

### When record created

Triggers when a new record is added to a selected table.

**Use cases**

* Send notifications for new entries
* Auto-create related records
* Initialize default values

### When record updated

Triggers when an existing record is modified.

**Use cases**

* React to status changes
* Sync updates across tables
* Notify stakeholders on field changes

### When record deleted

Triggers when a record is removed from a table.

**Use cases**

* Cleanup dependent records
* Log deletions
* Notify administrators

### When form submitted

Triggers when a form view connected to a table is submitted.

**Use cases**

* Lead capture workflows
* Support request handling
* Survey response processing

### When record enters a view

Triggers when a record appears in a specific view for the first time. The view’s filters define the trigger condition.

**Use cases**

* Workflow stages
* Approval pipelines
* Task readiness detection

### When record matches conditions

Triggers when a record meets defined conditions. The conditions can be based on any field values in the record.

**Use cases**

* Rule-based automations
* SLA breaches
* Conditional alerts

## Action Nodes

Actions define what the automation does after the trigger fires. Multiple actions can be chained together. Actions execute sequentially in the order they are connected.

### Record Actions

#### Create record

Creates a new record in a specified table. The fields of the new record can be set using static values or data from previous actions.

**Use cases**

* Create follow-up tasks
* Insert audit logs
* Sync data across tables

#### Update record

Updates one or more fields in an existing record. The fields to update can be set using static values or data from previous actions.

**Use cases**

* Change status fields
* Set computed values
* Mark records as processed

#### Find record

Finds a single record matching specified criteria. The found record or its ID can be used in subsequent actions.

**Use cases**

* Locate related records
* Fetch data for later actions

#### List records

Retrieves multiple records that match defined filters. The resulting list can be used in flow nodes like **Iterate**.

**Use cases**

* Batch operations
* Iteration using flow nodes

#### Delete record

Deletes a record from a table. ID of the record to delete can be specified using static values or data from previous actions.

**Use cases**

* Data cleanup
* Lifecycle enforcement

## Communication Actions

### Send an email

Sends an email using configured email settings.

**Use cases**

* Notifications
* Alerts
* User confirmations

### Send message

Sends a message to an external messaging service (for example, Slack).

**Use cases**

* Team notifications
* Operational alerts
* Workflow updates

## Flow Nodes

Flow nodes control how actions are executed within an automation. They enable conditional branching and iteration over records.

### If / else

Adds conditional branching to the workflow. Based on the evaluation of a condition, it directs execution to either the **If** branch or the **Else** branch. The condition can be based on data from previous actions.

**Behavior**

* Evaluates a condition
* Executes actions in the **If** branch when condition is true
* Executes actions in the **Else** branch when condition is false

**Use cases**

* Approval logic
* Conditional notifications
* Business rule enforcement

### Iterate

Repeats a set of actions for each item in specified list data (for example, records from **List records** action).

**Behavior**

* Accepts array output from previous action
* Executes child actions once per array item

**Use cases**

* Bulk updates
* Batch notifications
* Record-by-record processing

## Execution Order

1. Trigger fires
2. Actions execute top-to-bottom
3. Flow nodes control branching or repetition
4. Automation completes once all paths finish execution
5. Logs are recorded for auditing

***


# Bar Chart
URL: /docs/product-docs/dashboards/widgets/bar-chart

Configure bar chart widgets to compare values across categories in your dashboard



<img alt="Bar Chart" src={__img0} placeholder="blur" />

The **Bar Chart** widget in NocoDB dashboards allows you to compare values across different categories. It is especially useful for highlighting trends, distributions, or comparisons between groups.

## Title & Description

* **Title**: Enter a title for the bar chart widget. This will be displayed prominently at the top of the widget.
* **Description**: Optionally, add a description to provide context or details about the data being visualized. This will appear below the title.

<img src="/img/v2/dashboards/widget-bar-chart-title.png" alt="Title" style={{ width: "50%" }} />

## Data Source

* **Table**: Select the table from which you want to pull data for the bar chart.
* **Records**: Choose which records to include:
  * **All Records**: Displays all records from the selected table.
  * **Records from a view**: Uses records from a specific view, allowing you to apply existing filters and sorts.
  * **Specific Records**: Apply custom filters to select only certain records.

<img src="/img/v2/dashboards/widget-bar-chart-source.png" alt="Title" style={{ width: "50%" }} />

## Display

### X-axis

* **Field**: Select the field whose values will be shown as categories along the X-axis (e.g., Product, Region, Status).
* **Sort By**: Choose the criteria to sort categories:
  * **xAxis Value**: Sorts based on the label values.
  * **yAxis Value**: Sorts based on the numeric values plotted.
* **Order**: Select Default, Ascending, or Descending order.
* **Include empty records**: Optionally, include categories that do not have values.
* **Include others**: Toggle to combine small or excess categories into an “Others” group for better readability.

### Y-axis

* **Fields**: Choose the field(s) that determine the bar lengths. You can add multiple fields for comparison.
* **Field Summary**: Displays the **Sum, Average, Min, or Max** of a numeric field.
* **Start at zero**: Ensures the Y-axis always begins at zero, which improves accuracy in comparing bar heights.

<img src="/img/v2/dashboards/widget-bar-chart-axis.png" alt="Title" style={{ width: "50%" }} />

## Appearance

Customize the look of the chart to improve readability and alignment with your dashboard:

* **Size**: Choose the chart size (Small, Medium).
* **Show value in chart**: Displays numeric values directly on the bars.
* **Show count in legend**: Adds record counts in the legend alongside category names.

<img src="/img/v2/dashboards/widget-bar-chart-style.png" alt="Title" style={{ width: "50%" }} />


# Donut Chart
URL: /docs/product-docs/dashboards/widgets/donut-chart

Configure donut chart widgets to visualize data distribution in your dashboard







The **Donut Chart** widget in NocoDB dashboards is a variant of the pie chart that features a hollow center, allowing for additional information or metrics to be displayed. It is particularly useful for showing how different segments contribute to a whole while providing space for supplementary details.

## Title & Description

* **Title**: Enter a title for the donut chart widget. This will be displayed prominently at the top of the widget.
* **Description**: Optionally, add a description to provide context or details about the data being visualized. This will appear below the title.
  <img alt="Title" src={__img0} placeholder="blur" />

## Data Source

* **Table**: Select the table from which you want to pull data for the donut chart. This is the primary source of records for the visualization.
* **Record**: Select records from the chosen table to be included in the donut chart. You can choose from:
  * **All Records**: Displays all records in the selected table.
  * **Records from a view**: Allows you to filter records based on a specific view, enabling focused visualizations. You need to select a view from the dropdown.
  * **Specific Records**: Apply filters to select specific records for the donut chart. This is useful for showing data based on certain criteria. You can add multiple filters to refine the selection.

<div style={{ display: "flex", gap: "1rem", justifyContent: "center", flexWrap: "wrap" }}>
  <img src="/img/v2/dashboards/widget-number-source-1.png" alt="Number Widget Config 1" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />

  <img src="/img/v2/dashboards/widget-number-source-2.png" alt="Number Widget Config 2" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />
</div>

## Display

* **Category Field**: Select the field that will be used to determine the segments of the donut chart. This field should contain categorical data that you want to visualize.
  * **Order**: Choose how the segments are ordered in the donut chart. You can order them by:
    * **Default**: Segments are displayed in the order they appear in the data.
    * **Ascending**: Segments are sorted in ascending order based on their values.
    * **Descending**: Segments are sorted in descending order based on their values.
  * **Include empty records**: Optionally, you can choose to include records that do not have a value for the selected category field. This can help in visualizing segments that may otherwise be omitted due to missing data.

* **Value Field**: Choose the field that will determine the size of each segment in the donut chart. This field should contain numerical data that represents the value for each category.
  * **Record Count**: Displays the count of records for each category.
  * **Field Summary**: Shows the sum, average, minimum, maximum, or count of a specific field across the selected records. Available options vary based on the field type.

<img alt="Field Summary" src={__img1} placeholder="blur" />

## Appearance

You can customize the appearance of the donut chart to enhance its visual appeal and clarity. The following options are available:

* **Size**: Adjust the size of the donut chart to fit your dashboard layout. You can choose from small or medium sizes.

* **Legend Orientation**: Choose the orientation of the legend that displays the category names and their corresponding colors. Options include:
  * **Right**: Places the legend to the right of the donut chart.
  * **Bottom**: Places the legend below the donut chart.
  * **Left**: Places the legend to the left of the donut chart.
  * **Top**: Places the legend above the donut chart.

* **Show Percentage in chart**: Enable this option to display the percentage contribution of each segment within the donut chart. This provides additional context for understanding the data distribution.

* **Show Count in Legend**: Enable this option to display the count of records for each category in the legend. This helps in understanding the number of records represented by each segment.

<img alt="Appearance" src={__img2} placeholder="blur" />


# iFrame
URL: /docs/product-docs/dashboards/widgets/iframe

Embed external content securely inside your dashboard using the iFrame widget



The **iFrame** widget in NocoDB allows you to embed external web pages, applications, or dashboards directly inside your NocoDB dashboard. This is useful for integrating third-party tools, live reports, charts, or any web resource you want to monitor alongside your database data.

<img alt="iframe-widget" src={__img0} placeholder="blur" />

## Configuration

* **URL**
  Enter the web page URL you want to embed.

> ⚠️ Only a limited set of **whitelisted domains** are supported. If the URL does not belong to a whitelisted domain, it cannot be embedded.

* **Parameters**
  You can pass query parameters to control the embedded page. For example:

```
https://app.nocodb.com/sharedViewID?disableTopbar=true&disableToolbar=false
```

## NocoDB iFrame Whitelist

The following domains are whitelisted for embedding in NocoDB iFrames.

| Analytics & Business Intelligence | Automation & Workflow | Calendar & Scheduling |
| --------------------------------- | --------------------- | --------------------- |
| datawrapper.de                    | make.com              | cal.com               |
| looker.com                        | n8n.io                | calendly.com          |
| metabase.com                      | zapier.com            | tidycal.com           |
| powerbi.microsoft.com             |                       |                       |
| tableau.com                       |                       |                       |

| Cloud Storage & File Sharing | Communication & Collaboration | Database & Data Management |
| ---------------------------- | ----------------------------- | -------------------------- |
| dropbox.com                  | loom.com                      | airtable.com               |
| google.com                   | mural.co                      | getgrist.com               |
|                              | pitch.com                     | nocodb.com                 |
|                              | sli.do                        |                            |
|                              | slido.com                     |                            |

| Design & Prototyping | Developer Tools & Code | Diagramming & Mind Mapping |
| -------------------- | ---------------------- | -------------------------- |
| canva.com            | codepen.io             | dbdiagram.io               |
| figma.com            | codesandbox.io         | diagrams.net               |
| framer.com           | gist.github.com        | draw\.io                   |
| invisionapp.com      | github.com             | gliffy.com                 |
| marvelapp.com        | gitlab.com             | lucid.co                   |
| penpot.app           | jsfiddle.net           | lucidchart.com             |
| sketch.com           | postman.com            | mindmeister.com            |
| zeplin.io            | replit.com             | miro.com                   |
|                      | swagger.io             | tldraw\.com                |
|                      | val.town               | whimsical.com              |

| Documentation & Knowledge Management | Forms & Surveys  | Media & Entertainment |
| ------------------------------------ | ---------------- | --------------------- |
| atlassian.com                        | forms.gle        | instagram.com         |
| descript.com                         | jotform.com      | pinterest.com         |
| gitbook.com                          | surveymonkey.com | spotify.com           |
| notion.so                            | tally.so         | vimeo.com             |
| obsidian.md                          | typeform.com     | youtu.be              |
| scribehow\.com                       |                  | youtube.com           |
| slab.com                             |                  |                       |

| Project Management |
| ------------------ |
| asana.com          |
| basecamp.com       |
| clickup.com        |
| coda.io            |
| linear.app         |
| monday.com         |
| trello.com         |

> **Note**: All domains include both the root domain and wildcard subdomains (e.g., `example.com` and `*.example.com`) in the whitelist configuration.

## Use Cases

* Embedding analytics dashboards (e.g., Metabase, Grafana, Superset).
* Displaying Google Docs, Sheets, or Slides within NocoDB.
* Showing interactive charts or visualizations from allowed external apps.
* Integrating custom internal tools from whitelisted domains.


# Widgets
URL: /docs/product-docs/dashboards/widgets

Add and configure widgets to visualize data in your dashboard









The dashboard editor provides a flexible canvas where you can arrange widgets. You can drag and drop widgets to position them as needed.

NocoDB dashboards support the following widget types:

| Widget Type                                                          | Description                            |
| -------------------------------------------------------------------- | -------------------------------------- |
| **[Number](/docs/product-docs/dashboards/widgets/number)**           | Displays KPIs and metric summaries     |
| **[Bar Chart](/docs/product-docs/dashboards/widgets/bar-chart)**     | Compares values across categories      |
| **[Line Chart](/docs/product-docs/dashboards/widgets/line-chart)**   | Shows trends over time                 |
| **[Pie Chart](/docs/product-docs/dashboards/widgets/pie-chart)**     | Visualizes parts of a whole            |
| **[Donut Chart](/docs/product-docs/dashboards/widgets/donut-chart)** | Pie chart variant with a hollow center |
| **[Text](/docs/product-docs/dashboards/widgets/text)**               | Displays static information            |
| **[iFrame](/docs/product-docs/dashboards/widgets/iframe)**           | Embeds external web content            |

### Adding Widgets

Click on Edit Dashboard to enter the dashboard editor. Then, use the widget toolbar at the top to add widgets. You can either click on the widget type in the toolbar or drag and drop it onto the dashboard canvas.

<img alt="widget-bar" src={__img0} placeholder="blur" />

### Configuring Widgets

Once a widget is added, you can configure its properties using the right panel. Each widget type has specific configuration options, such as:

* **Data Source**: Select the table and records to visualize.
* **Display Options**: Customize labels, colors, and formatting.

Refer to widget specific notes to learn more about available options for widget configuration.

<div style={{ display: "flex", gap: "1rem", justifyContent: "center", flexWrap: "wrap" }}>
  <img src="/img/v2/dashboards/widget-number-edit-1.png" alt="Number Widget Config 1" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />

  <img src="/img/v2/dashboards/widget-number-edit-2.png" alt="Number Widget Config 2" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />
</div>

### Arranging Widgets

You can drag and drop widgets to rearrange them on the dashboard canvas. NocoDB supports a flexible grid layout, allowing you to position widgets as needed.

<img alt="widget-reorder" src={__img1} placeholder="blur" />

### Resizing Widgets

To resize a widget, hover over its right-corner until the resize cursor appears. Click and drag to adjust the widget size. Widget specific restrictions apply. Some widgets can be only resized horizontally.

### Deleting Widgets

To remove a widget, click on 3-dot menu in the widget header and select **Delete widget**.

<img alt="widget-actions" src={__img2} placeholder="blur" />

### Duplicating Widgets

To create a copy of a widget, click on the 3-dot menu in the widget header and select **Duplicate widget**. This is useful for creating similar widgets with minor variations.

<img alt="widget-actions" src={__img3} placeholder="blur" />

***


# Line Chart
URL: /docs/product-docs/dashboards/widgets/line-chart

Configure line chart widgets to visualize trends and comparisons over time or categories in your dashboard



<img alt="Line Chart" src={__img0} placeholder="blur" />

The **Line Chart** widget in NocoDB dashboards allows you to visualize trends and comparisons across categories or time. It is especially useful for tracking changes, identifying patterns, and comparing multiple metrics simultaneously.

## Title & Description

* **Title**: Enter a title for the line chart widget. This will be displayed prominently at the top of the widget.
* **Description**: Optionally, add a description to provide context or details about the data being visualized. This will appear below the title.

<img src="/img/v2/dashboards/widget-line-graph-title.png" alt="Line Chart Title" style={{ width: "50%" }} />

## Data Source

* **Table**: Select the table from which you want to pull data for the line chart.
* **Records**: Choose which records to include:
  * **All Records**: Displays all records from the selected table.
  * **Records from a view**: Uses records from a specific view, allowing you to apply filters and sorts.
  * **Specific Records**: Apply custom filters to select only certain records.

<img src="/img/v2/dashboards/widget-line-graph-source.png" alt="Line Chart Data Source" style={{ width: "50%" }} />

## Display

### X-axis

* **Field**: Select the field whose values will be shown along the X-axis (e.g., Date, Product, Category).
* **Sort By**: Choose how categories are sorted:
  * **xAxis Value**: Sorts based on the label values.
  * **yAxis Value**: Sorts based on the numeric values plotted.
* **Order**: Select Default, Ascending, or Descending.
* **Include empty records**: Optionally include categories that have no values.
* **Include others**: Toggle to group smaller categories into an “Others” bucket.

### Y-axis

* **Fields**: Choose the field(s) to plot on the Y-axis. You can add multiple fields to display multiple lines in the chart.
* **Record Count**: Shows the number of records for each category.
* **Field Summary**: Displays the **Sum, Average, Min, or Max** of a numeric field.
* **Start at zero**: Ensures the Y-axis always begins at zero for consistency.

<img src="/img/v2/dashboards/widget-line-graph-axis.png" alt="Line Chart Axis Config" style={{ width: "50%" }} />

## Appearance

Customize how the chart is displayed for clarity and readability:

* **Size**: Adjust the chart size (Small, Medium).
* **Legend Orientation**: Choose where to display the legend (Top, Bottom, Left, Right).
* **Show count in legend**: Enable to display record counts in the legend.
* **Plot data points**: Enable to highlight data points on the line.
* **Smooth lines**: Enable to display smoothed curves instead of jagged lines.

<img src="/img/v2/dashboards/widget-line-graph-style.png" alt="Line Chart Appearance" style={{ width: "50%" }} />


# Number
URL: /docs/product-docs/dashboards/widgets/number

Configure number widgets to display key metrics in your dashboard











The section here details various configuration options available for the **Number** widget in NocoDB dashboards. This widget is designed to display key performance indicators (KPIs) and metric summaries in a clear, concise format.

## Title & description

* **Title**: Enter a title for the number widget. This will be displayed prominently at the top of the widget.
* **Description**: Optionally, add a description to provide context or details about the metric being displayed. This will appear below the title.

<img alt="Title" src={__img0} placeholder="blur" />

## Data source

* **Table**: Select the table from which you want to pull data for the number widget. This is the primary source of records for the metric.
* **Record**: Select records from the chosen table to be included in the metric calculation. You can choose from:
  * **All Records**: Displays the total count of records in the selected table.
  * **Records from a view**: Allows you to filter records based on a specific view, enabling focused metrics. You need to select a view from the dropdown.
  * **Specific Records**: Apply filters to select specific records for the metric. This is useful for showing metrics based on certain criteria. You can add multiple filters to refine the selection.

<div style={{ display: "flex", gap: "1rem", justifyContent: "center", flexWrap: "wrap" }}>
  <img src="/img/v2/dashboards/widget-number-source-1.png" alt="Number Widget Config 1" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />

  <img src="/img/v2/dashboards/widget-number-source-2.png" alt="Number Widget Config 2" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />
</div>

## Display

* **Record Count**: Displays the total number of records in the selected source.
* **Field Summary**: Shows the sum, average, minimum, maximum, or count of a specific field across the selected records. Available options vary based on the field type.

<img alt="Field Summary" src={__img1} placeholder="blur" />

## Appearance

**Number Format**: Choose how the number is displayed, such as:

* **Default**: Standard numeric format.
* **Filled**: Displays the number with a filled background.
* **Coloured Text**: Uses color to highlight the number, making it stand out.

<img alt="Appearance" src={__img2} placeholder="blur" />

<img alt="Appearance" src={__img3} placeholder="blur" />

<img alt="Appearance" src={__img4} placeholder="blur" />


# Pie Chart
URL: /docs/product-docs/dashboards/widgets/pie-chart

Configure pie chart widgets to visualize data distribution in your dashboard







The **Pie Chart** widget in NocoDB dashboards allows you to visualize data distribution across categories. It is particularly useful for showing how different segments contribute to a whole.

## Title & Description

* **Title**: Enter a title for the pie chart widget. This will be displayed prominently at the top of the widget.
* **Description**: Optionally, add a description to provide context or details about the data being visualized. This will appear below the title.

<img alt="Title" src={__img0} placeholder="blur" />

## Data Source

* **Table**: Select the table from which you want to pull data for the pie chart. This is the primary source of records for the visualization.
* **Record**: Select records from the chosen table to be included in the pie chart. You can choose from:
  * **All Records**: Displays all records in the selected table.
  * **Records from a view**: Allows you to filter records based on a specific view, enabling focused visualizations. You need to select a view from the dropdown.
  * **Specific Records**: Apply filters to select specific records for the pie chart. This is useful for showing data based on certain criteria. You can add multiple filters to refine the selection.

<div style={{ display: "flex", gap: "1rem", justifyContent: "center", flexWrap: "wrap" }}>
  <img src="/img/v2/dashboards/widget-number-source-1.png" alt="Number Widget Config 1" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />

  <img src="/img/v2/dashboards/widget-number-source-2.png" alt="Number Widget Config 2" style={{ width: "30%", minWidth: "240px", borderRadius: "8px", border: "1px solid #ddd" }} />
</div>

## Display

* **Category Field**: Select the field that will be used to determine the segments of the pie chart. This field should contain categorical data that you want to visualize.
  * **Order**: Choose how the segments are ordered in the pie chart. You can order them by:
    * **Default**: Segments are displayed in the order they appear in the data.
    * **Ascending**: Segments are sorted in ascending order based on their values.
    * **Descending**: Segments are sorted in descending order based on their values.

  * **Include empty records**: Optionally, you can choose to include records that do not have a value for the selected category field. This can help in visualizing segments that may otherwise be omitted due to missing data.

* **Value Field**: Choose the field that will determine the size of each segment in the pie chart. This field should contain numerical data that represents the value for each category.
  * **Record Count**: Displays the count of records for each category.
  * **Field Summary**: Shows the sum, average, minimum, maximum, or count of a specific field across the selected records. Available options vary based on the field type.

<img alt="Field Summary" src={__img1} placeholder="blur" />

## Appearance

You can customize the appearance of the pie chart to enhance its visual appeal and clarity. The following options are available:

* **Size**: Adjust the size of the pie chart to fit your dashboard layout. You can choose from small or medium sizes.

* **Legend Orientation**: Choose the orientation of the legend that displays the category names and their corresponding colors. Options include:
  * **Right**: Places the legend to the right of the pie chart.
  * **Bottom**: Places the legend below the pie chart.
  * **Left**: Places the legend to the left of the pie chart.
  * **Top**: Places the legend above the pie chart.

* **Show Percentage in chart**: Enable this option to display the percentage contribution of each segment within the pie chart. This provides additional context for understanding the data distribution.

* **Show Count in Legend**: Enable this option to display the count of records for each category in the legend. This helps in understanding the number of records represented by each segment.

<img alt="Appearance" src={__img2} placeholder="blur" />


# Text
URL: /docs/product-docs/dashboards/widgets/text

Configure text widgets to add static textual content to your dashboard









The section here details various configuration options available for the **Text** widget in NocoDB dashboards. This widget is designed to display descriptive content, instructions, notes, or disclaimers, helping you add context or guidance alongside your data visualizations.

## Content

Type the text you want to display. This can be:

* Instructions for dashboard users
* Explanatory notes for data insights
* Compliance or legal disclaimers
* Motivational or status updates for teams

You can choose between two content modes:

* **Markdown**: Write using markdown syntax for headings, lists, links, images, blockquotes, code, and tables. Find more details about supported markdown syntax in the [Markdown Guide](/docs/product-docs/fields/field-types/text-based/rich-text#formatting-options).
* **Text**: Use the inline editor for direct styling.

<img alt="widget-text" src={__img0} placeholder="blur" />

<img alt="widget-text" src={__img1} placeholder="blur" />

## Formatting

Use the inline editor to style your text:

* **Bold**, *Italic*, and <u>underline</u> for emphasis.
* Horizontal alignment (**left**, **center**, **right**).
* Vertical alignment (**top**, **middle**, **bottom**).

<img alt="widget-text" src={__img2} placeholder="blur" />

## Appearance

Customize how the text is presented in the widget:

<Callout type="info">
  Appearance options are available only when the content mode is set to **Text**.
</Callout>

* **Font**: Choose from available font families.
* **Weight**: Set text thickness (e.g., Light, Medium, Bold).
* **Size**: Adjust the font size to suit your layout.
* **Line Height**: Control spacing between lines for better readability.
* **Text Color**: Select any color to highlight your content.

<img alt="widget-text" src={__img3} placeholder="blur" />

***


# Accessing APIs
URL: /docs/product-docs/developer-resources/rest-apis/accessing-apis

How to access NocoDB APIs with Auth or API token?

## API Tokens

NocoDB APIs can be authorized by using API Tokens. API tokens allow us to integrate seamlessly with 3rd party apps. See [API Tokens Management](/docs/product-docs/account-settings/api-tokens) for more.

## Swagger UI

You can interact with the API's resources via the Swagger UI. For more details, see [Swagger APIs Doc](/docs/product-docs/bases/actions-on-base#rest-apis)


# REST APIs
URL: /docs/product-docs/developer-resources/rest-apis

NocoDB REST API Overview































NocoDB provides a comprehensive set of REST APIs that allow you to interact programmatically with your data, metadata, and workspace resources. These APIs make it possible to integrate NocoDB with external applications, automate workflows, build custom tools, or manage your bases at scale.

Whether you want to query records, update fields, manage tables, or retrieve metadata, NocoDB exposes clear and consistent API surfaces designed for both simple and advanced use cases. This document outlines the available API types, explains how to construct endpoints, and guides you through locating the required IDs for making requests.

Use this reference as your starting point for building reliable, API-driven integrations with NocoDB.

* [Data APIs](https://data-apis-v3.nocodb.com/)
* [Meta APIs](https://meta-apis-v3.nocodb.com/)

<Callout type="info">
  Collaboration related Meta APIs are available on NocoDB Cloud Business+ plans and Self-hosted Enterprise plans. View & Script related Meta APIs are available on NocoDB Cloud and Self-hosted Enterprise plans.
</Callout>

When querying using v3 apis, see [v3 Where Clause](/docs/product-docs/developer-resources/rest-apis#v3-where-query-parameter) for a slight difference between the two version's where clause.

## Finding Your API IDs

Before making API calls, you'll need to identify and copy the relevant IDs required for constructing your endpoints. This section walks you through locating each essential identifier.

### Workspace ID

**Workspace ID** is an alphanumeric identifier prefixed with `w` (representing *workspace*) that uniquely identifies your workspace in NocoDB. It appears in the URL bar when viewing any base within the workspace.

You can also find it in the workspace context menu (accessible by clicking the workspace icon in the minibar). Click the ID to copy it to your clipboard.

<img alt="Workspace ID" src={__img0} placeholder="blur" />

Workspace ID can also be retrieved from Workspace settings page.

<img alt="Workspace ID" src={__img1} placeholder="blur" />

### Base ID

**Base ID** is required for metadata APIs and administrative operations. It uniquely identifies a specific database (or base) within your workspace.

The Base ID is an alphanumeric identifier prefixed with `p` (representing *project*), visible in the URL when accessing any table or base-level settings. You can also find it in the base context menu (chevron next to the base name) in the left sidebar, where you can click the ID to copy it to your clipboard.

<img alt="Base ID" src={__img2} placeholder="blur" />

### Table ID

**Table ID** is the most commonly used identifier and is required for all data API calls. It uniquely identifies a specific table within your base.

The Table ID is an alphanumeric string prefixed with `m` (representing *model*), visible in the URL immediately after the Base ID when viewing a table. You can also find it in the table context menu (three dots next to the table name) in the left sidebar. Click the ID to copy it to your clipboard.

<img alt="Table ID" src={__img3} placeholder="blur" />

### View ID

**View ID** is used for view-specific API operations, such as fetching records from a particular view. It uniquely identifies a specific view within a table.

The View ID is an alphanumeric string prefixed with `v` (representing *view*), visible in the URL when a specific view is open. You can also find it in the view context menu (three dots next to the view name) in the left sidebar. Click the ID to copy it to your clipboard.

<img alt="View ID" src={__img4} placeholder="blur" />

View ID can also be retrieved from view toolbar > more actions (3 dots) menu

<img alt="View ID" src={__img5} placeholder="blur" />

### Field ID

**Field ID** is used for field-specific API operations, such as updating field properties. It uniquely identifies a specific column within a table.

The Field ID is an alphanumeric string prefixed with `c` (representing *column*), visible in the URL when viewing or editing a field’s settings. You can also find it in the field context menu (chevron next to the field name) in the field header bar. Click the ID to copy it to your clipboard.

<img alt="Field ID" src={__img6} placeholder="blur" />

Field ID can also be retrieved from `Details` > `Fields` editor

<img alt="Field ID" src={__img7} placeholder="blur" />

### Record ID

**Record ID** is used for record-specific API operations, such as retrieving or updating an individual record. It uniquely identifies a specific row within a table.

By default, the Record ID is a numeric value starting from 1. You can display the **ID** field (which corresponds to the Record ID) by opening the **Fields** menu in the toolbar and enabling **Show System Fields**.

<img alt="Record ID" src={__img8} placeholder="blur" />

You can also find it in the URL when viewing a specific record (expanded record view).

<img alt="Record ID" src={__img9} placeholder="blur" />

You can also access the Record ID in formulas by selecting **ID** from the list of available fields in the formula editor or by using the `RECORD_ID()` function.

<img alt="Record ID" src={__img10} placeholder="blur" />

### User ID

**User ID** is used for user-specific API operations, such as retrieving user details. It uniquely identifies a specific user within your workspace or organization.

The User ID is an alphanumeric string prefixed with `u` (representing *user*). You can find it on either the **Workspace Members** page or the **Base Members** page by clicking the three dots menu next to a user’s name. Click the ID to copy it to your clipboard.

<img alt="User ID" src={__img11} placeholder="blur" />

<img alt="User ID" src={__img12} placeholder="blur" />

### Data Source ID

For external data sources connected to NocoDB (such as Postgres or MySQL), the **Data Source ID** is additionally required to perform data API operations.

The Data Source ID is an alphanumeric string that uniquely identifies the connected data source. You can find it in the context menu by clicking the three dots next to the data source name in the left sidebar. Click the ID to copy it to your clipboard.

<img alt="Data Source ID" src={__img13} placeholder="blur" />

You can also find it in the Data Source settings page.

<img alt="Data Source ID" src={__img14} placeholder="blur" />

## Rate Limits

NocoDB APIs are rate-limited to ensure fair usage and optimal performance for all users. The default rate limit is set to **5 requests per second per user**. These limits are the same across all plans.

If these limits are exceeded, the API will return a 429 status code (Too Many Requests). You’ll need to wait 30 seconds before sending additional requests.

NocoDB may adjust these limits or introduce additional rate tiers based on pricing plans to maintain optimal service performance.

## Query params

| **Name**                       | **Alias**                  | **Use case**                                                 | **Default value** | **Example value**                                                                                                                                                 |
| ------------------------------ | -------------------------- | ------------------------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [where](#comparison-operators) | [w](#comparison-operators) | Complicated where conditions                                 |                   | `(colName,eq,colValue)~or(colName2,gt,colValue2)` <br />[Usage: Comparison operators](#comparison-operators) <br />[Usage: Logical operators](#logical-operators) |
| limit                          | l                          | Number of rows to get (SQL limit value)                      | 10                | 20                                                                                                                                                                |
| offset                         | o                          | Offset for pagination (SQL offset value)                     | 0                 | 20                                                                                                                                                                |
| sort                           | s                          | Sort by column name, Use `-` as a prefix for descending sort |                   | column\_name                                                                                                                                                      |
| fields                         | f                          | Required column names in result                              | \*                | column\_name1,column\_name2                                                                                                                                       |
| shuffle                        | r                          | Shuffle the result for pagination                            | 0                 | 1 (Only allow 0 or 1. Other values would see it as 0)                                                                                                             |

## Comparison Operators

| Operation | Meaning                                                         | Example                          |
| --------- | --------------------------------------------------------------- | -------------------------------- |
| eq        | equal                                                           | (colName,eq,colValue)            |
| neq       | not equal                                                       | (colName,neq,colValue)           |
| not       | not equal (alias of neq)                                        | (colName,not,colValue)           |
| gt        | greater than                                                    | (colName,gt,colValue)            |
| ge        | greater or equal                                                | (colName,ge,colValue)            |
| lt        | less than                                                       | (colName,lt,colValue)            |
| le        | less or equal                                                   | (colName,le,colValue)            |
| is        | is                                                              | (colName,is,true/false/null)     |
| isnot     | is not                                                          | (colName,isnot,true/false/null)  |
| in        | in                                                              | (colName,in,val1,val2,val3,val4) |
| btw       | between                                                         | (colName,btw,val1,val2)          |
| nbtw      | not between                                                     | (colName,nbtw,val1,val2)         |
| like      | like                                                            | (colName,like,%name)             |
| nlike     | not like                                                        | (colName,nlike,%name)            |
| isWithin  | is Within (Available in `Date` and `DateTime` only)             | (colName,isWithin,sub\_op)       |
| allof     | includes all of                                                 | (colName,allof,val1,val2,...)    |
| anyof     | includes any of                                                 | (colName,anyof,val1,val2,...)    |
| nallof    | does not include all of (includes none or some, but not all of) | (colName,nallof,val1,val2,...)   |
| nanyof    | does not include any of (includes none of)                      | (colName,nanyof,val1,val2,...)   |

## Comparison Sub-Operators

The following sub-operators are available in the `Date` and `DateTime` columns.

| Operation       | Meaning                 | Example                           |
| --------------- | ----------------------- | --------------------------------- |
| today           | today                   | (colName,eq,today)                |
| tomorrow        | tomorrow                | (colName,eq,tomorrow)             |
| yesterday       | yesterday               | (colName,eq,yesterday)            |
| oneWeekAgo      | one week ago            | (colName,eq,oneWeekAgo)           |
| oneWeekFromNow  | one week from now       | (colName,eq,oneWeekFromNow)       |
| oneMonthAgo     | one month ago           | (colName,eq,oneMonthAgo)          |
| oneMonthFromNow | one month from now      | (colName,eq,oneMonthFromNow)      |
| daysAgo         | number of days ago      | (colName,eq,daysAgo,10)           |
| daysFromNow     | number of days from now | (colName,eq,daysFromNow,10)       |
| exactDate       | exact date              | (colName,eq,exactDate,2022-02-02) |

For `isWithin` in `Date` and `DateTime` columns, the different set of sub-operators are used.

| Operation        | Meaning                 | Example                                |
| ---------------- | ----------------------- | -------------------------------------- |
| pastWeek         | the past week           | (colName,isWithin,pastWeek)            |
| pastMonth        | the past month          | (colName,isWithin,pastMonth)           |
| pastYear         | the past year           | (colName,isWithin,pastYear)            |
| nextWeek         | the next week           | (colName,isWithin,nextWeek)            |
| nextMonth        | the next month          | (colName,isWithin,nextMonth)           |
| nextYear         | the next year           | (colName,isWithin,nextYear)            |
| nextNumberOfDays | the next number of days | (colName,isWithin,nextNumberOfDays,10) |
| pastNumberOfDays | the past number of days | (colName,isWithin,pastNumberOfDays,10) |

## Logical Operators

| Operation | Example                                                              |
| --------- | -------------------------------------------------------------------- |
| \~or      | (checkNumber,eq,JM555205)\~or((amount,gt,200)\~and(amount,lt,2000))  |
| \~and     | (checkNumber,eq,JM555205)\~and((amount,gt,200)\~and(amount,lt,2000)) |
| \~not     | \~not(checkNumber,eq,JM555205)                                       |

## v3 Where Query Parameter

When calling v3 data api, the where clause has a slight difference with the previous versions. It allows values to be wrapped with quotes (double quotes, single quotes, or backticks) to safely use special characters that might otherwise break older version `where` clauses. This is particularly useful for strings containing commas, parentheses, or other delimiters.

**Example:** Searching for a phrase with special characters:
`("My Field", like, "Let's come home, and go straight to bed")`

**Another Example:** Searching for a value that includes a comma:
`("Product Name", eq, "Laptop, 15-inch")`

**Example:** Using single quotes for a value:
`(City, eq, 'New York')`

### Usage on v2 API

The v3 `where` clause can also be utilized when using the v2 API by prepending the `where` clause with an `@` sign. This allows you to leverage the advanced capabilities of the v3 `where` clause even in v2 API calls.

**Example:** Using a v3 `where` clause to check for non-blank titles in a v2 API call:
`@("Title", not, blank)`

**Another Example:** Combining multiple conditions with special characters in a v2 API call:
`@("Description", like, "High-performance, water-resistant")`


# Upload via API
URL: /docs/product-docs/developer-resources/rest-apis/upload-via-api

Upload files locally present or from public remote URL via API

Sample code to upload files via API is listed below.
Assumes `http://localhost:8080/` as the base URL for the API calls.

## Upload local file (single)

### Javascript

```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

(async () => {
    // API Token for uploading the file
    // Reference : https://docs.nocodb.com/account-settings/api-tokens/#create-api-token
    const apiToken = 'YOUR_API_TOKEN';

    // Base URL for the API
    const baseURL = 'https://app.nocodb.com';

    // Table ID
    // Table ID of your table can be retrieved from the URL (OR) by using table context menu
    const tableID = 'YOUR_TABLE_ID';

    // Read the image file
    const photoStream = fs.createReadStream('./photo.png');

    // Create form data
    const formData = new FormData();
    formData.append('file', photoStream);

    // Define headers for uploading the file
    const uploadHeaders = {
        'xc-token': apiToken,
        ...formData.getHeaders(),
    };

    // Upload the file
    const uploadResponse = await axios.post(`${baseURL}/api/v2/storage/upload`, formData, {
        headers: uploadHeaders,
    });

    // Create a new row in the database
    const response = await axios.post(`${baseURL}/api/v2/tables/${tableID}/records`, {
        // Example field data
        "Title": "New Name",
        // Pass the uploaded file data; file is field name here & its type is "Attachment"
        "file": uploadResponse.data,
    }, {
        headers: {
            'xc-token': apiToken,
            'Content-Type': 'application/json',
        },
    });
})().catch(err => {
    console.log(err);
});

```

### Bash

```bash
#!/bin/bash

# Required configuration
API_TOKEN="YOUR_API_TOKEN"
BASE_URL="https://app.nocodb.com"
TABLE_ID="YOUR_TABLE_ID"       # e.g., m7wp2q8n4d9w4kp
FILE_PATH="./upload/photo.png"             # Path to file to upload
FIELD_NAME="File"                   # Name of attachment field
TITLE_FIELD="Title"                 # Optional: a text field
TITLE_VALUE="New Name"              # Optional: text value

# Step 1: Upload the file
echo "Uploading file..."
UPLOAD_RESPONSE=$(curl -s -X POST "${BASE_URL}/api/v2/storage/upload" \
  -H "xc-token: ${API_TOKEN}" \
  -F "file=@${FILE_PATH}")

echo "Upload response: $UPLOAD_RESPONSE"

# Step 2: Create the record with uploaded file
echo "Creating record..."

CREATE_RESPONSE=$(curl -s -X POST "${BASE_URL}/api/v2/tables/${TABLE_ID}/records" \
  -H "xc-token: ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"${TITLE_FIELD}\": \"${TITLE_VALUE}\",
    \"${FIELD_NAME}\": ${UPLOAD_RESPONSE}
  }")

echo "Create response: $CREATE_RESPONSE"
```

📝 **Instructions**

1. Save the file as `upload-and-insert.sh`
2. Make it executable:

```bash
chmod +x upload-and-insert.sh
```

3. Update the following variables:

* `API_TOKEN`
* `TABLE_ID`
* `FILE_PATH`
* Field names (`file`, `Title`, etc.)

4. Run the script:

```bash
./upload-and-insert.sh
```

### Typescript

```typescript
import axios from 'axios';
import FormData from 'form-data';
import fs from 'fs';
import path from 'path';

const uploadAndInsert = async (): Promise<void> => {
    const apiToken = 'YOUR_API_TOKEN'; // Replace with your actual API token
    const baseURL = 'https://app.nocodb.com';
    const tableID = 'YOUR_TABLE_ID'; // Replace with your actual table ID
    const filePath = path.resolve('../uploads/photo.png');

    const photoStream = fs.createReadStream(filePath);
    const formData = new FormData();
    formData.append('file', photoStream);

    const uploadHeaders = {
        'xc-token': apiToken,
        ...formData.getHeaders(),
    };

    try {
        const uploadResponse = await axios.post(`${baseURL}/api/v2/storage/upload`, formData, {
            headers: uploadHeaders,
        });

        const uploadedFileData = uploadResponse.data;

        const recordResponse = await axios.post(`${baseURL}/api/v2/tables/${tableID}/records`, {
            Title: 'New Name',
            file: uploadedFileData,
        }, {
            headers: {
                'xc-token': apiToken,
                'Content-Type': 'application/json',
            },
        });

        console.log('Record created:', recordResponse.data);
    } catch (error) {
        console.error('Error occurred:', error);
    }
};

// Invoke properly
(async () => {
    await uploadAndInsert();
})();

```

📝 **Instructions**

Install required packages:

```bash
npm install axios form-data @types/form-data
```

If using Node.js with TypeScript, also install:

```bash
npm install --save-dev @types/node
```

***

* Make sure your TypeScript `tsconfig.json` includes `"esModuleInterop": true` to support default imports from CommonJS libraries like `axios`, `form-data`, and `fs`.

### Python

```python
import requests

# Configuration
API_TOKEN = "YOUR_API_TOKEN"
BASE_URL = "https://app.nocodb.com"
TABLE_ID = "YOUR_TABLE_ID"
FILE_PATH = "./photo.png"

# Step 1: Upload the file
with open(FILE_PATH, 'rb') as file:
    files = {
        'file': file
    }
    headers = {
        'xc-token': API_TOKEN
    }

    print("Uploading file...")
    upload_response = requests.post(
        f"{BASE_URL}/api/v2/storage/upload",
        headers=headers,
        files=files
    )

    if upload_response.status_code != 200:
        print("Upload failed:", upload_response.text)
        exit(1)

    uploaded_file_data = upload_response.json()
    print("Upload response:", uploaded_file_data)

# Step 2: Insert a new record with uploaded file
record_payload = {
    "Title": "New Name",   # adjust field names as needed
    "File": uploaded_file_data  # must match the name of your attachment field
}

headers = {
    'xc-token': API_TOKEN,
    'Content-Type': 'application/json'
}

print("Creating record...")
record_response = requests.post(
    f"{BASE_URL}/api/v2/tables/{TABLE_ID}/records",
    headers=headers,
    json=record_payload
)

if record_response.status_code != 200:
    print("Record creation failed:", record_response.text)
else:
    print("Record created:", record_response.json())
```

📝 **Instructions**

Make sure you have `requests` installed:

```bash
pip install requests
```

### Ruby

```ruby
require 'net/http'
require 'uri'
require 'json'
require 'mime/types'

# Configuration
API_TOKEN = 'YOUR_API_TOKEN'
BASE_URL = 'https://app.nocodb.com'
TABLE_ID = 'YOUR_TABLE_ID'
FILE_PATH = './photo.png'

# Step 1: Upload the file
uri = URI("#{BASE_URL}/api/v2/storage/upload")

file = File.open(FILE_PATH)
mime_type = MIME::Types.type_for(FILE_PATH).first.to_s

request = Net::HTTP::Post::Multipart.new uri.path,
  'file' => UploadIO.new(file, mime_type, File.basename(file))

request['xc-token'] = API_TOKEN

puts "Uploading file..."
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(request)

if response.code.to_i != 200
  puts "Upload failed: #{response.body}"
  exit(1)
end

uploaded_file_data = JSON.parse(response.body)
puts "Upload response: #{uploaded_file_data}"

# Step 2: Insert a record
uri = URI("#{BASE_URL}/api/v2/tables/#{TABLE_ID}/records")

payload = {
  "Title" => "New Name",
  "file" => uploaded_file_data
}.to_json

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['xc-token'] = API_TOKEN
request.body = payload

puts "Creating record..."
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

if response.code.to_i != 200
  puts "Record creation failed: #{response.body}"
else
  puts "Record created: #{response.body}"
end
```

📝 **Instructions**

You’ll need the `multipart-post` and `mime-types` gems:

```bash
gem install multipart-post mime-types
```

Add at the top if needed:

```ruby
require 'net/http/post/multipart'
```

### JAVA

```java
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.File;
import java.io.IOException;
import java.util.*;

public class NocoDBUploaderOkHttp {

    private static final String API_TOKEN = "YOUR_API_TOKEN";
    private static final String BASE_URL = "https://app.nocodb.com";
    private static final String TABLE_ID = "YOUR_TABLE_ID";
    private static final String FILE_PATH = "./photo.png";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        ObjectMapper mapper = new ObjectMapper();

        // Step 1: Upload file
        File file = new File(FILE_PATH);
        String mimeType = okhttp3.internal.http.HttpDate.format(new Date()); // fallback if type is unknown

        RequestBody fileBody = RequestBody.create(file, MediaType.parse(Files.probeContentType(file.toPath())));
        MultipartBody multipartBody = new MultipartBody.Builder()
                .setType(MultipartBody.FORM)
                .addFormDataPart("file", file.getName(), fileBody)
                .build();

        Request uploadRequest = new Request.Builder()
                .url(BASE_URL + "/api/v2/storage/upload")
                .header("xc-token", API_TOKEN)
                .post(multipartBody)
                .build();

        System.out.println("Uploading file...");
        try (Response response = client.newCall(uploadRequest).execute()) {
            if (!response.isSuccessful()) {
                System.err.println("Upload failed: " + response.body().string());
                return;
            }

            String uploadResponseStr = response.body().string();
            System.out.println("Upload response: " + uploadResponseStr);

            // Step 2: Create record
            List<Object> fileData = mapper.readValue(uploadResponseStr, List.class);
            Map<String, Object> record = new HashMap<>();
            record.put("Title", "New Name");
            record.put("file", fileData); // field name in your NocoDB table

            RequestBody recordBody = RequestBody.create(
                    mapper.writeValueAsString(record),
                    MediaType.parse("application/json")
            );

            Request recordRequest = new Request.Builder()
                    .url(BASE_URL + "/api/v2/tables/" + TABLE_ID + "/records")
                    .header("xc-token", API_TOKEN)
                    .header("Content-Type", "application/json")
                    .post(recordBody)
                    .build();

            System.out.println("Creating record...");
            try (Response recordResponse = client.newCall(recordRequest).execute()) {
                if (!recordResponse.isSuccessful()) {
                    System.err.println("Record creation failed: " + recordResponse.body().string());
                } else {
                    System.out.println("Record created: " + recordResponse.body().string());
                }
            }
        }
    }
}
```

## Upload local files (batch)

### Javascript

```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const path = require('path');

(async () => {
    const apiToken = 'YOUR_API_TOKEN';
    const baseURL = 'https://app.nocodb.com';
    const tableID = 'YOUR_TABLE_ID';

    // List of file paths to upload
    const filesToUpload = [
        './uploads/photo.png',
        './uploads/photo2.png',
        './uploads/photo3.png'
    ];

    const uploadedFiles = [];

    // Upload each file one by one
    for (const filePath of filesToUpload) {
        const fileStream = fs.createReadStream(filePath);
        const formData = new FormData();
        formData.append('file', fileStream);

        const uploadHeaders = {
            'xc-token': apiToken,
            ...formData.getHeaders(),
        };

        try {
            const uploadResponse = await axios.post(`${baseURL}/api/v2/storage/upload`, formData, {
                headers: uploadHeaders,
            });

            // Add the uploaded file metadata to the array
            uploadedFiles.push(...uploadResponse.data); // .data is an array
        } catch (err) {
            console.error(`Failed to upload file ${filePath}:`, err.response?.data || err.message);
        }
    }

    // Insert the record with all uploaded files
    try {
        const response = await axios.post(`${baseURL}/api/v2/tables/${tableID}/records`, {
            Title: "New Name",
            File: uploadedFiles, // Pass multiple files as array
        }, {
            headers: {
                'xc-token': apiToken,
                'Content-Type': 'application/json',
            },
        });

        console.log("Record created:", response.data);
    } catch (err) {
        console.error("Failed to create record:", err.response?.data || err.message);
    }
})();

```


# Bitbucket
URL: /docs/product-docs/noco-sync/on-premise-oauth/bitbucket

Instructions for setting up Bitbucket authentication integration for NocoDB

<Callout type="info">
  This page is intended for on-premise enterprise NocoDB installations.
</Callout>

This document provides instructions for setting up the Bitbucket authentication integration for NocoDB.

## Environment Variables

To enable OAuth2 authentication with Bitbucket, you need to configure the following environment variables.

***

## Step 1: Create a Bitbucket OAuth Consumer

1. Log in to your Bitbucket account
2. Navigate to Bitbucket Administration **Workspace settings → OAuth consumers**

* (Bitbucket → left sidebar → click your workspace → **Workspace settings** → **OAuth consumers**)

3. Click on **“Add consumer”**
4. Fill out the form:

* **Name**: Your application name (e.g., "NocoDB")

* **Description**: Brief description of your application

* **Callback URL**:
  `https://your-nocodb-instance.com/`

* **Permissions**: Enable:

* **Repositories**: Read & Write

* **Pull requests**: Read & Write

* **Issues**: Read & Write

* **Account**: Read

5. Click **Save**

***

## Step 2: Get Client ID and Client Secret

After creating your OAuth consumer:

1. Bitbucket will display:

* **Key** → Client ID
* **Secret** → Client Secret

2. Copy both values (the Secret is shown **only once**)
3. Store them safely for configuration

***

## Step 3: Set Environment Variables

Configure your NocoDB instance with:

```
INTEGRATION_AUTH_BITBUCKET_CLIENT_ID=your_bitbucket_client_id
INTEGRATION_AUTH_BITBUCKET_CLIENT_SECRET=your_bitbucket_client_secret
INTEGRATION_AUTH_BITBUCKET_REDIRECT_URI=your_redirect_uri
```

Where:

* `your_bitbucket_client_id` → The **Key (Client ID)** from Bitbucket
* `your_bitbucket_client_secret` → The **Secret (Client Secret)**
* `your_redirect_uri` → The callback URL used in the OAuth consumer
  (e.g., `https://your-nocodb-instance.com/`)

***

## OAuth Scopes Requested

The integration will request these Bitbucket scopes:

* `repository`
* `repository:write`
* `pullrequest`
* `pullrequest:write`
* `issue`
* `issue:write`
* `account`

These permissions allow NocoDB to read/write repositories, issues, and pull requests as needed.


# GitHub
URL: /docs/product-docs/noco-sync/on-premise-oauth/github

Instructions for setting up GitHub authentication integration for NocoDB

<Callout type="info">
  This page is intended for on-premise enterprise NocoDB installations.
</Callout>

This document provides instructions for setting up the GitHub authentication integration for NocoDB.

## Environment Variables

To enable OAuth2 authentication with GitHub, you need to set up the following environment variables:

### Step 1: Create a GitHub OAuth App

1. Log in to your GitHub account
2. Navigate to Settings > Developer settings > OAuth Apps
3. Click on "New OAuth App"
4. Fill out the form:

* **Application name**: Your application name (e.g., "NocoDB")
* **Homepage URL**: Your application's homepage URL
* **Application description**: (Optional) Brief description of your app
* **Authorization callback URL**: The URL where GitHub will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
* **Icon**: (Optional) Upload an icon for your application

5. Click "Register application"

### Step 2: Get Client ID and Client Secret

After registering your OAuth App, you'll be provided with:

* Client ID
* Client Secret (click "Generate a new client secret" to create one)

### Step 3: Set Environment Variables

Configure your NocoDB instance with the following environment variables:

```
INTEGRATION_AUTH_GITHUB_CLIENT_ID=your_github_client_id
INTEGRATION_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
INTEGRATION_AUTH_GITHUB_REDIRECT_URI=your_redirect_uri
```

Where:

* `your_github_client_id`: The Client ID from your GitHub OAuth App
* `your_github_client_secret`: The Client Secret from your GitHub OAuth App
* `your_redirect_uri`: The callback URL you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/api/v1/integrations/auth/github/callback`)

## OAuth Scopes

This integration requests the following GitHub scopes:

* `read:user`: Read-only access to user profile data
* `repo`: Full control of repositories


# GitLab
URL: /docs/product-docs/noco-sync/on-premise-oauth/gitlab

Instructions for setting up GitLab authentication integration for NocoDB

<Callout type="info">
  This page is intended for on-premise enterprise NocoDB installations.
</Callout>

This document provides instructions for setting up the GitLab authentication integration for NocoDB.

## Environment Variables

To enable OAuth2 authentication with GitLab, you need to set up the following environment variables:

### Step 1: Create a GitLab OAuth Application

1. Log in to your GitLab account
2. Navigate to User Settings > Applications (or for organization-wide application, go to your Group settings > Applications)
3. Fill out the form:

* **Name**: Your application name (e.g., "NocoDB")
* **Redirect URI**: The URL where GitLab will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
* **Scopes**: Select the following scopes:
* `api` (API access)
* `read_user` (Read user information)

4. Click "Save application"

### Step 2: Get Application ID and Secret

After creating your OAuth App, you'll be provided with:

* Application ID (Client ID)
* Secret (Client Secret)

### Step 3: Set Environment Variables

Configure your NocoDB instance with the following environment variables:

```
INTEGRATION_AUTH_GITLAB_CLIENT_ID=your_gitlab_client_id
INTEGRATION_AUTH_GITLAB_CLIENT_SECRET=your_gitlab_client_secret
INTEGRATION_AUTH_GITLAB_REDIRECT_URI=your_redirect_uri
```

Where:

* `your_gitlab_client_id`: The Application ID from your GitLab OAuth App
* `your_gitlab_client_secret`: The Secret from your GitLab OAuth App
* `your_redirect_uri`: The callback URL you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/`)

## OAuth Scopes

This integration requests the following GitLab scopes:

* `api`: Access to the GitLab API
* `read_user`: Read-only access to user profile data


# Linear
URL: /docs/product-docs/noco-sync/on-premise-oauth/linear

Instructions for setting up Linear authentication integration for NocoDB

<Callout type="info">
  This page is intended for on-premise enterprise NocoDB installations.
</Callout>

This document provides instructions for setting up the Linear authentication integration for NocoDB.

## Environment Variables

To enable OAuth2 authentication with Linear, you need to set up the following environment variables:

### Step 1: Create a Linear OAuth App

1. Log in to your Linear account
2. Navigate to Settings > API > OAuth applications (or go directly to [https://linear.app/settings/api/applications](https://linear.app/settings/api/applications))
3. Click on "New OAuth application"
4. Fill out the form:

* **Application Name**: Your application name (e.g., "NocoDB")
* **Developer Name**: The person or company developing this application (e.g., "NocoDB")
* **Developer URL**: Homepage or documentation for your application (e.g., "[https://nocodb.com/](https://nocodb.com/)")
* **Description**: Brief description of your application
* **Callback URIs**: The URL where Linear will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
* **Enable “Public”**: Turn ON to allow all Linear workspaces to authorize
* **Icon**: (Optional) Upload an icon for your application

5. Click "Create"

### Step 2: Get Client ID and Client Secret

After creating your OAuth application:

1. You'll be shown the Client ID and Client Secret
2. Copy these values as they will be needed for configuration

### Step 3: Set Environment Variables

Configure your NocoDB instance with the following environment variables:

```
INTEGRATION_AUTH_LINEAR_CLIENT_ID=your_linear_client_id
INTEGRATION_AUTH_LINEAR_CLIENT_SECRET=your_linear_client_secret
INTEGRATION_AUTH_LINEAR_REDIRECT_URI=your_redirect_uri
```

Where:

* `your_linear_client_id`: The Client ID from your Linear OAuth App
* `your_linear_client_secret`: The Client Secret from your Linear OAuth App
* `your_redirect_uri`: The redirect URI you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/api/v1/integrations/auth/linear/callback`)

## API Key Authentication

If you're using API Key authentication instead of OAuth:

1. Log in to your Linear account
2. Navigate to Settings > API > Personal API keys (or go directly to [https://linear.app/settings/api](https://linear.app/settings/api))
3. Under "Personal API keys", enter a name for your key
4. Click "Create key"
5. Copy the generated API key (you won't be able to see it again)

You'll need to provide this API key when configuring the integration with the API Key authentication method.

## OAuth Scopes

This integration requests the following Linear scopes:

* `read`: Read access to workspace data
* `write`: Write access to workspace data

These scopes allow the integration to read and modify issues, projects, and other data in your Linear workspace.


# Calendar
URL: /docs/product-docs/views/view-types/calendar

Learn how to work with Calendar view in NocoDB.





















Calendar View allows you to visualise your data in a calendar format. You can easily rearrange the records by dragging and dropping them to different dates. You can also visualise the records in a day, week, month, or year format. This section will cover all the operations that can be performed on the Calendar view.

<img alt="1010-2 Calendar" src={__img0} placeholder="blur" />

## Calendar View Actions

1. [Create a New Calendar View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Calendar View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Calendar View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Calendar View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Calendar View](/docs/product-docs/views/share-view)
6. [Lock Calendar View for Edits](/docs/product-docs/views#view-permission-types)

## Timescales

For Calendar view, NocoDB supports 4 different timescales:

### Day

In day view, you can see the records for a single day. For records with DateTime fields, you can drag and drop the records to different timeslots within the day.

<img alt="day-view" src={__img1} placeholder="blur" />

### Week

In week view, you can see the records for a single week. You can drag and drop the records to different days within the week. For records with DateTime fields, you can drag and drop the records to different timeslots within the day.

<img alt="week-view" src={__img2} placeholder="blur" />

### Month

In month view, you can see the records for an entire month. You can drag and drop the records to different days within the month.

<img alt="month-view" src={__img3} placeholder="blur" />

### Year

Year view allows you to see a birds-eye view of the records for the entire year. Blue badge on the date indicates that there are records on that date. You can click on the date to see the records for that date.

<img alt="year-view" src={__img4} placeholder="blur" />

## Calendar View Operations

### Customize Record Label

You can customize the record label that appears on the calendar. To do this, click on the `Fields` menu on the toolbar. In the dropdown that appears

* Use toggle to enable or disable the fields that you want to display on the calendar.
* Use reorder to change the order of the fields that you want to display on the calendar.
* Use format menu options to customize the display of the fields on the calendar. You can choose to format the field as Bold, Italicise or Underline.

<img alt="fields-menu" src={__img5} placeholder="blur" />

### Add New Records

To add a new record to the calendar, click on the `+` icon to the bottom right of the calendar. Alternatively, you can also double-click on the white space in the calendar to add a new record. In the form that appears, fill in the details and click on `Save`.

### Expand Record Details

To view the details of a record, click on the record. This will expand the record and show all the details of the record.

### Edit Record Details

Use drag and drop to move the record to a different date or time. To edit any other details of a record, click on the record to expand it. Edit the details of the record. Make the necessary changes and click on `Save`.

### Delete Record

To delete a record, click on the record to expand it. Click on the `Delete` button from the record context menu. Confirm the deletion by clicking on `Delete` in the confirmation dialog.

## Configuring Date Range

<Callout type="info">The date range for the calendar view is supported only in the Cloud version of NocoDB</Callout>
<img alt="date-range" src={__img6} placeholder="blur" />

In NocoDB, you can configure the date range display in the calendar view by selecting Start and End date fields. To specify the date range while setting up the calendar view, click on `+ End Date` and choose the desired date field to serve as the end date. This displays the records in the calendar view as a range block between the start and end date.

<img alt="date-range" src={__img7} placeholder="blur" />

<img alt="date-range" src={__img8} placeholder="blur" />

<Callout type="info">
  The date range configuration is currently supported only for the Date field type. Support for DateTime field type will be added in the future
</Callout>

Alternatively, you can also configure the date range display functionality during view creation. To do this, click on `+ Add Field` and choose the desired date field to serve as the end date.

<img alt="date-range" src={__img9} placeholder="blur" />

Once the date range display is enabled, you can drag drop the records to change the start and end dates of the records. You can also resize the records to change the duration of the records.

## Other toolbar operations

1. [Apply Filters to Display Specific Records on the Calendar](/docs/product-docs/table-operations/filter)
2. [Sort Records on the Calendar by One or More Criteria](/docs/product-docs/table-operations/sort)
3. [Perform Quick Searches for Specific Data Within Fields](/docs/product-docs/table-operations/search)
4. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)


# Form
URL: /docs/product-docs/views/view-types/form

Learn how to create, import, and manage forms in NocoDB.

















































Form View allows you to arrange fields in a form to input data.

<img alt="1010-2 Form" src={__img0} placeholder="blur" />

## Form View Builder

Form view builder layout can be divided into 4 sections:

1. **Form Area** - This is the area where fields added to the form are listed. This area also acts as a preview of the form.
2. **Form Fields** - This area lists all the fields available in the table. You can drag and drop fields for re-ordering and toggle the `hide` switch to remove fields from the form.
3. **Appearance Settings** - This is the area where you can configure the form view appearance settings like Background Color, Banner & Branding.
4. **Post Form Submission Settings** - This is the area where you can configure the form view to perform various actions after a form is submitted.

<img alt="Form Builder" src={__img1} placeholder="blur" />

## Form View Actions

1. [Create a New Form View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Form View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Form View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Form View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Form View](/docs/product-docs/views/share-view)
6. [Lock Form View for Edits](/docs/product-docs/views#view-permission-types)

## Form View Operations

### Add Form Title & Description

In the **Form View** area, click on in input boxes provided for **Title** & **Description** to add/update title & description to the form.

<Callout type="info">
  Formatting options are supported for the description field. You can also use Markdown to format the text
</Callout>

<img alt="Form Title & Description" src={__img2} placeholder="blur" />

### Add/Remove Fields

To add/remove a field

* Use toggle switch next to the field name in the **Form Fields** to add/remove a field from the form.

### Form Appearance Settings

<img alt="Form appearance" src={__img3} placeholder="blur" />

#### Change Background Color

To change the background color of the form, select the required color from the color picker in the **Appearance Settings** panel.

#### Hide Branding

To hide NocoDB branding from the form, toggle the `Hide NocoDB Branding` switch in the **Appearance Settings** panel.

<Callout type="info">
  This feature is available only in the paid plans in both Cloud & Self-hosted
</Callout>

#### Hide Form Banner

To hide the form banner, toggle the `Hide Banner` switch in the **Appearance Settings** panel.

#### Customize Submit Button ☁

You can customize the text displayed on the form submit button by enabling the `Customize Submit button` toggle in the **Appearance Settings** panel. Once enabled, enter the desired label in the text input field (up to 50 characters). The default button label is "Submit".

<img alt="Customize Submit Button" src={__img4} placeholder="blur" />

<Callout type="info">
  This feature is available on **Plus** plan and above in Cloud, and with **Enterprise** license in Self-hosted. It is not available in the open-source version.
</Callout>

### Rearrange Fields Within the Form

To rearrange fields within the form, drag and drop the field to the required position. This can be done in both the **Form Area** and **Form Fields** panel.

### Add a New Field to the Table

To add a new field to the table,

* Click on the `+ Add field` in the **Form Fields** panel
* Select the field name & type from the dropdown.
* Click on `Save Field`

<img alt="Add Field" src={__img5} placeholder="blur" />

### Form Scheduling ☁

Form scheduling allows you to control when a shared form accepts responses by setting a **Start date** and **Expiration date**. This is useful for time-limited surveys, event registrations, or any form that should only be available during a specific window.

<Callout type="info">
  This feature is available on 

  **Plus**

   plan and above in Cloud, and with 

  **Enterprise**

   license in Self-hosted.
</Callout>

To enable form scheduling:

1. Open the form view builder.
2. In the right sidebar, toggle the **Form scheduling** switch to enable it.
3. Set the **Start date** — the date and time when the form will begin accepting responses.
4. Set the **Expiration date** — the date and time when the form will stop accepting responses.
5. Optionally, toggle **Show expiry countdown** to display a countdown timer on the shared form.

<img alt="Form Scheduling" src={__img6} placeholder="blur" />

<Callout type="info">
  Both start date and expiration date are optional. You can set either one or both. The expiration date must be after the start date if both are set.
</Callout>

#### Builder Preview

When the form is outside the scheduled window, the form builder displays an informational banner. If the start date is in the future, the banner indicates the form is not yet open along with the scheduled start date. Similarly, if the form has passed its expiration date, the banner indicates the form is no longer accepting responses.

<img alt="Form Not Yet Open - Builder" src={__img7} placeholder="blur" />

#### Shared Form View

When a respondent accesses the shared form outside the scheduled window, the form displays a message instead of the form fields:

* **Before start date**: A **"This form is not yet open"** message is shown along with a live countdown timer showing the days, hours, minutes, and seconds remaining until the form opens. The form automatically becomes available when the countdown reaches zero.

<img alt="Form Not Yet Open" src={__img8} placeholder="blur" />

* **After expiration date**: A **"This form is no longer accepting responses"** message is shown indicating that the form has been closed.

<img alt="Form Expired" src={__img9} placeholder="blur" />

#### Show Expiry Countdown

When enabled, a countdown timer is displayed on the shared form showing the time remaining until the form expires. Even if this option is disabled, the countdown will automatically appear when less than 10 minutes remain before expiration.

### Post Form Submission Settings

NocoDB allows you to configure the form view to perform various actions after a form is submitted. These actions can be configured in the **Post Form Submission Settings** panel.

1. **Show `Submit Another Form` Button**: This option when enabled, will display a `Submit Another Form` button after the form is submitted.
2. **Show a Blank form**: This option when enabled, will display a new blank form 5 seconds after the form is submitted.
3. **Email me**: Enable this option to receive an Email after the form is submitted.
4. **After Submit Message**: You can configure a message to display on successful submission of the form.

<img alt="Form View Settings" src={__img10} placeholder="blur" />

<Callout type="info">
  Formatting options are supported for the 

  `After Submit Message`

   field. You can also use Markdown to format the text
</Callout>

### Redirect URL

To redirect the user to a specific URL after the form is submitted, toggle the `Redirect URL` switch in the **Post Form Submission Settings** panel and enter the URL in the input box provided. The browser will redirect to the specified URL after the form is submitted instead of showing the default success message & "Submit Another Form" button.

<img alt="Redirect URL" src={__img11} placeholder="blur" />

You can use **`{record_id}`** in the URL as a query parameter to display the newly created record as expanded form (provided user submitting form has access to the base). For example, `https://app.nocodb.com/#/<workspaceId>/<baseId>/<tableId>?rowId={record_id}`

You can also use **`{record_id}`** in the URL as query parameter to pass the record ID of the newly created record to link in subsequent form. For example, if you want a link field in another table to be populated based on the record just created, you can use the shared form URL with link field prefilled appropriately `https://<shared form URL>?<link field>={record_id}`

<Callout type="info">
  Use of Redirect URL is mutually exclusive with the 

  `After Submit missage`

  , 

  `Show a Blank form`

   and 

  `Submit Another Form`

   options. If Redirect URL is enabled, the form will redirect to the specified URL after submission
</Callout>

## Field configuration

To change the field label displayed on the form & add help-text, click on the required field in the **Form Area** and on the right side configuration panel, configure

1. **Label** `Optional` : Defaults to the field name. This doesn't affect the field name in the table.
2. **Help Text** `Optional`
3. **Required** : Toggle to mark the field as required

<Callout type="info">
  * Required fields are marked with a red asterisk (\*) in the form.
  * If Checkbox field is marked as required, it has to be checked to submit the form.
</Callout>

<img alt="Field Label & Help Text" src={__img12} placeholder="blur" />

<Callout type="info">
  Formatting options are supported for the 

  `Help Text`

   field. You can also use Markdown to format the text
</Callout>

### Select Field Type

#### Options Layout

For select based field types, you can configure the options layout to be displayed as a `Dropdown` or an inline expanded `List`.

<img alt="Options Layout" src={__img13} placeholder="blur" />

#### Limit Options

Limit the number of options displayed in the dropdown or list. This is useful when dealing with a large number of options, allowing you to restrict the visible choices for the user.

* Use `Hide` button next to the option to hide the option from the dropdown or list.
* Use `Reorder` button associated with a field to reorder the options.

<img alt="Limit options" src={__img14} placeholder="blur" />

## Field Validations ☁

<Callout type="info">
  Field validations are only available in the cloud version of NocoDB
</Callout>

NocoDB allows you to configure input data validations for fields in the form. To configure field validation, click on the required field in the **Form Area**, and in the right configuration panel, configure the desired validations. Supported validations are type-specific and are listed below.

<Callout type="info">
  * Validation rules for fields are only applied when input fields are not empty. Set *Required field* to enforce these validation rules and ensure that the field cannot be left blank.
  * The form cannot be submitted if the validation rules are not met.
</Callout>

### Text-based Field Types

For text-based field types `Single Line Text` `Email` `Phone number` `URL` `Long Text` `Rich Text`, you can configure the following validations:

* **Minimum characters**: Specifies the minimum number of characters required for the field.
* **Maximum characters**: Specifies the maximum number of characters allowed for the field.
* **Starts with**: Allows you to define a prefix that the field value must start with.
* **Ends with**: Allows you to define a suffix that the field value must end with.
* **Contains string**: Allows you to define a substring that the field value must contain.
* **Does not contain string**: Allows you to define a substring that the field value must not contain.
* **Regular Expression**: Allows you to define a regular expression pattern that the field value must match.

For Email field type, you can configure the following additional validations:

* **Validate email**: Ensures that the field value is a valid email address.
* **Accept only work email**: Ensures that the field value is a valid work email address.

For Phone number field type, you can configure the following additional validations:

* **Validate phone number**: Ensures that the field value is a valid phone number.

For URL field type, you can configure the following additional validations:

* **Validate URL**: Ensures that the field value is a valid URL.

***

**Configuration Steps**

1. Click on the required field in the **Form Area**.
2. In the right configuration panel, click on the Settings icon next to `Custom Validations`
3. Click on `Add Validation` to add a new validation rule.
4. `VALIDATOR` Select the type of validation rule to be applied from the dropdown.
5. `VALIDATION VALUE` Enter the value for the validation rule.
6. `WARNING MESSAGE` (Optional) Enter a warning message to be displayed when the validation rule is not met.

<img alt="Text Field Validations" src={__img15} placeholder="blur" />

### Numeric Field Types

For numeric field types `Number` `Currency` `Percentage` `Decimal` `Duration`, you can configure the following validations:

* **Minimum**: Specifies the minimum numeric value allowed for the field.
* **Maximum**: Specifies the maximum numeric value allowed for the field.

<Callout type="info">
  - Value configured can be an integer or a decimal number, positive or negative.
  - Maximum value should be greater than or equal to the minimum value.
  - Value can be left empty to disable the validation.
</Callout>

***

**Configuration Steps**

1. Click on the required field in the **Form Area**.
2. In the right configuration panel, click on the toggle button next to `Limit number to a range`
3. \[Optional] Configure the minimum value allowed for the field.
4. \[Optional] Configure the maximum value allowed for the field.

<img alt="Numeric Field Validations" src={__img16} placeholder="blur" />

### Date-based Field Types

For date-based field types `Date` `Date & Time` `Time` `Year`, you can configure the following validations:

* **Minimum**: Specifies the minimum allowed value for the field.
* **Maximum**: Specifies the maximum allowed value for the field.

<Callout type="info">
  - For both, date & date-time fields, only the date part is considered for validation.
  - Value can be left empty to disable the validation.
</Callout>

***

**Configuration Steps**

1. Click on the required field in the **Form Area**.
2. In the right configuration panel, click on the toggle button next to `Limit date to a range`
3. \[Optional] Configure the minimum value allowed for the field.
4. \[Optional] Configure the maximum value allowed for the field.

<img alt="Date Field Validations" src={__img17} placeholder="blur" />

### Attachment Field Type

For the attachment field type, you can configure the following validations:

* **Limit file types**: Allows you to restrict the file types that can be uploaded by specifying permitted MIME types.
  Example
  * `image/png` Allows only PNGs
  * `application/pdf` Allows PDF documents only
  * `image/*` Allows all images
* **Limit file size**: Specifies the maximum file size allowed for the attachment. Size can be either in KB or MB.
* **Limit number of files**: Specifies the maximum number of files that can be uploaded.

<Callout type="info">
  - MIME types should be separated by a comma. Find MIME types for different file formats [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types).
  - File size limit specified is the maximum size allowed for each file, not the total size of all files.
</Callout>

***

**Configuration Steps**

1. Click on the required field in the **Form Area**.
2. In the `Limit file types` section, enter the permitted MIME types separated by a comma.
3. In the `Limit number of files` section, specify the maximum number of files that can be uploaded.
4. In the `Limit file size` section, specify the maximum allowable file size for the attachment.

<img alt="Attachment Field Validations" src={__img18} placeholder="blur" />

Check out this video for a more detailed explanation with examples:

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/Kltbg_Dn23k?si=u1z5Hk9IuuX4jLcY&start=23" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

## Field "Show On Conditions"

Conditional fields in Form View allow you to control the visibility and behavior of chosen fields based on specific data entered in previous fields. You can dynamically hide or show form fields when certain filter conditions are met. This enables a tailored form experience, displaying only relevant fields based on user input.

Note that, for constructing the condition, you can only use fields that are present in the form & are defined prior to the field for which the condition is being set. This also limits reordering of the fields in the form - reordering of the fields will be allowed as long as the condition requirement above is not broken.

To enable conditional fields in Form View, Open form-view builder & follow the steps below:

1. Select the field for which you want to set the condition.
2. On the right side configuration panel, click on the Settings icon next to `Show On Condition` to open the conditional field settings.
3. Click on `Add Filter` OR `Add Filter Group` to add new condition(s) as required.

<img alt="Show On Condition" src={__img19} placeholder="blur" />

NocoDB suffixes an eye icon next to the field name in the form builder to indicate that the field is conditionally visible.

## Pre-Filling Form Fields

NocoDB offers a convenient feature that allows pre-filling form fields with specific values by setting URL parameters. This functionality enables the creation of custom URLs with desired field values, streamlining data entry and enhancing user experience.

To construct a pre-filled form URL manually, ensure that the URL parameters are appropriately encoded in the following format: `?key1=value1&key2=value2`.

For instance, the URL `https://wh8s5w.noco.to/#/nc/form/66da06-f074-47af-ace7-fde46df55?Status=Qualification&Priority=Very+high` pre-fills the `Status` field with `Qualification` and the `Priority` field with `Very high`.

NocoDB provides an intuitive alternative approach to generate pre-filled URLs through the form builder.

1. Open the form builder and pre-fill the required form fields with the desired values.
2. Click on the `Share` button located in the top right corner.
3. Toggle the `Enable Public Viewing` button to enable sharing.
4. Toggle the `Enable Prefill` button to enable pre-filling.
5. Click on the `Copy Link` button to copy the pre-filled URL.

<img alt="Prefill" src={__img20} placeholder="blur" />

<br />

<img alt="Prefill share" src={__img21} placeholder="blur" />

<Callout type="info">
  * Prefilled fields override the default values if any were set for this field in the table
  * Maximum length of the URL is 8000 characters.
</Callout>

### Pre-fill Modes

1. **Default**: Standard mode. This mode will prefill the form fields with the values set in the shared form URL. Users can edit the prefilled fields in the form. In the image below, the `Number` field is prefilled with the value `1234`, `Currency` field is prefilled with the value `1000` and `Year` field is prefilled with value `2023`.

   <img src="/img/v2/views/form-view/prefill-default.png" alt="Prefill default" width="600" />

2. **Hide prefilled fields**: This mode will prefill the form fields with the values set in the shared form URL but will hide the prefilled fields in the form from the user. In the image below, the `Number` field is prefilled with the value `1234`, `Currency` field is prefilled with the value `1000` and `Year` field is prefilled with value `2023`.

   <img src="/img/v2/views/form-view/prefill-hide.png" alt="Prefill hide" width="600" />

3. **Lock prefilled fields as read-only**: This mode will prefill the form fields with the values set in the shared form URL and will lock the prefilled fields as read-only. In the image below, the `Number` field is prefilled with the value `1234`, `Currency` field is prefilled with the value `1000` and `Year` field is prefilled with value `2023`.

   <img src="/img/v2/views/form-view/prefill-lock.png" alt="Prefill lock" width="600" />

<Callout type="info">
  In any of the modes, the user can still change the prefilled fields by editing the URL
</Callout>

## Survey Form View

NocoDB supports a special type of form view called `Survey Form View`. This view is ideal for creating surveys & questionnaires. This view can be enabled by toggling the `Survey Mode` switch when creating [shared form view](/docs/product-docs/views/share-view#share-form-view-options).

Check out this video to see how you can utilize the Survey Mode:

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/LCHiSmUOHuI?si=V20TEFqYJuY_MIaO&start=11" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

When Survey Mode is enabled,

* Form input fields will be displayed one at a time.
* Users can navigate between fields using the `<` & `>` buttons.

<img alt="Survey Form View" src={__img22} placeholder="blur" />

## Attaching a file from mobile device

To attach a file from mobile device,

* Click on the `Add File(s)` button in attach field
* Sample options could be (varies from device to device)
  * Camera : use this if you wish to take a picture
  * Files : use this if you wish to attach a file from your device

<img alt="Attach file from mobile" src={__img23} placeholder="blur" />

## Related articles

[Grid View](/docs/product-docs/views/view-types/grid)\
[Gallery View](/docs/product-docs/views/view-types/gallery)\
[Kanban View](/docs/product-docs/views/view-types/kanban)


# Gallery
URL: /docs/product-docs/views/view-types/gallery

Learn how to work with gallery view in NocoDB.



Gallery View allows you to display images as thumbnails with other fields just like a gallery. This view type is ideal for viewing images in a gallery-like interface. Like in Gallery, you can also perform various operations on the gallery view, such as sorting, filtering, grouping, and searching. You can also export the data in the gallery view to CSV or Excel format. This section will cover all the operations that can be performed on the gallery view.

<img alt="1010-2 Gallery" src={__img0} placeholder="blur" />

## Gallery View Actions

1. [Create a New Gallery View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Gallery View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Gallery View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Gallery View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Gallery View](/docs/product-docs/views/share-view)
6. [Lock Gallery View for Edits](/docs/product-docs/views#view-permission-types)

## Gallery View Operations

1. [Rearrange Fields Within the Gallery](/docs/product-docs/table-operations/field-operations#rearranging-fields)
2. [Show or Hide Fields Within the Gallery](/docs/product-docs/table-operations/field-operations#show--hide-fields)
3. [Apply Filters to Display Specific Records on the Gallery](/docs/product-docs/table-operations/filter)
4. [Sort Records on the Gallery by One or More Criteria](/docs/product-docs/table-operations/sort)
5. [Perform Quick Searches for Specific Data Within Fields](/docs/product-docs/table-operations/search)
6. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)
7. [Change Cover Image](/docs/product-docs/table-operations/field-operations#change-cover-field)
8. [Show or Hide field Labels on Cards](/docs/product-docs/table-operations/field-operations#hide-field-labels-)

## Gallery View Record Operations

1. **Add a New Record to the Gallery**: Currently it is not possible to insert a new record directly on the gallery view. However, you can add a new record to the table, and it will be displayed on the gallery view.
2. **Edit an Existing Record on the Gallery**: Click on the card on the gallery view to open the record in the expanded record view. You can edit the record in the form view and save it.
3. **Delete a Single Record from the Gallery**: Click on the card on the gallery view to open the record in the expanded record view. You can delete the record in the form view by using the expanded record context menu.
4. **Delete Multiple Records in Bulk from the Gallery**: Currently it is not possible to delete multiple records in bulk directly on the gallery view. However, you can delete multiple records in bulk from the grid view & it will be reflected on the gallery view.

## Related articles

[Grid View](/docs/product-docs/views/view-types/grid)\
[Form View](/docs/product-docs/views/view-types/form)\
[Kanban View](/docs/product-docs/views/view-types/kanban)


# Grid
URL: /docs/product-docs/views/view-types/grid

Learn how to work with grid view in NocoDB.



Grid View, as a default type of view, allows you to display your data in a spreadsheet-like interface using rows and columns. Rows are as referred to as records and columns as fields in NocoDB.

<img alt="1010-2 Grid" src={__img0} placeholder="blur" />

Grid view is the default view type for all tables. This view type is ideal for viewing and editing data in a spreadsheet-like interface. You can also perform various operations on the grid view, such as sorting, filtering, grouping, and searching. You can also export the data in the grid view to CSV or Excel format. This section will cover all the operations that can be performed on the grid view.

## Grid View Actions

1. [Create a New Grid View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Grid View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Grid View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Grid View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Grid View](/docs/product-docs/views/share-view)
6. [Lock Grid View for Edits](/docs/product-docs/views#view-permission-types)

## Grid View Operations

1. [Rearrange Fields Within the Grid](/docs/product-docs/table-operations/field-operations#rearranging-fields)
2. [Show or Hide Fields Within the Grid](/docs/product-docs/table-operations/field-operations#show--hide-fields)
3. [Apply Filters to Display Specific Records on the Grid](/docs/product-docs/table-operations/filter)
4. [Sort Records on the Grid by One or More Criteria](/docs/product-docs/table-operations/sort)
5. [Group Records Horizontally on the Grid](/docs/product-docs/table-operations/group-by)
6. [Search for Specific Data Within Fields](/docs/product-docs/table-operations/search)
7. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)
8. [Adjust Record Height on the Grid](/docs/product-docs/table-operations/row-height)
9. [Customize Field Width](/docs/product-docs/fields/actions-on-field)
10. [Toggle Field Visibility on the Grid](/docs/product-docs/table-operations/field-operations#show--hide-fields)

## Grid View Record Operations

1. [Add a New Record to the Grid](/docs/product-docs/records/create-record)
2. [Edit an Existing Record on the Grid](/docs/product-docs/records/actions-on-record#update-record)
3. [Delete a Single Record from the Grid](/docs/product-docs/records/actions-on-record#delete-record-single)
4. [Delete Multiple Records in Bulk from the Grid](/docs/product-docs/records/actions-on-record#delete-record-bulk)

## Related articles

[Gallery View](/docs/product-docs/views/view-types/gallery)\
[Form View](/docs/product-docs/views/view-types/form)\
[Kanban View](/docs/product-docs/views/view-types/kanban)


# Kanban
URL: /docs/product-docs/views/view-types/kanban

Learn how to work with kanban view in NocoDB.















Kanban View allows you to visualise your data using cards as part of various stacks on the board. You can easily rearrange the cards by dragging and dropping them to different stacks. This section will cover all the operations that can be performed on the Kanban view.

<img alt="1010-2 Kanban" src={__img0} placeholder="blur" />

## Kanban View Actions

1. [Create a New Kanban View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Kanban View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Kanban View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Kanban View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Kanban View](/docs/product-docs/views/share-view)
6. [Lock Kanban View for Edits](/docs/product-docs/views#view-permission-types)

## Kanban View Operations

1. [Rearrange Fields Within the Kanban](/docs/product-docs/table-operations/field-operations#rearranging-fields)
2. [Show or Hide Fields Within the Kanban](/docs/product-docs/table-operations/field-operations#show--hide-fields)
3. [Apply Filters to Display Specific Records on the Kanban](/docs/product-docs/table-operations/filter)
4. [Sort Records on the Kanban by One or More Criteria](/docs/product-docs/table-operations/sort)
5. [Perform Quick Searches for Specific Data Within Fields](/docs/product-docs/table-operations/search)
6. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)
7. [Change Cover Image](/docs/product-docs/table-operations/field-operations#change-cover-field)
8. [Show or Hide field Labels on Cards](/docs/product-docs/table-operations/field-operations#hide-field-labels-)

## Kanban View Stacked-by field Operations

### Change Stacked by Field

You can change the field by which the records are stacked on the kanban view by following the steps below:

1. Click on the `Stacked by` menu in the toolbar.
2. Click on field name that is currently selected as the stacked-by field.
3. From the dropdown, select the new field by which you want to stack the records.

<img alt="Change Stacked by Field" src={__img1} placeholder="blur" />

### Add/modify Stacked-by Field Options

You can add/modify options on the stacked-by single select field by following the steps below:

1. Click on the `Stacked by` menu in the toolbar. Dropdown lists all `Select Options` that are available on this field.
2. Add/modify as required.
3. Click on `Save` to save the changes.

<img alt="Add/modify option on the stacked-by single select field" src={__img2} placeholder="blur" />

### Collapse Stack

To ease the view of the kanban, you can collapse the stack by following the steps below:

1. Click on the dropdown icon on the stack header.
2. Select `Collapse Stack` from the dropdown.
3. `Collapsed Stack` will be displayed as vertical bars on the kanban view as displayed below.

<img alt="Collapse Stack" src={__img3} placeholder="blur" />

### Delete Stack

To delete a stack from the kanban view, follow the steps below:

1. Click on the dropdown icon on the stack header.
2. Select `Delete Stack` from the dropdown.
3. A confirmation dialog will be displayed. Click on `Delete` to delete the stack.

<img alt="Delete Stack" src={__img4} placeholder="blur" />

<img alt="Delete Stack Confirmation" src={__img5} placeholder="blur" />

### Reorder Stacks

You can reorder the stacks on the kanban view by dragging and dropping the stack to the desired position.

## Kanban View Record Operations

### Move Records within Stacks

You can move records within a stack by dragging and dropping the card to the desired position within the stack.

### Add a New Record to the Kanban

On kanban, you can add a new record directly to a particular stack by using `Add Record` button on the stack footer. This opens up an expanded record view where you can enter the data for the new record. Once you save the record, it will be displayed on the kanban view. You can also add a new record to the table, and it will be displayed on the kanban view.

<img alt="Add Record" src={__img6} placeholder="blur" />

### Edit an Existing Record on the Kanban

Click on the card on the kanban view to open the record in the expanded record view. You can edit the record in the expanded record view and save it.

### Delete a Single Record from the Kanban

Right-click on the card to access the context menu and select the `Delete` option.

## Related articles

[Grid View](/docs/product-docs/views/view-types/grid)\
[Kanban View](/docs/product-docs/views/view-types/kanban)\
[Form View](/docs/product-docs/views/view-types/form)


# List
URL: /docs/product-docs/views/view-types/list

Learn how to work with List view in NocoDB.

















<Callout type="info">
  List View is available on the 

  **Business**

   plan and above in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

List View allows you to visualise your data as a hierarchical, multi-level list grouped by linked records. You can define up to three levels of grouping using Has-Many link fields, with each level showing records from a different linked table. Parent records appear as collapsible headers, and child records are displayed underneath them. This section will cover all the operations that can be performed on the List view.

<Callout type="note">
  For external data sources, List View is supported only for PostgreSQL.
</Callout>

<img alt="List View" src={__img0} placeholder="blur" />

## List View Actions

1. [Create a New List View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing List View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a List View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a List View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a List View](/docs/product-docs/views/share-view)
6. [Lock List View for Edits](/docs/product-docs/views#view-permission-types)

## Understanding Levels

List View introduces the concept of **levels** — a hierarchy of linked tables that determines how records are grouped and displayed.

* **Level 1 (Root):** The base table of the view. Its records are the leaf-level items displayed at the bottom of the hierarchy.
* **Level 2 and above:** Parent tables linked to the level below via a Has-Many (HM) relationship. These appear as collapsible group headers above their child records.

For example, if you have three tables — **Organizations**, **Teams**, and **Members** — linked as:

* Organizations → Has Many → Teams
* Teams → Has Many → Members

You can create a List View on the Members table with three levels:

1. **Organizations** (top-level group headers)
2. **Teams** (sub-group headers)
3. **Members** (leaf records)

<Callout type="info">
  Only Has-Many link fields can be used to define levels. Many-to-Many, Belongs-To and One-to-One links are not supported for level grouping.
</Callout>

When only one level is configured, the List View displays records as a flat list without any grouping — similar to a Grid View but with the List View's layout and styling.

## Configuring Levels

To set up or modify the hierarchy levels for a List View:

1. Click on the **Levels** button in the toolbar.
2. The configuration panel shows all current levels, with the root table at the bottom and parent levels above.
3. To add a new level:
   * Click **+ Add Level** at the top.
   * Select the link field that connects the new parent table to the level below.
4. To remove a level, click the delete icon next to it.

Changes are saved automatically.

<img alt="Configure Levels" src={__img1} placeholder="blur" />

<Callout type="info">
  Each table can only appear once in the level hierarchy. The same table cannot be used at multiple levels.
</Callout>

## List View Operations

### Fields per Level

Each level has its own set of visible fields. You can independently control which fields are shown for each level:

1. Click on the **Fields** menu in the toolbar.
2. Use the **Level Selector** tabs to switch between levels.
3. Toggle field visibility and reorder fields for the selected level.

<img alt="Fields per Level" src={__img2} placeholder="blur" />

### Filters per Level

Filters can be applied independently to each level, allowing you to filter records at any depth of the hierarchy:

1. Click on the **Filter** menu in the toolbar.
2. Use the **Level Selector** tabs to choose which level to filter.
3. Add filter conditions — these apply only to records at the selected level.

<img alt="Filters per Level" src={__img3} placeholder="blur" />

### Sorts per Level

Sorts can be applied independently to each level:

1. Click on the **Sort** menu in the toolbar.
2. Use the **Level Selector** tabs to choose which level to sort.
3. Add sort criteria — these apply only to records at the selected level.

<img alt="Sorts per Level" src={__img4} placeholder="blur" />

### Colour

You can colour Level 1 (root) records based on a field value to visually distinguish them in the list:

1. Click on the **Colour** button in the toolbar.
2. Select the field to colour records by.
3. Toggle **Background colour** on or off to control whether the full row background is coloured.
4. To remove colouring, click **Remove colouring**.

<Callout type="info">
  Record colouring applies only to Level 1 records. Parent-level group headers are not coloured.
</Callout>

<img alt="Colour" src={__img5} placeholder="blur" />

### Collapse and Expand Groups

Parent records are displayed as collapsible headers. Click the chevron icon on a parent record to collapse or expand its children.

* **Collapsed parents** hide all nested child records beneath them.
* **Expanded parents** show their child records indented below.
* Collapse state is preserved in the current session and passed to the server for efficient data loading.

### Search

Use the search bar in the toolbar to quickly find specific data within the List View:

1. Click the **Search** icon in the toolbar.
2. Use the **Level Selector** tabs to choose which level to search.
3. Select the field to search by from the dropdown.
4. Enter your search term — results are filtered in real time to show only matching records.

<img alt="Search" src={__img6} placeholder="blur" />

## List View Record Operations

### Add a New Record

Click the **+ Add Record** button that appears below a parent group to add a new record at that level. The record will be pre-linked to the parent record. This opens the expanded record form where you can fill in the details.

### Edit an Existing Record

Click on any cell in a record row to edit it inline. You can modify cell values directly within the list without opening the full record form.

### Expand Record Details

Hover over a record and click the **Open >** button that appears, or click the expand icon, to open the full expanded record view showing all fields and linked records.

<img alt="Expand Record" src={__img7} placeholder="blur" />

## Related articles

[Grid View](/docs/product-docs/views/view-types/grid)
[Gallery View](/docs/product-docs/views/view-types/gallery)
[Kanban View](/docs/product-docs/views/view-types/kanban)
[Calendar View](/docs/product-docs/views/view-types/calendar)


# Map
URL: /docs/product-docs/views/view-types/map

Learn how to work with Map View in NocoDB.











<Callout type="info">
  Map View is available in both the Community Edition and Enterprise Edition.
</Callout>

Map View allows you to visualize your records as markers on an interactive map. Each marker is placed using coordinates stored in a [GeoData](/docs/product-docs/fields/field-types/custom-types/geodata) field. You can click on markers to view or edit record details, and right-click on the map to create new records at a specific location. This section covers all the operations that can be performed on the Map View.

<img alt="Map View" src={__img0} placeholder="blur" />

## Map View Actions

1. [Create a New Map View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Map View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Map View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Map View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Map View](/docs/product-docs/views/share-view)
6. [Lock Map View for Edits](/docs/product-docs/views#view-permission-types)

## Prerequisites

Map View requires at least one **GeoData** field in your table. If your table does not have a GeoData field, you will need to [create one](/docs/product-docs/fields/field-types/custom-types/geodata) before setting up a Map View. The GeoData field stores latitude and longitude coordinates that are used to position markers on the map.

## Mapped By field

The **Mapped By** field determines which GeoData field is used to place markers on the map. Only fields of type `GeoData` are available for selection.

### Change the Mapped By field

1. Click on the `Mapped By` menu in the toolbar.
2. Select a different GeoData field from the dropdown.

<img alt="Mapped By field" src={__img1} placeholder="blur" />

<Callout type="info">
  Records without valid coordinates in the selected GeoData field will not appear on the map.
</Callout>

## Map View operations

1. [Show or Hide Fields Within the Map](/docs/product-docs/table-operations/field-operations#show--hide-fields)
2. [Apply Filters to Display Specific Records on the Map](/docs/product-docs/table-operations/filter)
3. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)

### Marker tooltips

When hovering over a marker, a tooltip is displayed showing a summary of the record. The tooltip includes up to four visible fields along with the coordinates.

<img alt="Marker tooltips" src={__img2} placeholder="blur" />

### Marker clustering

When multiple records are located close together, markers are grouped into clusters. Clusters display the count of records they contain. Zooming in on a cluster expands it to reveal individual markers.

<img alt="Clustering" src={__img3} placeholder="blur" />

### Map navigation

You can navigate the map by dragging to pan and scrolling to zoom. The map remembers your zoom level and position for each view, so your preferred viewport is preserved across sessions.

<Callout type="info">
  Map View displays up to 1,000 records. If your view contains more records, consider applying filters to narrow down the results.
</Callout>

## Map View record operations

### Add a new record

You can add a new record to the map in two ways:

* Click on the `+ Add Row` button to open the expanded record form and enter the data manually.
* **Right-click** on any location on the map to create a new record with the GeoData field automatically populated with the clicked coordinates.

<img alt="Add record" src={__img4} placeholder="blur" />

### Edit an existing record

Click on a marker on the map to open the record in the expanded record view. You can edit the record details and save the changes.

### Delete a record

Click on a marker to open the record in the expanded record view. You can delete the record using the expanded record context menu.

## Shared Map View

When a Map View is [shared publicly](/docs/product-docs/views/share-view), external users can view the map and interact with markers in read-only mode. Clicking a marker in a shared view opens a popup card displaying the visible fields of the record.

## Related articles

* [Grid View](/docs/product-docs/views/view-types/grid)
* [Gallery View](/docs/product-docs/views/view-types/gallery)
* [Kanban View](/docs/product-docs/views/view-types/kanban)
* [Calendar View](/docs/product-docs/views/view-types/calendar)


# Timeline
URL: /docs/product-docs/views/view-types/timeline

Learn how to work with Timeline view in NocoDB.

















<Callout type="info">
  Timeline View is available on the 

  **Business**

   plan and above in NocoDB Cloud and Self-hosted Enterprise editions.
</Callout>

Timeline View allows you to visualize your data as horizontal bars along a time axis. Each record is represented as a bar spanning from its start date to its end date, giving you a clear overview of schedules, project plans, and time-based data. You can drag and drop records to change dates, resize bars to adjust durations, and group records by any field. This section covers all the operations that can be performed on the Timeline view.

<img alt="Month Zoom" src={__img0} placeholder="blur" />

## Timeline View Actions

1. [Create a New Timeline View](/docs/product-docs/views/create-view#create-new-view)
2. [Rename an Existing Timeline View](/docs/product-docs/views/actions-on-view#rename-view)
3. [Duplicate a Timeline View](/docs/product-docs/views/actions-on-view#duplicate-view)
4. [Remove a Timeline View](/docs/product-docs/views/actions-on-view#delete-view)
5. [Share a Timeline View](/docs/product-docs/views/share-view)
6. [Lock Timeline View for Edits](/docs/product-docs/views#view-permission-types)

## Date Field Configuration

When creating a Timeline view, you need to select a **Start Date** field. The following field types can be used as date fields:

* Date
* DateTime
* CreatedTime
* LastModifiedTime

### Adding an End Date

By default, records are displayed as single-day bars using only the start date. To display records as ranges spanning multiple days, you can optionally configure an **End Date** field.

To add an end date:

1. Click on the `Timeline Range` settings in the toolbar.
2. Click `+ Add End Date`.
3. Select the desired date field from the dropdown.

<img alt="Timeline Range Settings" src={__img1} placeholder="blur" />

<Callout type="info">
  Only one date range (start + end) can be configured per Timeline view.
</Callout>

### Records Without Dates

Records that do not have a start date value are excluded from the timeline display. A badge in the toolbar shows the total record count along with how many records are missing dates.

{/* ![Records Without Dates](/img/v2/views/timeline/missing-dates-badge.png) */}

## Zoom Levels

Timeline View supports three zoom levels:

### Day

Shows a single day with full date detail. Useful for viewing records at a granular day-by-day level.

<img alt="Day Zoom" src={__img2} placeholder="blur" />

### Week

Shows seven days (Monday through Sunday) in a single view. Useful for weekly planning and sprint views.

<img alt="Week Zoom" src={__img3} placeholder="blur" />

### Month

Shows all days in a calendar month. Provides a broader overview of records across the month.

<img alt="Month Zoom" src={__img4} placeholder="blur" />

## Navigation

### Time Navigation

* Use the **Previous** and **Next** buttons in the toolbar to navigate backward or forward by one period (day, week, or month).
* Click the **Today** button to jump to the current date.
* Use the **Date Picker** dropdown to navigate directly to a specific date.

<img alt="Timeline Navigation" src={__img5} placeholder="blur" />

### Initial View Setting

You can configure what the timeline shows when first opened:

* **Closest Record to Today** (default): Automatically navigates to the record nearest to today's date.
* **Today**: Always opens on the current date.

This setting is available in the Timeline Range configuration in the toolbar.

### Record Navigation

When a record bar extends beyond the visible area, navigation arrows appear on the bar:

* A **left arrow** appears when the record's start date is clipped (off-screen to the left).
* A **right arrow** appears when the record's end date is clipped (off-screen to the right).

Click on these arrows to navigate to the corresponding date.

## Timeline View Operations

### Customize Record Label

You can customize the fields displayed on record bars. Click the `Fields` menu in the toolbar:

* Toggle fields on or off to control which fields are shown on the bars.
* Reorder fields using drag and drop.
* Apply text formatting (Bold, Italic, Underline) to individual fields.

<img alt="Fields Menu" src={__img6} placeholder="blur" />

### Add New Records

There are two ways to add records in the Timeline view:

**Using the Add Button**
Click the `+` button at the bottom left of the timeline. A new record is created with the start date set to the currently visible date range, and the expanded record form opens for you to fill in details.

**Drag to Create**
Click and drag on an empty area of the timeline grid to create a new record:

1. Click on the starting date and drag to the ending date.
2. A dotted selection rectangle shows the date range being selected.
3. Release to create the record — the expanded form opens with the start and end dates pre-filled.

{/* ![Drag to Create](/img/v2/views/timeline/drag-create.png) */}

<Callout type="info">
  Drag-to-create is available only in flat (non-grouped) layout.
</Callout>

### Expand Record Details

Click on any record bar to open the expanded record form, where you can view and edit all field values.

### Edit Record Dates

**Drag to Move**
Click and hold a record bar for a moment, then drag it to a new date position. Both the start and end dates shift by the same number of days, preserving the record's duration.

**Drag to Resize**
Hover over the left or right edge of a record bar to reveal a resize handle:

* Drag the **left edge** to change the start date.
* Drag the **right edge** to change the end date (only available when an end date field is configured).

<img alt="Drag and Drop" src={__img7} placeholder="blur" />

<Callout type="info">
  Drag-to-move and resize operations support undo/redo.
</Callout>

### Delete Record

Click on a record bar to open the expanded record form. Use the `Delete` option from the record context menu to delete the record.

## Grouping Records

You can group records by one or more fields using the `Group By` option in the toolbar. When grouping is active:

* Records are organized into collapsible groups in the left sidebar.
* Each group displays its own timeline grid with a record count.
* Groups can be expanded or collapsed individually.
* Nested grouping (multiple levels) is supported.

{/* ![Timeline Group By](/img/v2/views/timeline/group-by.png) */}

## Visual Indicators

* **Today's date**: Highlighted with a distinct background color and blue text.
* **Weekends**: Displayed with a light gray background.
* **Record colors**: When [Row Coloring](/docs/product-docs/table-operations/record-colouring) is configured, record bars display the assigned color.
* **Hover**: Hovering over a record bar shows a tooltip with the date range and duration.

## Other Toolbar Operations

1. [Apply Filters to Display Specific Records on the Timeline](/docs/product-docs/table-operations/filter)
2. [Sort Records on the Timeline by One or More Criteria](/docs/product-docs/table-operations/sort)
3. [Perform Quick Searches for Specific Data Within Fields](/docs/product-docs/table-operations/search)
4. [Export Data to CSV or Excel Format](/docs/product-docs/table-operations/download#download-data)
5. [Apply Row Coloring Based on Field Values](/docs/product-docs/table-operations/record-colouring)

## Related articles

[Grid View](/docs/product-docs/views/view-types/grid)
[Gallery View](/docs/product-docs/views/view-types/gallery)
[Kanban View](/docs/product-docs/views/view-types/kanban)
[Calendar View](/docs/product-docs/views/view-types/calendar)


# Actions on base
URL: /docs/product-docs/bases/actions-on-base

Understand the structure, actions, and developer tools available in a base.











## Base context menu

The base context menu can be accessed in two ways:

* **From the workspace Bases tab** — click the **⋮** icon on a base card.
* **From within a base** — click the base name dropdown in the top-left of the sidebar. This menu includes additional options like **MCP Server**, **Rest APIs** (API v2 / API v3), and **Import data**.

<img alt="base context menu" src={__img0} placeholder="blur" />
<img alt="base context menu" src={__img1} placeholder="blur" />

## Rename base

1. Open the [base context menu](#base-context-menu).
2. Select **Rename base**.
3. Edit the name and press **Enter** to save.

## Star base

1. Open the [base context menu](#base-context-menu).
2. Select **Add to starred**.

Starred bases can be filtered using the **Starred** option in the base filter dropdown on the workspace Bases tab.

### Remove a base from starred list

1. Open the [base context menu](#base-context-menu).
2. Select **Remove from starred**.

## Duplicate base

1. Open the [base context menu](#base-context-menu).
2. Select **Duplicate base**.
3. Configure what to include:
   * **Include records** — disable to duplicate schema only, without data.
   * **Include comments** — disable to skip comments.
   * **Include scripts** — disable to skip scripts.
   * **Include dashboards** — disable to skip dashboards.
   * **Include workflows** — disable to skip workflows.
4. Select a **Workspace** to duplicate into (defaults to current workspace).
5. Click **Duplicate Base**.

<img alt="image" src={__img2} placeholder="blur" />

<Callout type="info">
  Cross-base links, audit logs, and integrations will not be duplicated. You will become the owner of the duplicated base. Existing members are not transferred.
</Callout>

## Delete base

Deleting a base permanently removes all its tables, data, and associated content.

<Callout type="warning">
  Only 

  **base owners**

   can delete a base. 

  **This action cannot be undone.**
</Callout>

1. Open the [base context menu](#base-context-menu).
2. Select **Delete base**.
3. Click **Delete Base** to confirm.

<img alt="base delete" src={__img3} placeholder="blur" />

## Find base ID

Each base has a unique ID (prefixed with `p`) visible in the base context menu and in the URL.

Example:

```
https://app.nocodb.com/wa5dveq3/pptsua3fuosby2j
```

In this example, the base ID is `pptsua3fuosby2j`.

## Relations

NocoDB provides a visual diagram of relationships between tables within a base.

1. Open the [base context menu](#base-context-menu).
2. Select **Relations**.

<img alt="base relations" src={__img4} placeholder="blur" />

## REST APIs

NocoDB provides a Swagger UI for each base to interact with its REST API endpoints. Both **API v2** and **API v3** are available.

1. Open the [base context menu](#base-context-menu) from within a base.
2. Hover over **Rest APIs** and select **API v2** or **API v3**.

See [Accessing APIs](/docs/product-docs/developer-resources/rest-apis/accessing-apis) for more details.

## Base settings

Access base settings from the [base context menu](#base-context-menu) → **Settings**, or via **Base Settings** → **General** when inside a base.

Available settings:

* **Show M2M tables** — Show or hide many-to-many junction tables in the sidebar.
* **Show NULL in cells** — Display NULL values in cells to differentiate from empty strings.
* **Show NULL & Empty in Filters** — Enable additional filter options to distinguish NULL from empty string values.


# Base collaboration
URL: /docs/product-docs/bases/base-collaboration

This article explains how to invite members or teams to your base, manage their roles, and remove them when needed.















<Callout type="info">
  A comprehensive guide regarding roles and permissions can be accessed 

  [here](/docs/product-docs/roles-and-permissions)
</Callout>

<Callout type="info">
  Teams feature availability: 

  **Business**

   plan onwards in cloud and On-premise 

  **Enterprise**

   edition
</Callout>

## Invite Members to Base

1. Open the base and go to **Base Settings** → **Invite Members to Base** in the sidebar.
2. Click **Add Members**.
3. Enter one or more email addresses.
4. Select a role — **Commenter**, **Viewer**, **No Access**, or **Inherit**.
5. Click **Invite to Base**.

<Callout type="info">
  You can only assign roles that are at most equal to your own role on the base.
</Callout>

<img alt="image" src={__img0} placeholder="blur" />
<img alt="image" src={__img1} placeholder="blur" />
<img alt="image" src={__img2} placeholder="blur" />

Workspace members inherit the role assigned at the workspace level unless a specific role is set at the base level. You can also invite users directly to a base without broader workspace access — ideal for external partners or temporary contributors.

## Invite Teams to Base ☁

1. Open the base and go to **Base Settings** → **Invite Members to Base** in the sidebar.
2. Click **Add Teams**.
3. Select one or more teams from the dropdown.
4. Choose a role — **Editor**, **Commenter**, **Viewer**, or **No Access**.
5. Click **Add Teams**.

<Callout type="info">
  Teams cannot be assigned the 

  **Owner**

   role at the base level. When a team is invited, all its members inherit the assigned base-level role unless overridden by an individual role.
</Callout>

<img alt="image" src={__img3} placeholder="blur" />
<img alt="image" src={__img4} placeholder="blur" />

To learn more about creating and managing teams, refer to the [Teams documentation](/docs/product-docs/collaboration/teams).

## List Base Members and Teams

The **Invite Members to Base** page displays all users and teams with access to the base, including their role and date joined. Roles inherited from the workspace are labelled **Role inherited from workspace**.

<img alt="image" src={__img5} placeholder="blur" />

## Modify Roles for Members or Teams

1. Click the role dropdown next to the member or team.
2. Select a new role — **Creator**, **Editor**, **Commenter**, or **Viewer**. The change takes effect immediately.

<img alt="image" src={__img6} placeholder="blur" />

<Callout type="info">
  You can only assign roles that are at most equal to your own role on the base.
</Callout>

## Role Precedence

When a user has multiple role assignments through both team and individual access:

* Individual explicit role takes precedence over team-assigned role.
* Base-level roles override workspace-level roles.
* In case of multiple team roles, the **highest** permission applies.

Learn more about [effective role resolution](/docs/product-docs/collaboration/teams#effective-role-resolution).

## Remove or Revoke Base Access

### Deny Access

To block a user or team from accessing the base:

* Click the role dropdown next to the member or team.
* Select **No Access**.

### Revoke Explicit Assignment

To remove a base-level role and fall back to workspace or team inheritance:

* Click the role dropdown next to the member or team.
* Select **Inherit**.

<Callout type="info">
  Use 

  **No Access**

   to explicitly block access. Use 

  **Inherit**

   to remove the base-level assignment and fall back to workspace or team role.
</Callout>


# Create base
URL: /docs/product-docs/bases/create-base

Learn how to create a base in NocoDB.











Click **+ New Base** on the workspace **Bases** tab to see the available options:

* **From Scratch** — Start with an empty base
* **From Template** — Pre-built structures for common use cases
* **Build with AI** — AI-powered base creation from your use case

<img alt="Create base" src={__img0} placeholder="blur" />
<img alt="Create base" src={__img1} placeholder="blur" />

## From Scratch

1. Click **+ New Base** → **From Scratch**.
2. Enter a name for your base.
3. Select a **Base Type**:
   * **Default** — Workspace members can collaborate based on their role.
   * **Private** — Invite-only base. Only you can view and manage its members. Learn more about [Private Base](/docs/product-docs/bases/private-base).
4. Click **Create Base**.

<img alt="Create base" src={__img2} placeholder="blur" />

<Callout type="info">
  Private bases are available on the 

  **Business**

   plan and above.
</Callout>

## From Template

1. Click **+ New Base** → **From Template**.
2. Browse templates by **Departments** (Marketing, Project Management, Supply Chain, Finance & Legal, HR & Recruiting) or **Industries** (Education, Manufacturing, Real Estate, Retail, Transportation).
3. Select a template to preview its structure and click to create.

<img alt="Create base" src={__img3} placeholder="blur" />

## Build with AI

<Callout type="info">
  This feature is available only on NocoDB Cloud. It is not supported in self-hosted or on-premise deployments.
</Callout>

1. Click **+ New Base** → **Build with AI**.
2. Select a use case (e.g., Project Management, CRM, Marketing campaigns) or describe your needs.
3. Review the suggested tables, views, and relationships.
4. Click **Create Base**.

<img alt="Create base" src={__img4} placeholder="blur" />

Learn more about [NocoAI base creation](/docs/product-docs/noco-ai/create-base).

***

<Callout type="info">
  When you create a base, you become its owner. Only base owners can delete a base.
</Callout>

On successful creation, you will be directed to the [Base Dashboard](/docs/product-docs/bases) where you can start adding tables and data.


# Import Airtable to NocoDB
URL: /docs/product-docs/bases/import-base-from-airtable

A complete import of your Airtable base to NocoDB within minutes



















<Callout type="info">
  To proceed, you need a valid Airtable 

  [Personal Access Token](#create-personal-access-token)

   and 

  [Shared Base ID / URL](#retrieve-share-base-id--url)

  .
</Callout>

## Access import modal

There are two ways to open the **Import from Airtable** modal:

**From the base context menu:**

1. Click on the base name in the sidebar to open the context menu.
2. Select **Import data** → **Airtable Base**.

<img alt="import data" src={__img0} placeholder="blur" />

**From the base dashboard:**

1. Click **Import Data** on the base dashboard.
2. Select **Airtable**.

<img alt="import data" src={__img1} placeholder="blur" />

## Configure and import

1. Enter your [Personal Access Token](#create-personal-access-token).
2. Enter your [Shared Base ID / URL](#retrieve-share-base-id--url).
3. Select a **Data Source** (Default or an external connection).
4. Configure [Advanced Settings](#advanced-settings) if needed.
5. Click **Import Base**.

<img alt="import data" src={__img2} placeholder="blur" />

Once the import completes, you'll see the **Airtable Base Imported** confirmation. Click **Show Details** to view the import log, or **Go to base** to start working.

<img alt="import data" src={__img3} placeholder="blur" />
<img alt="import data" src={__img4} placeholder="blur" />

### Advanced settings

* **Import data** — When disabled, only the schema (tables and views) is imported without actual records.
* **Import secondary views** — When disabled, only the primary grid view for each table is imported.
* **Import rollup columns** — Toggle import of Rollup fields.
* **Import lookup columns** — Toggle import of Lookup fields.
* **Import attachment columns** — Toggle import of Attachment fields.
* **Import formula columns** — Formula field import is currently not supported (greyed out).

## Get Airtable Credentials

### Create Personal Access Token

1. Visit the [Airtable Create Tokens](https://airtable.com/create/tokens) page and click **Create token**.
2. Enter a name for your token.
3. Add the required access scope — minimum `data.records:read`.
4. Select the base you want to import.
5. Click **Create token** and copy the generated token.

For more details, see the [Airtable Personal Access Token guide](https://airtable.com/developers/web/guides/personal-access-tokens).

<img alt="image" src={__img5} placeholder="blur" />
<img alt="image" src={__img6} placeholder="blur" />
<img alt="image" src={__img7} placeholder="blur" />

### Retrieve Share Base ID / URL

1. In Airtable, open the **Share** menu for your base.
2. Open the **Share Publicly** tab.
3. Enable **Turn on full base access**.
4. Copy the generated shared base URL.

For more details, see [Airtable's share link guide](https://support.airtable.com/hc/en-us/articles/205752117-Creating-a-base-share-link-or-a-view-share-link#basesharelink).

<img alt="Shared base" src={__img8} placeholder="blur" />


# Bases
URL: /docs/product-docs/bases

Overview of bases in NocoDB and how they help organize data and collaboration.



In NocoDB, a base is the core structure where your data lives. It contains tables, views, forms, dashboards, and more — a complete environment for organizing and collaborating on data. Each base belongs to a specific workspace.

<Callout type="info">
  Creating a new base requires 

  **Creator**

   or 

  **Owner**

   role at the workspace level.
</Callout>

The person who creates a base becomes its **owner**, and a base must always have at least one owner. Ownership can be shared, with multiple owners having full control over base settings and permissions.

## Base-level Permissions

Each base has its own set of members and permissions, independent of workspace-level access. This allows fine-grained control over who can view or edit content within a base. See [Base Collaboration](/docs/product-docs/bases/base-collaboration) for details on managing members, and [Table Permissions](/docs/product-docs/roles-and-permissions/table-permissions) / [Field Permissions](/docs/product-docs/roles-and-permissions/field-permissions) for granular access control.

## Base Dashboard

The base dashboard is the landing page when you open a base. It provides quick access to common data actions.

<img alt="image" src={__img0} placeholder="blur" />

### Data Actions

* **Create New Table** — Start building a table from scratch.
* **Import Data** — Upload from files and external sources.
* **Create Dashboard** — Build dashboards with charts and widgets to visualize data.
* **Sync Data** — Sync with internal or external sources.
* **Connect External Data** — Connect in realtime to external databases like MySQL or PostgreSQL.


# Private Base
URL: /docs/product-docs/bases/private-base

Learn how to configure and manage access to Private Bases in NocoDB.









<Callout type="warning">
   The Private Base feature is available only on the 

  **Business**

   plan and above 
</Callout>

A **Private Base** in NocoDB allows base owners to fully control access at the base level, independently of workspace-level roles. This feature is ideal for projects that require confidentiality, restricted visibility, or selective collaboration within a workspace.

## How Private Base Works

When a base is marked as **private**:

* **Workspace role inheritance is disabled** — users with roles like Owner, Editor, or Viewer at the workspace level will **not** automatically gain access.
* By default, only the **base creator (Owner)** can access the base.
* Access must be **explicitly granted** to other members by assigning a base-specific role (Owner, Creator, Editor, Commenter, or Viewer).

<Callout type="info">
  Members without explicit access will not see the base listed in their workspace
</Callout>

## Creating a Private Base

1. Click **+ New Base** → **From Scratch** on the workspace **Bases** tab.
2. Enter a name for the base.
3. Select **Private** as the **Base Type**.
4. Click **Create Base**.

<img alt="Create base" src={__img0} placeholder="blur" />
<img alt="Create base" src={__img1} placeholder="blur" />
<img alt="Create base" src={__img2} placeholder="blur" />

<Callout type="info">
  Only the base creator will have access by default. Other workspace members, including Workspace Owners, will not see the base unless explicitly added.
</Callout>

<Callout type="info">
  Private bases cannot be shared publicly. All view-sharing (except Form views) is restricted.
</Callout>

## Converting an Existing Base to Private

1. Open the base and go to **Base Settings** → **General** in the sidebar.
2. Under **Base Type**, select **Private**.

<img alt="Convert to Private Base" src={__img3} placeholder="blur" />

<Callout type="info">
  Explicitly configured base-level roles will be retained. Inherited workspace access for other users will be removed.
</Callout>

<Callout type="info">
  If the base or view is currently shared publicly, sharing will be disabled when switching to private.
</Callout>

## Disabling Private Access

1. Open the base and go to **Base Settings** → **General** in the sidebar.
2. Under **Base Type**, select **Default**.

<Callout type="info">
  Workspace-level role inheritance will be re-enabled. Members with workspace roles will regain corresponding access. Explicit base roles remain unchanged.
</Callout>

## Managing Access in a Private Base

Managing user access in a private base follows the same process as any other base. You can invite workspace members and assign them roles explicitly at the base level. Role changes at the workspace level will not affect access to a private base unless the base type itself is set back to default access.

For detailed steps, refer to the [Base Collaboration Guide](/docs/product-docs/bases/base-collaboration).

***


# Share base
URL: /docs/product-docs/bases/share-base

Procedures to share a base & generating embedded iframe













## Enable public access

To share a base, follow the steps below:

1. Navigate to the top right corner and click on the `Share` button.
2. In the Shared base section, toggle the `Enable public access` switch to activate public sharing.
3. A shareable link will be generated. Click the `Copy URL` option to copy it.

<img alt="Share base" src={__img0} placeholder="blur" />

<img alt="Share base" src={__img1} placeholder="blur" />

## Modify Share base

Updating (regenerating) the shared base configuration will invalidate the previously generated link and generate a new one. To do this:

1. Click the `Share` button in the top right corner.
2. Toggle `Enable public access` off to disable sharing.
3. Toggle it on again to reactivate sharing, which will generate a new link.

<img alt="Enable public access" src={__img2} placeholder="blur" />

## Disable Share base

To disable the shared link:

1. Click the `Share` button in the top right corner.
2. Toggle off the `Enable public access` option.

This will deactivate the current share link.

<img alt="Enable public access" src={__img3} placeholder="blur" />

## Custom URL

You can personalize the shared base URL by setting a custom identifier. The custom URL must be unique and should not contain special characters like `/`, `?`, or `#`.

To set a custom URL:

1. Toggle the `Custom URL` option.
2. Enter a custom value in the input field. If the custom URL entered is already in use, you will be prompted to choose a different one.
3. Click `Save` to apply the changes.

<img alt="Custom URL" src={__img4} placeholder="blur" />

<Callout type="info">
  The custom URL is case-sensitive
</Callout>

<Callout type="info">
  Creating or updating a custom URL will not invalidate the previously generated shared base link. Both the default and custom URLs will remain active unless public access is disabled.
</Callout>

## Embeddable Frame

You can embed the shared base into another application using an `HTML IFRAME`.

To generate an embeddable iframe code:

1. Click the `Share` button in the top right corner.
2. In the `Shared base` section, click `<>` to copy the Embeddable IFrame code.

<img alt="Share base iFrame" src={__img5} placeholder="blur" />

Example:

```html
<iframe
    class="nc-embed"
    src="https://app.nocodb.com/#/nc/base/e3bba9df-4fc1-4d11-b7ce-41c4a3ad6810?embed"
    width="100%"
    height="700"
    style="background: transparent; border: 1px solid #ddd"
>
</iframe>
```

Here’s an example of a complete HTML document embedding the base:

```html
<!DOCTYPE html>
<html>
<head>
    <title>Sample iFrame Example</title>
</head>
<body style="height:100vh; margin:0">
<iframe src="http://app.nocodb.com/#/base/035c5207-501a-48b8-8dbe-67742b78323e" width="100%" height="100%" style="border: none;"></iframe>
</body>
</html>
```

***


# Base Snapshots
URL: /docs/product-docs/bases/snapshots

Procedures to create and manage snapshots











Snapshots allow you to create a point-in-time backup of your base. Use them before major changes or to safeguard against accidental data loss.

<Callout type="info">
  Snapshots are available on cloud-hosted paid plans and self-hosted enterprise plans.
</Callout>

## Key Notes

* Restoring a snapshot creates a new base — the existing base is not modified.
* You can choose which workspace to restore the snapshot into.
* Audit log data (global audits and record revision history) is not included in snapshots.
* Base-level permissions, shared base, and shared view settings are not restored — these must be reconfigured manually.
* The number of snapshots allowed per base depends on your plan.
* A minimum gap of three hours is required between creating two snapshots.
* Only **Base Owners** can access the snapshot feature.

## Access Snapshots

1. Open the base and go to **Base Settings** → **Manage Snapshots** in the sidebar.

<img alt="Snapshots" src={__img0} placeholder="blur" />

## Create a Snapshot

1. Click **+ New Snapshot**.
2. Enter a name for the snapshot (defaults to the current date and time).
3. Click **Save**.

<img alt="Create Snapshot" src={__img1} placeholder="blur" />

The snapshot will appear in the list with **Restore** and **Delete** actions.

<img alt="Create Snapshot" src={__img2} placeholder="blur" />

## Restore a Snapshot

1. Click **Restore** next to the snapshot you want to restore.
2. Select the target workspace (defaults to current workspace).
3. Click **Confirm Restore**.

<img alt="Restore Snapshot" src={__img3} placeholder="blur" />

<Callout type="info">
  Restoring a snapshot creates a new base in the selected workspace. The existing base is not affected.
</Callout>

## Delete a Snapshot

1. Click the **delete icon** (🗑️) next to the snapshot.
2. Click **Delete Snapshot** to confirm.

<img alt="Delete Snapshot" src={__img4} placeholder="blur" />


# Auth0
URL: /docs/product-docs/account-settings/authentication/oidc-sso/auth0

Learn how to configure Auth0 as an identity provider for NocoDB.









<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Auth0 as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring OIDC SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `Redirect URL`

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider

<img alt="OIDC SSO Configuration" src={__img0} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img1} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img2} placeholder="blur" />

### Auth0, Configure NocoDB as an Application

1. Access your [Auth0 account](https://auth0.com/)
   * navigate to `Applications` > `Create Application`.
2. In the `Create Application` modal,
   * choose `Regular Web Application`
   * click `Create`
3. On Quick start screen, go to `Settings` tab
   * Copy the `Client ID` and `Client Secret` from the `Basic Information` section.
4. Goto `Application URIs` section
   * Add the `Redirect URL` copied from step(2) under `Allowed Callback URLs`.
   * `Save Changes`
5. On the `Settings` tab, go to the `Advanced Settings` section and click on the `Endpoints` tab.
   * Copy the `OAuth Authorization URL`, `OAuth Token URL`, `OAuth User Info URL` & `JSON Web Key Set URL`

### NocoDB, Configure Auth0 as an Identity Provider

1. In NocoDB, open `Account Settings` > `Authentication` > `OIDC`. On the "Register OIDC Identity Provider" modal, insert the following information:
   * Insert `Client ID` retrieved in step (5) above as `Client ID`
   * Insert `Client Secret` retrieved in step (5) above as `Client Secret`
   * Insert `OAuth Authorization URL` retrieved in step (7) above as `Authorization URL`
   * Insert `OAuth Token URL` retrieved in step (7) above as `Token URL`
   * Insert `OAuth User Info URL` retrieved in step (7) above as `Userinfo URL`
   * Insert `JSON Web Key Set URL` retrieved in step (7) above as `JWK Set URL`
   * Set `Scope` as `openid` `profile` `email` `offline_access`
   * In the Username Attribute field, indicate the name of the claim that represents the user's email. The default value is set to "email."

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

<Callout type="info">
  Post sign-out, refresh page (for the first time) if you do not see 

  `Sign in with SSO`

   option
</Callout>

For information about Auth0 API Scopes, refer [here](https://auth0.com/docs/secure/tokens/refresh-tokens)

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Azure AD (Entra)
URL: /docs/product-docs/account-settings/authentication/oidc-sso/azure-ad

Learn how to configure Azure AD as an identity provider for NocoDB.









<Callout type="info">
  Please reach 

  [**out to sales**](https://cal.com/nocodb/sales)

   for SSO access
</Callout>

This article briefs about the steps to configure Azure AD as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring OIDC SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `Redirect URL`

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider

<img alt="OIDC SSO Configuration" src={__img0} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img1} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img2} placeholder="blur" />

### Azure AD, Configure NocoDB as an Application

1. Sign in to your [Azure account](https://portal.azure.com/#allservices) and navigate to `Azure Active Directory` under `Azure Services`.
2. Access `Manage Tenants` from the navigation bar, select your directory, and click `Switch`.
3. On your directory's homepage, click `+ Add` > `App Registration` from the navigation bar.
4. On the `Register an application` page,
   * Provide your application's name.
   * Set `Accounts in this organizational directory only` as the `Supported account types`.
   * Choose `Web` as the Application type
   * Add the `Redirect URL` under `Redirect URIs`.
   * `Register`
5. On your application's homepage,
   * Copy the `Application (client) ID`
   * Click `Add a certificate or secret` under `Client credentials` section
   * On `Certificates & secrets` page, go to `Client secrets` section
   * Click `New client secret`
   * On `Add a client secret` page,
     * Add a description for the secret
     * Set expiration as required
     * `Add`
   * Copy the `Value` of the newly created secret
6. On your application's homepage,
   * Go to `Endpoints` tab
   * Open `OpenID Connect metadata document` URL & copy `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` & `jwks_uri` from the JSON response
7. Configuring scopes
   * Go to `API permissions` tab
   * Click `Add a permission`
   * On `Request API permissions` page,
     * Select `Microsoft Graph` from `Microsoft APIs`
     * Select `Delegated permissions`
     * Select `openid` `profile` `email` `offline_access` from `Select permissions` dropdown
     * From `Users` dropdown, select `User.Read`
     * `Add permissions`
   * Click `Grant admin consent for this directory` from the `API permissions` page

### NocoDB, Configure Azure AD as an Identity Provider

On NocoDB, open `Account Settings` > `Authentication` > `OIDC`. On the "Register OIDC Identity Provider" modal, insert the following information:

* Insert `Application (client) ID` retrieved in step (7) above as `Client ID`
* Insert `Value` of the newly created secret retrieved in step (7) above as `Client Secret`
* Insert `authorization_endpoint` retrieved in step (8) above as `Authorization URL`
* Insert `token_endpoint` retrieved in step (8) above as `Token URL`
* Insert `userinfo_endpoint` retrieved in step (8) above as `Userinfo URL`
* Insert `jwks_uri` retrieved in step (8) above as `JWK Set URL`
* Set `Scope` as `openid` `profile` `email` `offline_access`

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

<Callout type="info">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>

For information about Azure AD API Scopes, refer [here](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#offline_access)


# Okta
URL: /docs/product-docs/account-settings/authentication/oidc-sso/okta

Learn how to configure Okta as an identity provider for NocoDB.









<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Okta as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring OIDC SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `Redirect URL`

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider

<img alt="OIDC SSO Configuration" src={__img0} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img1} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img2} placeholder="blur" />

### Okta, Configure NocoDB as an Application

1. Sign in to your [Okta account](https://www.okta.com/) and navigate to the "Get started with Okta" page.
   * Click on `Add App` for the Single Sign-On option.
   * On the `Browse App Integration Catalog` page, select `Create New App`
2. In the pop-up with title `Create a new app integration`
   * Choose `OIDC - OpenID Connect` as the Sign-in method
   * Choose `Web Application` as the Application type
3. Go to `General Settings` on the `New Web App Integration` page
   * Provide your application's name.
   * From the Options in the `Grant type allowed` section, select `Authorization Code` and `Refresh Token`
   * Add the `Redirect URL` under `Sign-in redirect URIs`.
   * From the `Assignments section`, select an option from `Controlled access` to set up the desired accessibility configuration for this application.
   * `Save`
4. On your new application,
   * Go to the `General` tab
   * Copy the `Client ID` and `Client Secret` from the `Client Credentials` section.
5. From `Account` dropdown in navigation bar
   * Copy `Okta Domain`
6. Append "./well-known/openid-configuration" to the `Okta Domain` URL & access it
   * Example: [https://dev-123456.okta.com/.well-known/openid-configuration](https://dev-123456.okta.com/.well-known/openid-configuration)
   * Copy `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` & `jwks_uri` from the JSON response

### NocoDB, Configure Okta as an Identity Provider

In NocoDB, open `Account Settings` > `Authentication` > `OIDC`. On the "Register OIDC Identity Provider" modal, insert the following information:

* Insert `Client ID` retrieved in step (6) above as `Client ID`
* Insert `Client Secret` retrieved in step (6) above as `Client Secret`
* Insert `authorization_endpoint` retrieved in step (8) above as `Authorization URL`
* Insert `token_endpoint` retrieved in step (8) above as `Token URL`
* Insert `userinfo_endpoint` retrieved in step (8) above as `Userinfo URL`
* Insert `jwks_uri` retrieved in step (8) above as `JWK Set URL`
* Set `Scope` as `openid` `profile` `email` `offline_access`
* In the Username Attribute field, indicate the name of the claim that represents the user's email. The default value is set to "email."

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

For information about Okta API Scopes, refer [here](https://developer.okta.com/docs/reference/api/oidc/#scopes)

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Ping Identity
URL: /docs/product-docs/account-settings/authentication/oidc-sso/ping-identity

Learn how to configure Ping Identity as an identity provider for NocoDB.









<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Ping Identity as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring OIDC SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `Redirect URL`

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider

<img alt="OIDC SSO Configuration" src={__img0} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img1} placeholder="blur" />
<img alt="OIDC SSO Configuration" src={__img2} placeholder="blur" />

### Ping Identity, Configure NocoDB as an Application

1. Access your [PingOne account](https://www.pingidentity.com/en/account/sign-on.html) and navigate to the homepage.
2. Click on `Add Environment` from the top right corner.
3. On the `Create Environment` screen,
   * Opt for `Build your own solution`
   * In the `Select solution(s) for your Environment` section, select `PingOne SSO` from `Cloud Services`
   * Click `Next`
   * Provide a name and description for the environment,
   * Click `Next`
4. Access the newly created environment and go to `Connections` > `Applications` from the sidebar.
5. Within the Applications homepage, initiate the creation of a new application by clicking the "+" icon.
6. On the "Add Application" panel:
   * Input the application name and description.
   * Choose "OIDC Web App" as the Application Type and click "Configure"
7. From your application,
   * Go to `Configurations` tab
   * Click on `Edit` button
   * Check `Refresh Token` option
   * Copy `Authorization URL`, `Token URL`, `Userinfo URL` & `JWK Set URL` from the `Endpoints` section
   * From `Generals` dropdown, copy `Client ID` & `Client Secret`
   * `Save`
8. From `Resources` tab,
   * Click `Edit`
   * Select `openid` `profile` `email` from `Scopes`
9. Switch toggle button in the top right corner to `On` to activate the application.

### NocoDB, Configure Ping Identity as an Identity Provider

1. In NocoDB, open `Account Settings` > `Authentication` > `OIDC`. On the "Register OIDC Identity Provider" modal, insert the following information:
   * Insert `Client ID` retrieved in step (9) above as `Client ID`
   * Insert `Client Secret` retrieved in step (9) above as `Client Secret`
   * Insert `Authorization URL` retrieved in step (9) above as `Authorization URL`
   * Insert `Token URL` retrieved in step (9) above as `Token URL`
   * Insert `Userinfo URL` retrieved in step (9) above as `Userinfo URL`
   * Insert `JWK Set URL` retrieved in step (9) above as `JWK Set URL`
   * Set `Scope` as `openid` `profile` `email` `offline_access`
   * In the Username Attribute field, indicate the name of the claim that represents the user's email. The default value is set to "email."

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

For information about Ping Identity API Scopes, refer [here](https://docs.pingidentity.com/r/en-us/pingone/pingone_t_edit_scopes_for_an_application)

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Auth0
URL: /docs/product-docs/account-settings/authentication/saml-sso/auth0

Learn how to configure Auth0 as an identity provider for NocoDB.











<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Auth0 as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring SAML SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `SAML SSO` Configuration details

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL` & `Audience / Entity ID`; these information will be required to be configured later with the Identity Provider

<img alt="SAML SSO Configuration" src={__img0} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img2} placeholder="blur" />

### Auth0, Configure NocoDB as an Application

1. Access your [Auth0 account](https://auth0.com/)
   * navigate to `Applications` > `Create Application`.

2. In the `Create Application` modal,
   * choose `Regular Web Application`
   * click `Create`

3. Upon successful creation, you will be directed to the `Quick Start` screen.
   * Go to the `Addons` tab.
   * Enable `SAML2 Web App`

4. On the `SAML2 Web App` modal,
   * Paste `Redirect URL` copied in step above into `Application Callback URL` field
   * In Settings, retain `nameIdentifierProbes` as `["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]`; remove other probes if any
   ```json
   {
     "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
     ]
   }
   ```
   * Click `Enable` to save the settings

5. On the `Settings` tab,
   * move to `Advanced Settings` > `Endpoints` > `SAML` section,
   * copy the SAML `Metadata URL`

[//]: # "3. Upon successful creation, you will be directed to the `Quick Start` screen. "

[//]: # "    - Go to the `Settings` tab."

[//]: # "    - Paste `Redirect URI` copied in step above into `Allowed Callback URLs` field"

[//]: # "    - `Save`"

### NocoDB, Configure Auth0 as an Identity Provider

1. Go to `Account Settings` > `Authentication` > `SAML`
2. Insert `Metadata URL` retrieved in step above; alternatively you can configure XML directly as well
3. `Save`

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img4} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Azure AD (Entra)
URL: /docs/product-docs/account-settings/authentication/saml-sso/azure-ad

Learn how to configure Active Directory as an identity provider for NocoDB.











<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Active Directory as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring SAML SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `SAML SSO` Configuration details

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the
   provider on the login page
5. Retrieve `Redirect URL` & `Audience / Entity ID`; these information will be required to be configured later with the
   Identity Provider

<img alt="SAML SSO Configuration" src={__img0} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img2} placeholder="blur" />

### Azure AD, Configure NocoDB as an Application

1. Sign in to your [Azure account](https://portal.azure.com/#allservices) and navigate
   to `Microsoft Entra admin center` > `Identity` > `Enterprise applications`
2. Click `+ New application`
3. On the `Browse Microsoft Entra Gallery` page, select `Create your own application` from the navigation bar.
   * Provide your application's name.
   * Choose `Integrate any other application you don't find in the gallery (Non-gallery)`
   * `Create`
4. On your application page, navigate to `Manage` > `Single sign-on` > `SAML`
5. Go to the `Basic SAML Configuration` section under `Set up Single Sign-On with SAML` and click `Edit`
   * Add the `Audience URI` under `Identifier (Entity ID)`.
   * Add the `Redirect URL` under `Replay URL (Assertion Consumer Service URL)`.
   * Click `Save`
6. In the `Attributes & Claims` section, click `Edit`
   * Edit the "Unique User Identifier (Name ID)" claim:
     * Select `Email address` from the `Name identifier format` dropdown
     * Choose `Attribute` as the `Source`
     * In the `Source attribute`, select `user.mail`
     * Click `Save`
7. Go to the `SAML Certificates` section and copy the `App Federation Metadata URL`
8. on the Application's Overview page,
   * Click `Users and groups`,
   * Add the necessary users or groups to the application.

### NocoDB, Configure Azure AD as an Identity Provider

1. Go to `Account Settings` > `Authentication` > `SAML`
2. Insert `Metadata URL` retrieved in step above; alternatively you can configure XML directly as well
3. `Save`

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img4} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Keycloak
URL: /docs/product-docs/account-settings/authentication/saml-sso/keycloak

Learn how to configure Keycloak as an identity provider for NocoDB.











<Callout type="info">
  For SSO Access - please reach [**out to sales team**](https://cal.com/nocodb/sales).
</Callout>

This article briefs about the steps to configure Keycloak as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring SAML SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `SAML SSO` Configuration details

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL` & `Audience / Entity ID`; these information will be required to be configured later with the Identity Provider

<img alt="SAML SSO Configuration" src={__img0} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img2} placeholder="blur" />

### Keycloak, Configure NocoDB as an Application

1. Access your Keycloak account
   * navigate to `Clients` menu
   * select `Clients list` tab > Click `Create client` button.
2. In the `Create Client` modal, `General Settings` tab:
   * Select `SAML` as the `Client type`
   * Specify `Audience/Entity ID` retrieved from NocoDB as the `Client ID`
   * Click `Next`
3. In the `Create Client` modal, `Login Settings` tab,
   * Specify `Redirect URL` retrieved from NocoDB as the `Valid Redirect URIs`
   * Specify `Redirect URL` retrieved from NocoDB as the `Valid post logout redirect URIs`
   * Click `Save`
4. On the `Client details`, `Settings` tab,
   * navigate to `SAML Capabilities` section
   * Specify `Name ID format` as `email`
   * Enable `Force Name ID Format` and `Force POST Binding`
   * navigate to `Signature and Encryption` section
   * Enable `Sign Assertions`
   * Click `Save`
5. On the `Client details`, `Keys` tab,
   * Disable `Signing keys config` > `Client Signature Required`
6. Navigate to `Realm Settings` > `Endpoints`
   * Copy `SAML 2.0 Identity Provider Metadata` URL

### NocoDB, Configure Azure AD as an Identity Provider

1. Go to `Account Settings` > `Authentication` > `SAML`Key
2. Insert `Metadata URL` retrieved in step above; alternatively you can configure XML directly as well
3. `Save`

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img4} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with <SSO>` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Okta
URL: /docs/product-docs/account-settings/authentication/saml-sso/okta

Learn how to configure Okta as an identity provider for NocoDB.











<Callout type="info">
  For SSO Access - please reach [**out to sales team**](https://cal.com/nocodb/sales).
</Callout>

This article briefs about the steps to configure Okta as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring SAML SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `SAML SSO` Configuration details

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL` & `Audience / Entity ID`; these information will be required to be configured later with the Identity Provider

<img alt="SAML SSO Configuration" src={__img0} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img2} placeholder="blur" />

### Okta, Configure NocoDB as an Application

1. Sign in to your [Okta account](https://www.okta.com/)
   * Navigate to `Applications` > `Applications`
   * Click `Create App Integration`
2. In the pop-up with title `Create a new app integration` choose `SAML 2.0` as the Sign-in method
3. On the `Create SAML Integration` page, in the General settings - provide a name for your app; click `Next`
4. In the `Configure SAML` section:
   * Enter the `Redirect URL` copied from NocoDB in the `Single sign-on URL` field.
   * Add the `Audience URI` copied from NocoDB in the `Audience URI (SP Entity ID)` field.
   * Choose `Email Address` from the `Name ID format` options.
   * Select `Email` from the `Application user-name` options.
   * Click `Next`
5. Complete any additional information in the final step and click `Finish`
6. On your application's homepage,
   * Navigate to the `Sign-on` tab
   * Copy the `Metadata URL` from the `SAML 2.0` section
7. Go to the `Assignments` tab and click `Assign` to assign people or groups to this application.

### NocoDB, Configure Okta as an Identity Provider

1. Go to `Account Settings` > `Authentication (SSO)` > `SAML`
2. On the "Register SAML Identity Provider" modal, insert `Metadata URL` retrieved in step above; alternatively you can configure XML directly as well
3. `Save`

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img4} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# Ping Identity
URL: /docs/product-docs/account-settings/authentication/saml-sso/ping-identity

Learn how to configure Ping Identity as an identity provider for NocoDB.











<Callout type="info">
  For SSO Access - please reach 

  [**out to sales team**](https://cal.com/nocodb/sales)
</Callout>

This article briefs about the steps to configure Auth0 as Identity service provider for NocoDB

<Callout type="info">
  For users on 

  **Business plan**

  , the SSO configuration menu is available under 

  **Workspace Settings**

  .
  Refer 

  [here](/docs/product-docs/account-settings/authentication#business-plan)

   for more details.
</Callout>

<Callout type="warning">
  **Domain Verification Required for Cloud Plans**

  : Before configuring SAML SSO, you must verify your domain in NocoDB (required for both Business and Enterprise plans in the cloud). Only users with email addresses from verified domains can sign in via SSO. See 

  [Domain Verification](/docs/product-docs/account-settings/authentication#domain-verification)

   for details.
</Callout>

### NocoDB, Retrieve `SAML SSO` Configuration details

1. Go to `Account Settings`
2. Select `Authentication (SSO)`
3. Click on `New Provider` button
4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
5. Retrieve `Redirect URL` & `Audience / Entity ID`; these information will be required to be configured later with the Identity Provider

<img alt="SAML SSO Configuration" src={__img0} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img1} placeholder="blur" />
<img alt="SAML SSO Configuration" src={__img2} placeholder="blur" />

### Ping Identity, Configure NocoDB as an Application

1. Access your [PingOne account](https://www.pingidentity.com/en/account/sign-on.html) and navigate to the homepage.
2. Click on `Add Environment` from the top right corner.
3. On the `Create Environment` screen,
   * Opt for `Build your own solution`
   * In the `Select solution(s) for your Environment` section, select `PingOne SSO` from `Cloud Services`
   * Click `Next`
   * Provide a name and description for the environment,
   * Click `Next`
4. Access the newly created environment and go to `Connections` > `Applications` from the sidebar.
5. Within the Applications homepage, initiate the creation of a new application by clicking the "+" icon.
6. On the "Add Application" panel:
   * Input the application name and description.
   * Choose "SAML Application" as the Application Type and click "Configure."
   * Within the SAML Configuration panel, opt for "Manually Enter."
   * Populate the `ACS URLs` field with the `Redirect URL` retrieved from step (2) above
   * Insert the `Audience URI` retrieved above in step (2) in the `Entity ID` field
   * `Save`
7. In your application,
   * Navigate to the `Configurations` tab
   * Copy the `IDP Metadata URL`
8. On your application panel, activate user access to the application by toggling the switch in the top right corner.

### NocoDB, Configure Ping Identity as an Identity Provider

1. Go to `Account Settings` > `Authentication` > `SAML`
2. Insert `Metadata URL` retrieved in step above; alternatively you can configure XML directly as well
3. `Save`

<img alt="SAML SSO Configuration" src={__img3} placeholder="blur" />

For Sign-in's, user should be able to now see `Sign in with <SSO>` option.

<img alt="SAML SSO Configuration" src={__img4} placeholder="blur" />

<Callout type="note">
  Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
</Callout>

<Callout type="info">
  For more common questions and troubleshooting, see our 

  [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs)

  .
</Callout>


# QR code
URL: /docs/product-docs/fields/field-types/custom-types/QR-code

This article explains how to create & work with a QR code field.







`QR code` is a custom field type that allows you to generate a QR code from a string value. This is useful for generating QR codes for things like URLs, phone numbers, or other data that can be represented as a string.

The following field types are supported for the reference field:

* Formula
* Single Line Text
* Long Text
* Phone Number
* URL
* Email

## Create a QR code field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `QR Code` from the dropdown.
4. Select the field to be used as the source for the QR code.
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Cell displays the QR code generated from the source field. Click on the cell to open enlarged view of the QR code.

<img alt="image" src={__img1} placeholder="blur" />\
<img alt="image" src={__img2} placeholder="blur" />

## Related fields

* [Barcode](/docs/product-docs/fields/field-types/custom-types/barcode)


# Attachment
URL: /docs/product-docs/fields/field-types/custom-types/attachment

This article explains how to create & work with an Attachment field.







`Attachment` fields allow you to upload files to your records. You can upload any file type, and the file will be linked to the record. You can also upload multiple files to a single `Attachment` field record.

## Create an Attachment field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Attachment` from the dropdown.
4. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="info">
  Max size for an attachment file is currently limited to 5 MB
</Callout>

### Cell display

The cell display for `Attachment` field is either a clickable preview if file is an image in recognizable format or a file-type icon.\
<img alt="image" src={__img1} placeholder="blur" />

### Upload files

To upload files to an `Attachment` field,

* Click on the `+` icon in the cell, choose the file to upload and click on `Upload` button. OR
* Drag drop the file to the cell. OR
* Click on expand icon `<>`, choose the file to upload or drag-drop file; click on `Upload` button.

## Expand modal

Expand modal for `Attachment` field displays the list of files uploaded to the field. You can also upload files from the expand modal. To access expand modal, click on the expand icon `<>` in the cell.

<img alt="image" src={__img2} placeholder="blur" />

Expand modal supports the following actions:

### Attach file(s)

* Click on `Attach file(s)` button {"<"}1{">"}
* Choose the file(s) to upload

### Delete file

* Click on `x` icon {"<"}2{">"} to the top left of the image card to delete the file

### Download file

* Click on `Download` button {"<"}5{">"} to download the file

### Bulk Download file(s)

* Select the files by clicking on the checkbox {"<"}3{">"} to the top left of the image card
* Click on `Bulk Download` button {"<"}4{">"} to download the selected files

### Rename file

* Click on `Rename` button {"<"}5{">"} to rename the file
* Enter the new name in the input field
* Click on `Rename` button to save the new name

<Callout type="note">
  Rename file only renames the file in NocoDB display (expand record & tool tip on hover). It does not rename the file in the storage.
</Callout>

## Environment variables

In self-hosted version, you can configure the following environment variables to customize the behavior of `Attachment` field:

* `NC_ATTACHMENT_FIELD_SIZE`: Maximum size of attachment files in bytes. Default: `20971520` (20 MiB)
* `NC_MAX_ATTACHMENTS_ALLOWED`: Maximum number of attachments per cell. Default: `10`
* `NC_SECURE_ATTACHMENTS`: Allow accessing attachments only through pre-signed URLs. Default: `false`
* `NC_ATTACHMENT_EXPIRE_SECONDS`: Expiry time for pre-signed URLs. Default: `7200` (2 hours)

All supported environment variables are described [here](/docs/self-hosting/environment-variables).

## Related articles

* [Attaching a file from mobile](/docs/product-docs/views/view-types/form#attaching-a-file-from-mobile-device)


# Barcode
URL: /docs/product-docs/fields/field-types/custom-types/barcode

This article explains how to create & work with a Barcode field.







`Barcode` is a custom field type that allows you to generate a barcode from a string value. This is useful for generating barcodes for things like URLs, phone numbers, or other data that can be represented as a string.

The following field types are supported for the for reference field:

* Formula
* Single Line Text
* Long Text
* Phone Number
* URL
* Email

## Create a barcode field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Barcode` from the dropdown.
4. Select the field to be used as the source for the barcode.
5. Select the barcode type from the dropdown.
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Cell displays the barcode generated from the source field. Click on the cell to open enlarged view of the QR code.

<img alt="image" src={__img1} placeholder="blur" />\
<img alt="image" src={__img2} placeholder="blur" />

### Supported barcode types

NocoDB supports the following barcode types for the barcode field type.

* CODE128
* EAN-13
* EAN-8
* EAN-5
* EAN-2
* UPC (A)
* CODE39
* ITF-14
* MSI
* Pharma code
* Coda bar

## Related fields

* [QR code](/docs/product-docs/fields/field-types/custom-types/QR-code)


# Button
URL: /docs/product-docs/fields/field-types/custom-types/button

This article explains how to create & work with a Button field.















The **Button** Field allows users to create interactive buttons within their tables. These buttons can trigger specific actions, making workflows more dynamic and efficient. With the Button Field, you can navigate to external URLs, run custom webhooks, or even run custom scripts with a single click.

NocoDB currently supports following actions for the Button Field:

1. **Open URL**: Opens a new tab with a URL generated by a formula within the button field. The URL can be static or dynamic based on the current record's data.
2. **Run Webhook**: Trigger a webhook with the configured URL & custom payload. Payload can include data from the current record.
3. **Run Script**: Execute a custom script that can perform various operations on the current record or the entire table. Current record information can be accessed using the `row` variable in the script.

<Callout type="note">
  **Run Script**

   action is currently available only in the NocoDB Cloud version, Plus and above plans.
</Callout>

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/V20tQDkbkvU?si=7EL1IppfR7V9LRBF&start=13" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

## Create a Button Field

1. Click on the `+` icon to the right of the `Fields` header.
2. In the dropdown modal, enter the field name (optional).
3. Select the field type as `Button` from the dropdown.
4. Configure the button **appearance** settings as needed. This includes the button text, color, and icon.
5. Select the action type from the dropdown.
6. Configure the button **action** settings as needed. This depends on the action you want the button to perform
   * **Open URL**: Use the formula editor to create dynamic URLs.
   * **Run Webhook**: Select a webhook from the dropdown OR create a new webhook by clicking on the `+` icon.
   * **Run Script**: Select a script from the dropdown.
7. Click on the `Save Field` button.

### Button URL

<img alt="image" src={__img0} placeholder="blur" />

### Button Webhook

<img alt="image" src={__img1} placeholder="blur" />

<Callout type="note">
  For the 

  **"Run Webhook"**

   action, a webhook with the required trigger type must first be created in the 

  **Webhooks**

   section. The same webhook can be reused across multiple Button fields. Please note that the 

  **"Run Webhook"**

   action is not available in shared views or shared bases.
</Callout>

#### Edit Webhook

To edit a webhook, click on the `Edit` icon next to the webhook name in the Button field settings. This will open the webhook settings modal, where you can edit the webhook URL, method, headers, and payload. Click on the `Save changes` button to save the changes.

<img src="/img/v2/fields/types/button-webhook-edit.png" width="350" />

<img alt="image" src={__img2} placeholder="blur" />

Created webhook can be accessed by using the [Webhook](/docs/product-docs/automation/webhook) section in details tab. For more details, refer to the following articles:

* [Create webhook](/docs/product-docs/automation/webhook/create-webhook)
* [Edit webhook](/docs/product-docs/automation/webhook/actions-on-webhook#edit-webhook)
* [Delete webhook](/docs/product-docs/automation/webhook/actions-on-webhook#delete-webhook)

<Callout type="note">
  Deleting a webhook will remove it from all Button fields that reference it, whereas deleting a Button field will not affect the associated webhook. A single webhook can also be reused across multiple Button fields.
</Callout>

### Button Script

<img alt="image" src={__img3} placeholder="blur" />

Also termed as "Row Actions", Button Scripts let you trigger pre-configured actions directly from a record in Grid / Kanban / Gallery views. Instead of manually editing fields to update values like status or stage, you can now perform repetitive updates in a single click.

Each button is configured to execute a Frontend Script that updates the record or performs other automated actions. When a user clicks the button, the configured script runs in the context of that record.

Sample Script to update a field value:

```javascript
const recordID = cursor?.row?.id;
const table = await base.getTable("Table-1");

if(recordID) {
    // Perform operations if recordID is valid
    console.log(`Record ID is: ${recordID}`);

    // You can add more logic here based on your requirements
    await table.updateRecordAsync(recordID, {
        "Status": "Completed",
        "Title": "Default Title"
    })
} else {
    // Handle the case where recordID is undefined or null
    console.error('Record ID is not defined');
}
```

## Conditional Buttons ☁

<Callout type="note">
  Availability: NocoDB Cloud Business plan onwards & self-hosted Enterprise license.
</Callout>

By default, a button is always enabled for every record in the table. With **Visibility Conditions**, you can control when a button is active on a per-row basis. When the conditions are not met for a particular record, the button appears disabled with a "Conditions not met" tooltip, preventing any accidental clicks.

This is useful when you want a button action to only be available under certain circumstances — for example, enabling an "Approve" button only when a status field is set to "Pending", or allowing a "Send Invoice" button only after the amount exceeds a threshold.

Visibility conditions work with all button action types — Open URL, Run Webhook, and Run Script.

<img alt="image" src={__img4} placeholder="blur" />

### Setting up visibility conditions

1. Open the button field configuration (create a new button field or edit an existing one).
2. Scroll down to the **Visibility condition** section and expand it.
3. Click **Add filter** to define one or more conditions based on fields in the current table.
4. Use **Add filter group** to combine multiple conditions with AND/OR logic.
5. Click **Save Field** to apply.

<img alt="image" src={__img5} placeholder="blur" />

Once configured, each row in the table is evaluated against the defined conditions:

* **Condition met**: The button is enabled and clickable.
* **Condition not met**: The button is disabled and displays a "Conditions not met" tooltip on hover.

<img alt="image" src={__img6} placeholder="blur" />

### Editing or removing visibility conditions

To modify existing conditions, open the button field configuration and update the filters in the **Visibility condition** section. To remove all conditions and make the button always active, clear all filters and save the field.

<Callout type="note">
  Visibility conditions use the same filter system as view filters, supporting all standard comparison operators, grouped conditions with AND/OR logic, and user-based conditions.
</Callout>


# Checkbox
URL: /docs/product-docs/fields/field-types/custom-types/checkbox

This article explains how to create & work with a Checkbox field.







The checkbox field type is used to store boolean values. It can be used to store a simple yes/no value, or true/false, or any other boolean value.

## Create a checkbox field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Checkbox` from the dropdown.
4. Select icon for the field; defaults to `check` icon (Optional).
5. Select color for the field; defaults to `grey` (Optional).
6. Set default value for the field (Optional).
7. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Cell displays the icon in the color selected for the field. A true value will be represented by a checked icon or a filled icon\
<img alt="image" src={__img1} placeholder="blur" />

### Supported icons

NocoDB supports the following icons for the checkbox field type.\
<img alt="image" src={__img2} placeholder="blur" />

## Related fields

* [Rating](/docs/product-docs/fields/field-types/custom-types/rating)


# Colour
URL: /docs/product-docs/fields/field-types/custom-types/colour

This article explains how to create & work with a Colour field.



<Callout type="info">
   Available on cloud deployments & On-prem licensed deployments
</Callout>

The `Colour field` allows you to store and display colour values as hex codes (e.g. `#FF5733`). Each cell shows a colour swatch alongside an editable hex input, making it easy to visually identify and modify colours. A built-in colour picker with default and custom colour palettes is available for quick selection.

## Create a colour field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Colour` from the dropdown.
4. Set default value for the field using the colour picker (Optional).
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Each cell displays a colour swatch on the left and the hex value on the right. Clicking the swatch opens the colour picker, and the hex value can be edited directly in the text input.

### Setting value for the field

* Click on the colour swatch to open the colour picker and select a colour.
* Type a hex value directly into the text input (e.g. `#FF5733` or `FF5733`).
* Paste a hex value into the text input.

### Unsetting value for the field

* Clear the text input to remove the colour value.
* Key in `Delete` to clear the colour value for the field.

### Colour picker

The colour picker provides two tabs:

* **Default colours** - A palette of commonly used colours for quick selection.
* **Custom** - A full colour wheel with hue, saturation, and brightness controls, plus a hex input for precise colour entry.

Press `Enter` to save the selected colour, or `Escape` to cancel.

### Filtering

Colour fields support text-based filtering on the hex value. The filter input includes a colour swatch preview alongside the text input for visual reference.

## Related fields

* [Checkbox](/docs/product-docs/fields/field-types/custom-types/checkbox)
* [Rating](/docs/product-docs/fields/field-types/custom-types/rating)


# GeoData
URL: /docs/product-docs/fields/field-types/custom-types/geodata

This article explains how to create and work with a GeoData field.











The **GeoData** field stores geographic coordinates (latitude and longitude) for a record. It provides an interactive map interface for viewing and selecting locations, supports place search, and can be used as the data source for [Map View](/docs/product-docs/views/view-types/map).

## Create a GeoData field

1. Click on the `+` icon to the right of the `Fields header`.
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `GeoData` from the dropdown.
4. Click on `Save Field` button.

<img alt="Create GeoData field" src={__img0} placeholder="blur" />

## Cell display

In the grid view, a GeoData cell displays the stored latitude and longitude values as a coordinate pair. Clicking on the cell opens the expanded cell editor.

## Cell editor

The expanded cell editor provides an interactive interface for viewing and setting a location.

<img alt="GeoData cell editor" src={__img1} placeholder="blur" />

The cell editor includes:

* **Latitude and Longitude inputs** — manually enter or adjust coordinates directly.
* **Interactive map** — displays the selected location with a marker on an OpenStreetMap-powered map. You can click on the map to move the marker to a new position.
* **Place search** — search for a location by name using the search bar at the top of the map. Select a result from the dropdown to set the coordinates automatically.

<img alt="Place search" src={__img2} placeholder="blur" />

* **Use Current Location** — click this button to populate the field with your device's current geographic coordinates (requires browser location permission).

<img alt="Current location" src={__img3} placeholder="blur" />

### External map links

At the bottom of the cell editor, quick links to **Google Maps** and **OpenStreetMap** are provided so you can view the selected location in a full mapping application.

<img alt="External map links" src={__img4} placeholder="blur" />

## Filtering GeoData fields

GeoData fields support the following filter operations:

| Filter operation | Description                                    |
| ---------------- | ---------------------------------------------- |
| is like          | Matches records containing the specified text  |
| is not like      | Excludes records containing the specified text |
| is blank         | Matches records with no coordinates set        |
| is not blank     | Matches records that have coordinates          |

## Sorting GeoData fields

GeoData fields can be sorted in ascending or descending order based on the text representation of the stored coordinates.

## Related topics

* [Map View](/docs/product-docs/views/view-types/map) — visualize GeoData records as markers on an interactive map.
* [Geometry](/docs/product-docs/fields/field-types/custom-types/geometry) — stores geometric shapes and spatial data.


# Geometry
URL: /docs/product-docs/fields/field-types/custom-types/geometry

This article explains how to create & work with a Geometry field.



## Create a geometry field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional)
3. Select the field type as `Geometry` from the dropdown.
4. Configure default value for the field (Optional)
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />


# JSON
URL: /docs/product-docs/fields/field-types/custom-types/json





`JSON` is a custom field type that allows you to store JSON data in a field. Useful for storing data that can be represented as a JSON object, like API Response, or a set of key-value pairs.

## Create a JSON field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `JSON` from the dropdown.
4. Configure default value for the field (Optional)
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Cell displays the JSON data stored in the field. Click on expand record icon to open the JSON data in an editor modal.


# Rating
URL: /docs/product-docs/fields/field-types/custom-types/rating

This article explains how to create & work with a Rating field.







The `Rating field` allows you to capture and display ratings using a visual scale. The scale can be customized with different icons, colors, and maximum values. This makes it ideal for collecting feedback or evaluations in a visually intuitive way.

## Create a checkbox field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Rating` from the dropdown.
4. Select icon for the field; defaults to `star` icon (Optional).
5. Configure max count for the field; defaults to `5` (Optional).
6. Select color for the field; defaults to `grey` (Optional).
7. Set default value for the field (Optional).
8. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

Cell displays the ratings in the color & icon selected for the field.\
<img alt="image" src={__img1} placeholder="blur" />

### Setting value for the field

* Click on the `nth` rating icon to set the rating value for the field as `n`.
* Key in the rating value in the cell to set the rating value for the field.
* Paste the rating value in the cell to set the rating value for the field.

### Unsetting value for the field

* Click on the `nth` rating icon again to set the rating value for the field as `0`.
* Key in `0` in the cell to set the rating value for the field as `0`.
* Key in `Delete` to set the rating value for the field as `0`.

### Supported icons

NocoDB supports the following icons for the rating field type.\
<img alt="image" src={__img2} placeholder="blur" />

## Related fields

* [Checkbox](/docs/product-docs/fields/field-types/custom-types/checkbox)


# Specific DB type
URL: /docs/product-docs/fields/field-types/custom-types/specific-db-type

This article explains how to create & work with a Specific DB Type field.



## Create a Specific DB Type field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Specific DB Type` from the dropdown.
4. Configure default value for the field (Optional)
5. Provide DB specific data type configurations
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Advanced field attributes

* `NN` **Not Null** : Ensures that a column cannot have a NULL value, requiring that a value must always be provided.
* `PK` **Primary Key** : Uniquely identifies each record in a table.
* `AI` **Auto Increment** : Automatically generates a unique number for each new record, typically used with primary keys.
* `UN` **Unsigned** : Ensures that a column can only store non-negative numbers, commonly used for counters, identifiers, or monetary values.
* `AU` **Auto Update** : Automatically updates a column to the current timestamp when a record is updated, often used for timestamp or datetime columns.

:::note
Specific DB type is available only for external Data source connections
:::


# Created Time
URL: /docs/product-docs/fields/field-types/date-time-based/created-time

This article explains how to create & work with a Created Time field.



Since version v0.204.0 (Jan 2024), NocoDB internally captures the time when record was created. This information is stored as a system field in the database & is hidden in the table by default. To view this information on the UI, you can either enable `Show System Fields` OR create a `Created Time` field manually by following the steps below.

Default system field can be only hidden from UI. It cannot be modified, duplicated or deleted.

<Callout type="note">
  * When connected to an external database, `CreatedTime` field is not created automatically. You can create a `CreatedTime` field manually by following the steps below.
  * `CreatedTime` field is empty indicates the record predates the created at feature (v0.204.0, Jan 2024). Prior to this feature release, it was possible to remove this from the table.
</Callout>

## Create a `CreatedTime` field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `CreatedTime` from the dropdown.
4. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

## Cell display

`CreatedTime` field is displayed as a read-only field in the table view. It is displayed as a date & time string in the format `DD MMM YYYY, HH:mm`.

## Related fields

* [Last Modified Time](/docs/product-docs/fields/field-types/date-time-based/last-modified-time)


# Date Time
URL: /docs/product-docs/fields/field-types/date-time-based/date-time

This article explains how to create & work with a Date Time field.



`Date Time` field type is used to store both date and time values in a single field.

## Create a date time field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `DateTime` from the dropdown.
4. Configure `Date Format`
5. Configure `Time Format`
6. Configure default value (Optional)
7. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Supported date formats

| Format      | Example     |
| ----------- | ----------- |
| YYYY-MM-DD  | 2023-09-22  |
| YYYY/MM/DD  | 2023/09/22  |
| DD-MM-YYYY  | 22-09-2023  |
| MM-DD-YYYY  | 09-22-2023  |
| DD/MM/YYYY  | 22/09/2023  |
| MM/DD/YYYY  | 09/22/2023  |
| DD MM YYYY  | 22 09 2023  |
| MM DD YYYY  | 09 22 2023  |
| YYYY MM DD  | 2023 09 22  |
| DD MMM YYYY | 22 JAN 2024 |
| DD MMM YY   | 22 JAN 24   |
| DD.MM.YYYY  | 15.09.2024  |
| DD.MM.YY    | 15.09.24    |

### Supported time formats

| Format   | Example  |
| -------- | -------- |
| HH:mm:ss | 12:45:30 |
| HH:mm    | 14:20    |

## Related fields

* [Date](/docs/product-docs/fields/field-types/date-time-based/date)
* [Time](/docs/product-docs/fields/field-types/date-time-based/time)
* [Duration](/docs/product-docs/fields/field-types/date-time-based/duration)


# Date
URL: /docs/product-docs/fields/field-types/date-time-based/date

This article explains how to create & work with a Date field.



`Date` field type is used to store date values. NocoDB supports a wide range of date formats, as detailed in the table below.

## Create a date field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Date` from the dropdown.
4. Configure `Date Format`
5. Configure default value (Optional)
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Supported date formats

| Format      | Example     |
| ----------- | ----------- |
| YYYY-MM-DD  | 2023-09-22  |
| YYYY/MM/DD  | 2023/09/22  |
| DD-MM-YYYY  | 22-09-2023  |
| MM-DD-YYYY  | 09-22-2023  |
| DD/MM/YYYY  | 22/09/2023  |
| MM/DD/YYYY  | 09/22/2023  |
| DD MM YYYY  | 22 09 2023  |
| MM DD YYYY  | 09 22 2023  |
| YYYY MM DD  | 2023 09 22  |
| DD MMM YYYY | 22 JAN 2024 |
| DD MMM YY   | 22 JAN 24   |
| DD.MM.YYYY  | 15.09.2024  |
| DD.MM.YY    | 15.09.24    |

## Related fields

* [DateTime](/docs/product-docs/fields/field-types/date-time-based/date-time)
* [Time](/docs/product-docs/fields/field-types/date-time-based/time)
* [Duration](/docs/product-docs/fields/field-types/date-time-based/duration)


# Duration
URL: /docs/product-docs/fields/field-types/date-time-based/duration

This article explains how to create & work with a Duration field.



`Duration` field type is used to store duration of time in seconds or minutes. Different formats are supported by NocoDB, as detailed in the table below.

## Create a duration field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Duration` from the dropdown.
4. Configure `Duration Format`
5. Configure default value (Optional)
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Supported duration formats

| Format       | Example      |
| ------------ | ------------ |
| HH:mm        | 14:20        |
| HH:mm:ss     | 12:45:30     |
| HH:mm:ss.s   | 12:45:30.5   |
| HH:mm.ss.ss  | 12:45.30.50  |
| HH:mm.ss.sss | 12:45.30.500 |

## Related fields

* [DateTime](/docs/product-docs/fields/field-types/date-time-based/date-time)
* [Date](/docs/product-docs/fields/field-types/date-time-based/date)
* [Time](/docs/product-docs/fields/field-types/date-time-based/time)


# Last Modified Time
URL: /docs/product-docs/fields/field-types/date-time-based/last-modified-time

This article explains how to create & work with a last modified time field.



Since version v0.204.0 (Jan 2024), NocoDB internally captures the time when record was modified. This information is stored as a system field in the database & is hidden in the table by default. To view this information on the UI, you can either enable `Show System Fields` OR create a `Last Modified Time` field manually by following the steps below.

Default system field can be only hidden from UI. It cannot be modified, duplicated or deleted.

<Callout type="note">
  * When connected to an external database, `LastModifiedTime` field is not created automatically. You can create a `LastModifiedTime` field manually by following the steps below.
  * `LastModifiedTime` field is empty indicates
    * the record predates the `LastModifiedTime` feature (v0.204.0, Jan 2024). Prior to this feature release, it was possible to remove the `LastModifiedTime` field from the table.
    * the record was never modified.
    * external database connection : information is captured only after the field is explicitly created.
</Callout>

## Create a `LastModifiedTime` field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `LastModifiedTime` from the dropdown.
4. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

## Cell display

`LastModifiedTime` field is displayed as a read-only field in the table view. It is displayed as a date & time string in the format `DD MMM YYYY, HH:mm`.

## Related fields

* [Created Time](/docs/product-docs/fields/field-types/date-time-based/created-time)


# Time
URL: /docs/product-docs/fields/field-types/date-time-based/time

This article explains how to create & work with a Time field.



`Time` field type is used to store time values in a single field. Time formats supported by NocoDB are listed in the table below.

## Create a time field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional)
3. Select the field type as `Time` from the dropdown.
4. Configure default value (Optional)
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Supported time formats

Time format: HH:mm AM/PM (12-hour format)

[//]: # "| Format    | Example    |"

[//]: # "|-----------|------------|"

[//]: # "| HH:mm:ss  | 12:45:30   |"

[//]: # "| HH:mm     | 14:20      |"

## Related fields

* [DateTime](/docs/product-docs/fields/field-types/date-time-based/date-time)
* [Date](/docs/product-docs/fields/field-types/date-time-based/date)
* [Duration](/docs/product-docs/fields/field-types/date-time-based/duration)


# Array functions
URL: /docs/product-docs/fields/field-types/formula/array-functions

This article explains various array functions that can be used in formula fields.

This cheat sheet provides a quick reference guide for various array functions commonly used in data analysis and programming. Each function is accompanied by its syntax, a sample usage, and a brief description.

## ARRAYSORT

The ARRAYSORT function sorts an array result from links or lookup.

#### Syntax

```plaintext
ARRAYSORT(array, ["asc" | "desc"])
```

#### Sample

```plaintext
ARRAYSORT({LookupField}, "desc")
```

#### Remark

This function sorts an array result given from links or lookup field.
The 2nd parameter is the sort order, "asc" or "desc" to sort the values ascending or descending, with "asc" as the default if not provided.

***

## ARRAYUNIQUE

The ARRAYUNIQUE function returns unique items from the given array.

#### Syntax

```plaintext
ARRAYUNIQUE(array)
```

#### Sample

```plaintext
ARRAYUNIQUE({Field})
```

#### Remark

This function removes duplicate values, leaving only unique items from the given array.

***

## ARRAYCOMPACT

The ARRAYCOMPACT function removes null and empty from result.

#### Syntax

```plaintext
ARRAYCOMPACT(array)
```

#### Sample

```plaintext
ARRAYCOMPACT({Field})
```

#### Remark

This function removes null and empty, leaving only visible items from given array.

***

## ARRAYSLICE

The ARRAYSLICE function takes partial array values from start to (optional) end.

#### Syntax

```plaintext
ARRAYSLICE(array, start, [end])
```

#### Sample

```plaintext
ARRAYSLICE({Field}, 2, 3)
```

#### Remark

This function takes the array value partially, from start to (optional) end.
2nd parameter is the start index. Index start at 1.
3rd parameter is the end index. In the example above it'll take array value 2 and 3, giving a total 2 items.
Omitting end index will take the rest of items starting from start index.
Either start or end index cannot be negative. End index need to be bigger or equal with start index. Doing so will return empty as result.

***


# Conditional expressions
URL: /docs/product-docs/fields/field-types/formula/conditional-expressions

This article explains various conditional expressions that can be used in formula fields.

This cheat sheet provides a quick reference guide for various conditional expressions commonly used in data analysis and programming. Each expression is accompanied by its syntax, a sample usage, and a brief description.

## IF

The IF function in programming and spreadsheet formulas provides a way to perform conditional operations. It evaluates a condition and returns a value if the condition is `TRUE`, or another value if the condition is `FALSE`.

#### Syntax

```markdown
IF(expr, successCase, elseCase)
```

#### Sample

```markdown
IF({field} > 1, Value1, Value2)

Output
- `Value1` if `{field} > 1` evaluates to TRUE
- `Value2` otherwise
```

## SWITCH

The SWITCH function is a versatile tool for handling multiple cases. It evaluates the given expression (expr) against a series of patterns and returns the corresponding value of the first matching pattern. If none match, it returns the default value.

#### Syntax

```markdown
SWITCH(expr, [pattern, value, ..., default])
```

#### Sample

```markdown
SWITCH({field}, 1, 'One', 2, 'Two', '--')

Output
Switch case value based on the output of `{field}`:
- `'One'` if `{field} = 1`
- `'Two'` if `{field} = 2`
- `'--'` for the default case
```

## AND

The AND function is a logical operator that returns TRUE only if all its conditions are true.

#### Syntax

```markdown
AND(expr1, [expr2,...])
```

Comparison operators : `==`, `!=`, `>`, `<`, `>=`, `<=`

#### Sample

```markdown
AND({field} > 2, {field} < 10)

Output
TRUE if both `{field} > 2` and `{field} < 10` evaluate to TRUE
```

## OR

The OR function is another logical operator, returning TRUE if at least one of its conditions is true.

#### Syntax

```markdown
OR(expr1, [expr2,...])
```

Comparison operators : `==`, `!=`, `>`, `<`, `>=`, `<=`

#### Sample

```markdown
OR({field} > 2, {field} < 10)

Output
TRUE if at least one of the conditions `{field} > 2` or `{field} < 10` evaluates to TRUE
```

Logical operators, along with Numerical operators can be used to build conditional `expressions`.

Examples:

```
IF({marksSecured} > 80, "GradeA", "GradeB")  
```

```
SWITCH({quarterNumber},  
    1, 'Jan-Mar',
    2, 'Apr-Jun',
    3, 'Jul-Sep',
    4, 'Oct-Dec',
    'INVALID'
)
```

***


# Date functions
URL: /docs/product-docs/fields/field-types/formula/date-functions

This article explains various date functions that can be used in formula fields.

This cheat sheet provides a quick reference guide for various date functions commonly used in data analysis and programming. Each function is accompanied by its syntax, a sample usage, and a brief description.

## DATETIME\_DIFF

The DATETIME\_DIFF function calculates the difference between two dates in various units.

#### Syntax

```plaintext
DATETIME_DIFF(date1, date2, ["milliseconds" | "ms" | "seconds" | "s" | "minutes" | "m" | "hours" | "h" | "days" | "d" | "weeks" | "w" | "months" | "M" | "quarters" | "Q" | "years" | "y"])
```

#### Sample

```plaintext
DATETIME_DIFF("2022/10/14", "2022/10/15", "seconds") => -86400
```

#### Remark

This function compares two dates and returns the difference in the specified unit. Positive integers indicate that the second date is in the past compared to the first, and vice versa for negative values.

***

## DATEADD

The DATEADD function adds a specified value to a date or datetime.

#### Syntax

```plaintext
DATEADD(date | datetime, value, ["second" | "minute" | "hour" | "day" | "week" | "month" | "year"])
```

#### Sample

```plaintext
DATEADD('2022-03-14 10:00:00', 30, 'second')  => 2022-03-14 10:00:30
DATEADD('2022-03-14 10:00:00', 15, 'minute')  => 2022-03-14 10:15:00
DATEADD('2022-03-14 10:00:00', 2, 'hour')     => 2022-03-14 12:00:00
DATEADD('2022-03-14', 1, 'day')               => 2022-03-15
DATEADD('2022-03-14', 1, 'week')              => 2022-03-21
DATEADD('2022-03-14', 1, 'month')             => 2022-04-14
DATEADD('2022-03-14', 1, 'year')              => 2023-03-14
```

#### Conditional Example

```plaintext
IF(NOW() < DATEADD(date, 10, 'day'), "true", "false")
=> If the current date is less than the specified date plus 10 days, it returns true. Otherwise, it returns false.
```

#### Remark

This function supports date and datetime fields, can handle negative values, and works with units down to seconds.

***

## NOW

The NOW function returns the current time and day.

#### Syntax

```plaintext
NOW()
```

#### Sample

```plaintext
NOW() => 2022-05-19 17:20:43 (current date & time)
```

#### Conditional Example

```plaintext
IF(NOW() < date, "true", "false") => If the current date is less than the specified date, it returns true. Otherwise, it returns false.
```

#### Remark

This function provides the current time and day, supporting datetime fields and negative values.

***

## WEEKDAY

The WEEKDAY function returns the day of the week as an integer.

#### Syntax

```plaintext
WEEKDAY(date, [startDayOfWeek])
```

#### Sample

```plaintext
WEEKDAY(NOW()) => If today is Monday, it returns 0.
WEEKDAY(NOW(), "sunday") => If today is Monday, it returns 1.
```

#### Remark

Returns the day of the week as an integer between 0 and 6 (inclusive), with Monday as the default start day. The start day of the week can be optionally changed by specifying it as the second argument.

***

## DATESTR

The DATESTR function converts a date or datetime field into a string in "YYYY-MM-DD" format.

#### Syntax

```plaintext
DATESTR(date | datetime)
```

#### Sample

```plaintext
DATESTR('2022-03-14') => 2022-03-14
DATESTR('2022-03-14 12:00:00') => 2022-03-14
```

#### Remark

This function converts a date or datetime field into a string in "YYYY-MM-DD" format, ignoring the time part.

***

## DAY

The DAY function returns the day of the month as an integer.

#### Syntax

```plaintext
DAY(date | datetime)
```

#### Sample

```plaintext
DAY('2022-03-14') => 14
DAY('2022-03-14 12:00:00') => 14
```

#### Remark

This function returns the day of the month as an integer between 1 and 31 (inclusive). Note that the day information retrieved is based on the timezone of the server (GMT by default). If the browser timezone is different from the server timezone, the day value may differ.

***

## YEAR

The YEAR function returns the year as an integer.

#### Syntax

```plaintext
YEAR(date | datetime)
```

#### Sample

```plaintext
YEAR('2022-03-14') => 2022
YEAR('2022-03-14 12:00:00') => 2022
```

#### Remark

This function returns the year as an integer. The year information retrieved is based on the timezone of the server (GMT by default). If the browser timezone is different from the server timezone, the year value may differ.

***

## MONTH

The MONTH function returns the month of the year as an integer.

#### Syntax

```plaintext
MONTH(date | datetime)
```

#### Sample

```plaintext
MONTH('2022-03-14') => 3
MONTH('2022-03-14 12:00:00') => 3
```

#### Remark

This function returns the month of the year as an integer between 1 and 12 (inclusive). Note that the month information retrieved is based on the timezone of the server (GMT by default). If the browser timezone is different from the server timezone, the month value may differ.

***

## HOUR

The HOUR function returns the hour of the day as an integer.

#### Syntax

```plaintext
HOUR(datetime)
```

#### Sample

```plaintext
HOUR('2022-03-14 12:00:00') => 12
```

#### Remark

This function returns the hour of the day as an integer between 0 and 23 (inclusive). Hour information retrieved is based on a 24-hour clock & will be based on the timezone of the server (GMT by default). Note that, if browser timezone is different from the server timezone, the hour value may differ.

***


# Formatting Formula Results
URL: /docs/product-docs/fields/field-types/formula/formula-result-formatting

This article explains how to format the output of formulas in NocoDB, covering various formatting options based on the result type.



Formatting the output of formulas allows you to tailor how your data is displayed based on the type of result. Various formatting options are available to ensure that your data is presented in the most useful and visually appealing way.

<img alt="image" src={__img0} placeholder="blur" />

## Numeric Formats

<img src="/img/v2/fields/numeric-format.png" alt="image" width="400" />

### Decimal

The `Decimal format` is used to display results with a specified number of decimal places, allowing you to define the precision.

### Currency

The `Currency format` is ideal for displaying monetary values, with the option to set and display a specific currency symbol.

### Percent

The `Percent format` displays results as a number and includes an option to configure it as a progress bar.

### Rating

The `Rating format` is ideal for ratings on a scale from 1 to 10. It allows you to customize the icon, color, and choose the maximum rating value within that range.

## Date Formats

<img src="/img/v2/fields/date-format.png" alt="image" width="400" />

### Date Time

The `Date Time format` displays both date and time values.

### Date

The `Date format` displays only the date values, with a wide range of date formats available.

### Time

The `Time format` displays the result in either 12-hour or 24-hour time format.

## Text Formats

<img src="/img/v2/fields/text-format.png" alt="image" width="400" />

### Email

The `Email format` is used to display results as clickable email links. When an email address is detected in the formula output, it will be formatted as a mailto link, allowing users to click and open their default email client to send an email.

### URL

The `URL format` is designed to display results as clickable web links. When a valid URL is recognized in the formula output, it will be formatted as a hyperlink, enabling users to click and navigate directly to the specified web address.

### Phone Number

The `Phone number format` is ideal for displaying the results as phone numbers.

## Boolean Format

<img src="/img/v2/fields/boolean-format.png" alt="image" width="400" />

### Checkbox

When NocoDB recognizes a formula's output as a Boolean result, you can apply the `Checkbox format` to display it in a manner similar to a checkbox field. You can customize icon and color as required.

***


# Formula
URL: /docs/product-docs/fields/field-types/formula/formula

This article explains how to create & work with a Formula field.





## Create a formula field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Formula` from the dropdown.
4. Insert required formula
5. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="tip">
  * You can use explicit numerical values/ strings as needed, e.g. `123` (numeric) or `"123"` (string).
  * You can reference field names in equation with `{}`, e.g. `{field name}`
  * Nested formula (formula equation referring to another formula field) is supported
</Callout>

<Callout type="info">
   Unlike other field types, formula cells cannot be modified by double-clicking since the value is generated based on the formula.


  <img alt="Formula Cell Read-only" src={__img1} placeholder="blur" />

   
</Callout>

## Supported formula functions

* [Numeric and Logical Operators](/docs/product-docs/fields/field-types/formula/operators)
* [Numeric Functions](/docs/product-docs/fields/field-types/formula/numeric-functions)
* [String Functions](/docs/product-docs/fields/field-types/formula/string-functions)
* [Date Functions](/docs/product-docs/fields/field-types/formula/date-functions)
* [Array Functions](/docs/product-docs/fields/field-types/formula/array-functions)
* [Generic Functions](/docs/product-docs/fields/field-types/formula/generic-functions)
* [JSON Functions](/docs/product-docs/fields/field-types/formula/json-functions)
* [Conditional Expressions](/docs/product-docs/fields/field-types/formula/conditional-expressions)

***


# Generic functions
URL: /docs/product-docs/fields/field-types/formula/generic-functions

This article explains system functions & miscellaneous functions that can be used in formula fields.

# System Functions

## RECORD\_ID

The `RECORD_ID` function returns the unique identifier of the record.

#### Syntax

```plaintext
RECORD_ID()
```

#### Sample

```plaintext
RECORD_ID() => 1
```

***


# JSON functions
URL: /docs/product-docs/fields/field-types/formula/json-functions

This article explains various JSON functions that can be used in formula fields.

This sheet provides a quick reference guide for various JSON functions commonly used in data analysis and programming. Each function is accompanied by its syntax, a sample usage, and a brief description.

## JSON\_EXTRACT

The `JSON_EXTRACT` function extracts a value from a JSON string using a jq-like syntax.

#### Syntax

```plaintext
JSON_EXTRACT(json_string, path)
```

#### Sample

```plaintext
JSON_EXTRACT('{"a": {"b": "c"}}', '.a.b') => "c"
JSON_EXTRACT({json_column}, '.key')
```

#### Remark

* `json_string` must be a valid JSON string.
* `path` follows jq-like dot notation (e.g., `.a.b` to access nested values).
* Returns the extracted value as a string.

***


# Numeric functions
URL: /docs/product-docs/fields/field-types/formula/numeric-functions

This article explains various numeric functions that can be used in formula fields.

This cheat sheet provides a quick reference guide for various mathematical functions commonly used in data analysis and programming. Each function is accompanied by its syntax, a sample usage, and a brief description.

***

## ABS

The ABS function returns the distance of the number from zero on the number line, ensuring that the result is non-negative.

#### Syntax

```plaintext
ABS(number)
```

#### Sample

```plaintext
ABS(10.35) => 10.35
ABS(-15) => 15
```

***

## ADD

The ADD function computes the total of multiple numbers provided as arguments.

#### Syntax

```plaintext
ADD(number1, [number2, ...])
```

#### Sample

```plaintext
ADD(5, 7) => 12
ADD(-10, 15, 20) => 25
```

***

## AVG

The AVG function calculates the mean of a set of numerical values.

#### Syntax

```plaintext
AVG(number1, [number2, ...])
```

#### Sample

```plaintext
AVG(10, 20, 30) => 20
AVG(-5, 5) => 0
```

***

## CEILING

The CEILING function rounds a number up to the nearest integer greater than or equal to the input.

#### Syntax

```plaintext
CEILING(number)
```

#### Sample

```plaintext
CEILING(8.75) => 9
CEILING(-15.25) => -15
```

***

## COUNT

The COUNT function calculates the number of numeric arguments provided.

#### Syntax

```plaintext
COUNT(number1, [number2, ...])
```

#### Sample

```plaintext
COUNT(1, 2, "abc", 3) => 3
COUNT(-5, 0, "$abc", 5) => 3
```

***

## COUNTA

The COUNTA function counts the number of non-empty arguments provided.

#### Syntax

```plaintext
COUNTA(value1, [value2, ...])
```

#### Sample

```plaintext
COUNTA(1, "", "text") => 2
COUNTA("one", "two", "three") => 3
```

***

## COUNTALL

The COUNTALL function calculates the total number of arguments, both numeric and non-numeric.

#### Syntax

```plaintext
COUNTALL(value1, [value2, ...])
```

#### Sample

```plaintext
COUNTALL(1, "", "text") => 3
COUNTALL("one", "two", "three") => 3
```

***

## EVEN

The EVEN function rounds positive values up to the nearest even number and negative values down to the nearest even number.

#### Syntax

```plaintext
EVEN(number)
```

#### Sample

```plaintext
EVEN(7) => 8
EVEN(-5) => -6
```

***

## EXP

The EXP function returns 'e' raised to the power of a given number.

#### Syntax

```plaintext
EXP(number)
```

#### Sample

```plaintext
EXP(2) => 7.38905609893065
EXP(-1) => 0.36787944117144233
```

***

## FLOOR

The FLOOR function rounds a number down to the nearest integer.

#### Syntax

```plaintext
FLOOR(number)
```

#### Sample

```plaintext
FLOOR(8.75) => 8
FLOOR(-15.25) => -16
```

***

## INT

The INT function truncates the decimal part, returning the integer portion of a number.

#### Syntax

```plaintext
INT(number)
```

#### Sample

```plaintext
INT(8.75) => 8
INT(-15.25) => -15
```

***

## LOG

The LOG function computes the logarithm of a number to a specified base. (default = e).

#### Syntax

```plaintext
LOG([base], number)
```

#### Sample

```plaintext
LOG(10, 100) => 2
LOG(2, 8) => 3
```

***

## MAX

The MAX function identifies the highest value from a set of numbers.

#### Syntax

```plaintext
MAX(number1, [number2, ...])
```

#### Sample

```plaintext
MAX(5, 10, 3) => 10
MAX(-10, -5, -20) => -5
```

***

## MIN

The MIN function identifies the lowest value from a set of numbers.

#### Syntax

```plaintext
MIN(number1, [number2, ...])
```

#### Sample

```plaintext
MIN(5, 10, 3) => 3
MIN(-10, -5, -20) => -20
```

***

## MOD

The MOD function calculates the remainder when dividing (integer division) one number by another.

#### Syntax

```plaintext
MOD(number1, number2)
```

#### Sample

```plaintext
MOD(10, 3) => 1
MOD(-15, 4) => -3
```

***

## ODD

The ODD function rounds positive values up to the nearest odd number and negative values down to the nearest odd number.

#### Syntax

```plaintext
ODD(number)
```

#### Sample

```plaintext
ODD(6) => 7
ODD(-5.5) => -7
```

***

## POWER

The POWER function raises a given base to a specified exponent.

#### Syntax

```plaintext
POWER(base, exponent)
```

#### Sample

```plaintext
POWER(2, 3) => 8
POWER(10, -2) => 0.01
```

***

## ROUND

The ROUND function is used to round a number to a specified number of decimal places (precision). Default value for precision is 0.

#### Syntax

```plaintext
ROUND(number, [precision])
```

#### Sample

```plaintext
ROUND(8.765, 2) => 8.77
ROUND(-15.123, 1) => -15.1
```

***

## ROUNDDOWN

The ROUNDDOWN function rounds a number down to a specified number of decimal places (precision). Default value for precision is 0.

#### Syntax

```plaintext
ROUNDDOWN(number, [precision])
```

#### Sample

```plaintext
ROUNDDOWN(8.765, 2) => 8.76
ROUNDDOWN(-15.123, 1) => -15.2
```

***

## ROUNDUP

The ROUNDUP function rounds a number up to a specified number of decimal places (precision). Default value for precision is 0.

#### Syntax

```plaintext
ROUNDUP(number, [precision])
```

#### Sample

```plaintext
ROUNDUP(8.765, 2) => 8.77
ROUNDUP(-15.123, 1) => -15.1
```

***

## SQRT

The SQRT function calculates the square root of a given number.

#### Syntax

```plaintext
SQRT(number)
```

#### Sample

```plaintext
SQRT(25) => 5
SQRT(2) => 1.4142135623730951
```

***

## VALUE

The VALUE function is used to extract the numeric value from a string (after handling `%` or `-` accordingly).

#### Syntax

```plaintext
VALUE(text)
```

#### Sample

```plaintext
VALUE("123$") => 123
VALUE("USD -45.67") => -45.67
```

***


# Numeric and Logical operators
URL: /docs/product-docs/fields/field-types/formula/operators

This article explains various numeric and logical operators that can be used in formula fields.

### Numeric operators

| Operator | Sample                    | Description                      |
| -------- | ------------------------- | -------------------------------- |
| `+`      | `{field1} + {field2} + 2` | Addition of numeric values       |
| `-`      | `{field1} - {field2}`     | Subtraction of numeric values    |
| `*`      | `{field1} * {field2}`     | Multiplication of numeric values |
| `/`      | `{field1} / {field2}`     | Division of numeric values       |

<Callout type="info">
  To change the order of arithmetic operation, you can use round bracket parenthesis ().
  Example: 

  `({field1} + ({field2} * {field3}) / (3 - {field4} ))`

   
</Callout>

### Logical operators

| Operator | Sample                 | Description              |
| -------- | ---------------------- | ------------------------ |
| `<`      | `{field1} < {field2}`  | Less than                |
| `>`      | `{field1} > {field2}`  | Greater than             |
| `<=`     | `{field1} <= {field2}` | Less than or equal to    |
| `>=`     | `{field1} >= {field2}` | Greater than or equal to |
| `==`     | `{field1} == {field2}` | Equal to                 |
| `!=`     | `{field1} != {field2}` | Not equal to             |

### String operators

| Operator | Sample                | Description          |
| -------- | --------------------- | -------------------- |
| `&`      | `{field1} & {field2}` | String concatenation |

***


# String functions
URL: /docs/product-docs/fields/field-types/formula/string-functions

This article explains various string functions that can be used in formula fields.

This cheat sheet provides a quick reference guide for various string based functions commonly used in data analysis and programming. Each function is accompanied by its syntax, a sample usage, and a brief description.

## CONCAT

The CONCAT function concatenates one or more strings into a single string.

#### Syntax

```plaintext
CONCAT(text, [text,...])
```

#### Sample

```plaintext
CONCAT('John', ' ', 'Doe') => 'John Doe'
```

## LEFT

The LEFT function retrieves the first 'n' characters specified from the beginning of the input string.

#### Syntax

```plaintext
LEFT(text, count)
```

#### Sample

```plaintext
LEFT('123-456-7890', 3) => '123'
```

## LEN

The LEN function calculates and returns the total number of characters present in the provided string.

#### Syntax

```plaintext
LEN(text)
```

#### Sample

```plaintext
LEN('Product Description') => 19
```

## LOWER

The LOWER function transforms all characters in the input string to lowercase

#### Syntax

```plaintext
LOWER(text)
```

#### Sample

```plaintext
LOWER('User INPUT') => 'user input'
```

## MID

The MID function retrieves a substring from the input string starting at the specified position and extending for the specified count of characters.

#### Syntax

```plaintext
MID(text, position, [count])
```

#### Sample

```plaintext
MID('This is a sentence', 5, 3) => 'is '
```

## REGEX\_EXTRACT

The REGEX\_EXTRACT function searches the input string for the first occurrence of the specified regular expression pattern and returns the matched substring.

#### Syntax

```plaintext
REGEX_EXTRACT(text, pattern)
```

#### Sample

```plaintext
REGEX_EXTRACT('Error: Something went wrong', 'Error: (.*)') => 'Something went wrong'
```

## REGEX\_MATCH

The REGEX\_MATCH function evaluates whether the input string matches the specified regular expression pattern, returning 1 if there is a match and 0 if there is no match.

#### Syntax

```plaintext
REGEX_MATCH(text, pattern)
```

#### Sample

```plaintext
REGEX_MATCH('123-45-6789', '\d{3}-\d{2}-\d{4}') => 1
```

## REGEX\_REPLACE

The REGEX\_REPLACE function identifies all occurrences of the specified regular expression pattern in the input string and substitutes them with the provided replacement string.

#### Syntax

```plaintext
REGEX_REPLACE(text, pattern, replacer)
```

#### Sample

```plaintext
REGEX_REPLACE('Replace all bugs', 'bug', 'feature') => 'Replace all features'
```

## REPEAT

The REPEAT function duplicates the provided string the specified number of times, facilitating the creation of repeated patterns or sequences.

#### Syntax

```plaintext
REPEAT(text, count)
```

#### Sample

```plaintext
REPEAT('😃', 3) => '😃😃😃'
```

## REPLACE

The REPLACE function identifies all instances of a particular substring within the given string and substitutes them with another specified substring.

#### Syntax

```plaintext
REPLACE(text, srchStr, rplcStr)
```

#### Sample

```plaintext
REPLACE('Replace old text', 'old', 'new') => 'Replace new text'
```

## RIGHT

The RIGHT function retrieves the last 'n' characters from the end of the input string, allowing you to extract a substring starting from the right.

#### Syntax

```plaintext
RIGHT(text, n)
```

#### Sample

```plaintext
RIGHT('file_name.txt', 3) => 'txt'
```

## SEARCH

The SEARCH function identifies the position of the specified substring within the input string, returning the index if found, and 0 otherwise.

#### Syntax

```plaintext
SEARCH(text, srchStr)
```

#### Sample

```plaintext
SEARCH('user@example.com', '@') => 5
```

## SUBSTR

The SUBSTR function extracts a substring from the input string, starting at the specified position and optionally extending for the specified count of characters.

#### Syntax

```plaintext
SUBSTR(text, position, [count])
```

#### Sample

```plaintext
SUBSTR('Extract this text', 9, 4) => 'this'
```

## TRIM

The TRIM function eliminates any leading or trailing whitespaces from the input string.

#### Syntax

```plaintext
TRIM(text)
```

#### Sample

```plaintext
TRIM('   Trim this   ') => 'Trim this'
```

## UPPER

The UPPER function transforms all characters in the input string to uppercase.

#### Syntax

```plaintext
UPPER(text)
```

#### Sample

```plaintext
UPPER('title') => 'TITLE'
```

## URL

The URL function checks if the input string is a valid URL and converts it into a hyperlink

#### Syntax

```plaintext
URL(text)
```

#### Sample

```plaintext
URL('https://www.example.com') => a clickable link for https://www.example.com
```

## URLENCODE

The URLENCODE function percent-encodes special characters in a string so it can
be substituted as a query parameter into a URL.

It is similar to JavaScript `encodeURIComponent()` function, except it encodes
only characters that have a special meaning according to RFC 3986 section 2.2
and also percent signs and spaces; other characters such as letters from
non-Latin alphabets will not be encoded. Like `encodeURIComponent()`, it should
be used only for encoding URL components, not whole URLs.

#### Syntax

```plaintext
URLENCODE(text)
```

#### Sample

```plaintext
'https://example.com/q?param=' & URLENCODE('Hello, world')
=> 'https://example.com/q?param=Hello%2C%20world'
```

## ISBLANK

The ISBLANK function checks if a given input is not empty or null, returning FALSE if the input has a value, and TRUE otherwise.

#### Syntax

```plaintext
ISBLANK(text)
```

#### Sample

```plaintext
ISBLANK('') => true
ISBLANK('Hello') => false
```

## ISNOTBLANK

The ISNOTBLANK function checks if a given input is not empty or null, returning TRUE if the input has a value, and FALSE otherwise.

#### Syntax

```plaintext
ISNOTBLANK(text)
```

#### Sample

```plaintext
ISNOTBLANK('') => false
ISNOTBLANK('Hello') => true
```

***


# Auto Number
URL: /docs/product-docs/fields/field-types/identifier-types/auto-number

This article explains how to create and use an Auto Number field.

The **Auto Number** field automatically generates a unique, sequential number for each record in your table. Numbers start at 1 and increment by 1 for every new record added. This field is useful when you need simple, human-readable sequential identifiers — such as ticket numbers, invoice numbers, or order IDs — without relying on the internal primary key.

<Callout type="info">
  Auto Number is available on 

  **NocoDB Cloud**

   (Plus plan and above) and 

  **Self-hosted Enterprise Edition**

  .
</Callout>

<Callout type="warning">
  For external database connections, Auto Number fields are supported only with 

  **PostgreSQL**

   databases.
</Callout>

## Create an Auto Number field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field (Optional).
3. Select **Auto Number** from the list of field types.
4. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  Auto Number fields have no configuration options. A sequential value is generated automatically for each record — there is nothing to configure beyond the field name.
</Callout>

## Cell display

The **Auto Number** field appears as a read-only numeric cell. Values are auto-generated and cannot be edited or pasted into.

{/* Screenshot: Auto Number cell in grid view showing sequential values */}

{/* ![Auto Number cell display](/img/v2/fields/types/id-based/auto-number.png) */}

## Key behaviours

### Read-only

Auto Number values are generated automatically and cannot be manually edited, pasted, or overridden. Attempts to update an Auto Number value via the UI or API are silently ignored — the original value is preserved.

### Sequential numbering

Values are assigned sequentially starting from 1, incrementing by 1 for each new record. The underlying PostgreSQL sequence ensures that each value is unique. Deleting a record does **not** recycle its number — the sequence continues from the highest value ever assigned.

### Backfill on creation

When you add an Auto Number field to a table that already contains records, all existing records are automatically backfilled with sequential numbers (1, 2, 3, ...). The numbering follows the row order defined in the current view — if a sort is applied, the sorted order determines which record receives which number. New records inserted after the backfill continue the sequence from the next available number.

### Type conversion

An existing **Number** or **Single line text** field can be converted to an Auto Number field. When converted, the original values are replaced with sequential numbers (1, 2, 3, ...) based on the row order in the current view.

### Not available in forms

Since Auto Number values are system-generated, Auto Number fields do not appear in form views. Values are assigned automatically when the form submission creates a new record.

## Filtering Auto Number fields

Auto Number fields support numeric filter operations.

| Filter operation    | Description                                        |
| ------------------- | -------------------------------------------------- |
| is equal            | Matches the exact number                           |
| is not equal        | Excludes the exact number                          |
| is greater than     | Matches records greater than the specified value   |
| is less than        | Matches records less than the specified value      |
| is greater or equal | Matches records greater than or equal to the value |
| is less or equal    | Matches records less than or equal to the value    |
| is null             | Matches records with no value                      |
| is not null         | Matches records that have a value                  |

## Sorting Auto Number fields

Auto Number fields can be sorted in ascending or descending order. Since values are numeric and sequential, sorting by this field effectively orders records by their creation sequence.

## Limitations

* **PostgreSQL only**: Auto Number fields require a PostgreSQL database. They are not available when using MySQL, SQLite, or other database backends.
* **Not configurable**: The start number, increment value, prefix, and suffix cannot be customized. Values always start at 1 and increment by 1.
* **No manual editing**: Values cannot be manually set or modified after creation.
* **No copy-paste**: You cannot paste values into an Auto Number field.

***


# UUID
URL: /docs/product-docs/fields/field-types/identifier-types/uuid

This article explains how to create and use a UUID field.



The **UUID** (Universally Unique Identifier) field automatically generates a unique identifier (UUID v4) for each record. UUIDs are 128-bit values represented as 36-character strings in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (e.g., `31c46437-0bb9-4072-bf7a-40cd7aebcae3`). They are useful when you need globally unique, non-sequential identifiers for your records.

<Callout type="info">
  UUID is available on 

  **NocoDB Cloud**

   (all plans) and 

  **Self-hosted Enterprise Edition**

  .
</Callout>

<Callout type="warning">
  For external database connections, UUID fields are supported only with 

  **PostgreSQL**

   databases.
</Callout>

## Create a UUID field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field (Optional).
3. Select **UUID** from the list of field types.
4. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  UUID fields have no configuration options. A unique value is generated automatically for each record — there is nothing to configure beyond the field name.
</Callout>

## Cell display

The **UUID** field appears as a read-only text cell. Values are auto-generated when a new record is created and cannot be edited or pasted into.

{/* Screenshot: UUID cell in grid view showing generated values */}

<img alt="UUID cell display" src={__img0} placeholder="blur" />

## Key behaviours

### Read-only

UUID values are generated automatically by the database and cannot be manually edited, pasted, or overridden. Attempting to edit a UUID cell will display a read-only warning.

### Unique constraint

Every UUID field has a unique constraint enforced at the database level. This guarantees that no two records in the same table will share the same UUID value.

### Auto-generated on record creation

When a new record is added to the table, a UUID value is automatically assigned using PostgreSQL's `gen_random_uuid()` function. There is no need to manually populate the field.

### Not available in forms

Since UUID values are system-generated, UUID fields do not appear in form views. Values are assigned automatically when the form submission creates a new record.

## Filtering UUID fields

UUID fields support text-based filter operations. You can filter using full or partial UUID values.

| Filter operation | Description                                    |
| ---------------- | ---------------------------------------------- |
| is equal         | Matches the exact UUID string                  |
| is not equal     | Excludes the exact UUID string                 |
| is like          | Matches records containing the specified text  |
| is not like      | Excludes records containing the specified text |

{/* Screenshot: Filter dialog with UUID field selected */}

{/* ![UUID filtering](/img/v2/fields/types/identifier/uuid-filter.png) */}

<Callout type="info">
  You can filter using partial UUID values. For example, filtering with 

  `is like`

   and the value 

  `31c46`

   will match any UUID that contains that substring.
</Callout>

## Sorting UUID fields

UUID fields can be sorted in ascending or descending order. Sorting is performed on the text representation of the UUID, which means it follows lexicographic (alphabetical) order rather than any chronological sequence.

## Duplicating a table with UUID fields

When you duplicate a table that contains UUID fields, the UUID column structure is preserved in the new table. However, **new UUID values are generated** for all records in the duplicated table — the original values are not copied over.

## Limitations

* **PostgreSQL only**: UUID fields require a PostgreSQL database. They are not available when using MySQL, SQLite, or other database backends.
* **No default value configuration**: The default value (`gen_random_uuid()`) is set automatically and cannot be changed.
* **No copy-paste**: You cannot paste values into a UUID field.

***


# Link to Another Record
URL: /docs/product-docs/fields/field-types/links-based/link-to-another-record

This article explains how to create & work with a Link to Another Record field.

























`Link to Another Record` field type is used to establish relationships between tables & create links to other records.
NocoDB supports the following types of relations:

* `One-to-Many` - A record in one table can link to multiple records in another table.
  * Example: A `Country` can have multiple `Cities`.
* `Many-to-One` - Multiple records in one table link to a single record in another table.
  * Example: A `City` belongs to a `Country`.
* `Many-to-Many` - Multiple records in both tables can link to each other.
  * Example: A `Student` can have multiple `Subjects` & a `Subject` can have multiple `Students`.
* `One-to-One` - A record in one table links to exactly one record in another table.
  * Example: A `Country` has one `Capital`.

<Callout type="note">
  `One-to-Many` and `Many-to-One` are also commonly referred to as `Has-Many` and `Belongs-to` respectively.
</Callout>

<Callout type="note">
  * Links can be created only between tables in the same database.
  * Self-referencing links are supported. (Link to the same table)
  * For every `One-to-Many` relation defined, NocoDB augments a `Many-to-One` relationship field in the related table automatically.
</Callout>

## Create a link field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Link to Another Record` from the dropdown.
4. Select the relation type: `One-to-One`, `One-to-Many`, `Many-to-One`, OR `Many-to-Many`.
5. Select the table to which the relation is to be established with.
6. Click on `Save Field` button.

{/* TODO: Add screenshot of LTAR field creation UI */}

You can control record visibility in the `Link records` modal by limiting the records available for selection. [Read more](#limit-record-selection)

### Cell display

The cell displays linked records as chips, showing the primary display value of each linked record.

<img alt="image" src={__img0} placeholder="blur" />

Clicking on the expand icon will open a `Linked Records` modal with the full list of links & associated additional information.

### List linked records

<img alt="image" src={__img1} placeholder="blur" />

List of linked records will appear as a dropdown containing linked records as cards. A brief note about the modal components:

1. Search bar, to narrow down the list of linked records displayed
2. Icon represents the relation type. The count indicates the number of linked records
3. List (cards) of linked records
4. To view additional information (expanded record), hover on the card & click on the expand icon
5. Click on the `-` icon to unlink the record
6. Click on `+ New record` button to create and link a new record to the current one
7. Click on `Link more records` to link an existing record [Read more](#link-new-records)

### Link new records

Modal to add new links can be opened by

* Clicking on `+ Link more Records` button in the `Linked Records` modal
* Clicking on the `+` icon in the cell (appears on clicking on the cell)

<img alt="image" src={__img2} placeholder="blur" />

A brief note about the modal components:

1. Search bar, to narrow down the list of records displayed
2. Icon represents the relation type. The count indicates the number of linked records
3. List (cards) of records available for linking
4. To view additional information (expanded record) before linking, hover on the card & click on the expand icon
5. Click on the `+` icon to link the record
6. Click on `+ New record` button to create and link a new record to the current one

<Callout type="info">
  Multiple records can be linked at once
</Callout>

### Unlink records

To unlink a record, open the `Linked Records` modal & click on the `-` icon on the card of the record to be unlinked.

<Callout type="info">
  Multiple records can be unlinked at once
</Callout>

## Limit record selection

This feature enables users to restrict the records available for selection within the `Link records` modal. This can be achieved by two modes:

* Limit by view
* Limit by filter ☁

Note that,

* These options are not mutually exclusive & can be used together. When both are used, the records available for selection will be the **intersection of the records satisfying all conditions**.
* This feature only affects the records available for selection & **does not affect the existing links**.
* The limit is applied only on the **Link records** modal & does not restrict the link modification process via API, Copy-Paste or any other mechanisms.
* **Limit by filter** option is available only in cloud version.

### Limit by view

To limit the records available for selection based on a view, follow the steps below:

#### Steps

1. Enable `Limit record selection to view`
2. Select the view from the dropdown
3. Click on `Save Field` button

<img alt="image" src={__img3} placeholder="blur" />

In the example image above, the records available for selection will be limited to the records available in `Trailers` view.

Note that,

* Only one view can be selected at a time.
* Deleting the view associated with the link field will disable the limit by view option.
* Change in filters within the view will also reflect records available for selection during linking.

### Limit by filter ☁

To limit the records available for selection based on filters, follow the steps below:

#### Steps

1. Enable `Limit record selection by filter`
2. Configure filter

* Click on `Add filter` button.
* Select the field, operator
* Configure value

3. Click on `Save Field` button

<img alt="image" src={__img4} placeholder="blur" />

In the example image above, the records available for selection will be limited to the records available in `Trailers` view where `rating` is `PG`.

Note that,

* Multiple filters can be added.
* Deleting the field associated with the link field will disable associated filters.

#### Filter Type

Conditions in the filter can be of two types: Static & Dynamic.

* **Static condition**: Filter value is a constant value.
* **Dynamic condition**: Filter value is a field value from the current record.

Use the ⚙️ icon to the right of the filter to toggle between static & dynamic filter values.

<img alt="image" src={__img5} placeholder="blur" />
<img alt="image" src={__img6} placeholder="blur" />

Note that, it's allowed to have a mix of static & dynamic conditions in the filter.

## Upgrade from Links (V1)

If your base has existing `Links` fields (the older field type that displayed only a count of linked records), you can upgrade them to `Link to Another Record` fields.

The upgrade option is available in two places:

* Right-click on a Links field header and select `Upgrade field`

<img alt="image" src={__img7} placeholder="blur" />

* Open the field editor — a banner will indicate that a newer version is available with an `Upgrade` button

<img alt="image" src={__img8} placeholder="blur" />

A confirmation dialog will appear before the upgrade is applied.

<img alt="image" src={__img9} placeholder="blur" />

<Callout type="warn">
  This change cannot be undone.
</Callout>

After upgrading:

* Your data will not be affected.
* The original field will show only the count of linked records (converted to a Rollup field).
* A new `Link to Another Record` field will be added next to it to display the actual linked records.

| Before upgrade                                       | After upgrade                                        |
| ---------------------------------------------------- | ---------------------------------------------------- |
| <img alt="image" src={__img10} placeholder="blur" /> | <img alt="image" src={__img11} placeholder="blur" /> |

## Related fields

* [Lookup](/docs/product-docs/fields/field-types/links-based/lookup)
* [Rollup](/docs/product-docs/fields/field-types/links-based/rollup)


# Links
URL: /docs/product-docs/fields/field-types/links-based/links

This article explains how to create & work with a Links field.

















<Callout type="warn">
  The `Links` field type is deprecated. New link fields are created as [Link to Another Record](/docs/product-docs/fields/field-types/links-based/link-to-another-record) fields. Existing Links fields can be [upgraded](/docs/product-docs/fields/field-types/links-based/link-to-another-record#upgrade-from-links-v1) to the new format.
</Callout>

`Links` field type is used to establish relationship between tables & create links to other records.
NocoDB supports following types of relations:

* `Has-Many` - A record in one table can have multiple records in another table.
  * Example: A `Country` can have multiple `Cities`.
* `Belongs-to` - Multiple records in one table can have a single record in another table.
  * Example: A `City` `Belongs-to` a `Country`.
* `Many-to-Many` - Multiple records in one table can have multiple records in another table.
  * Example: A `Student` can have multiple `Subjects` & a `Subject` can have multiple `Students`.

<Callout type="note">
  - Links can be created only between tables in the same database.
  - Self-referencing links are supported. (Link to the same table)
  - For every `Has-Many` relation defined, NocoDB augments `Belongs-to` relationship field in the adjacent table automatically
</Callout>

## Create a link field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Links` from the dropdown.
4. Select the relation type : `One-to-one`, `Has-Many`, OR `Many-to-Many`.
5. Select the table to which the relation is to be established with.
6. Advance settings: Configure label to be used for display in the cell. Defaults to `Link`, `Links` (Optional).
7. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

You can control record visibility in the `Link records` modal by limiting the records available for selection. [Read more](#limit-record-selection)

### Cell display

The cell will display number of links for a record to the related table.

<img alt="image" src={__img1} placeholder="blur" />

Clicking on the link-text will open a `Linked Records` modal with the list of links & associated additional information.

### List linked records

<img alt="image" src={__img2} placeholder="blur" />

List of linked records will appear as a dropdown containing linked records as cards. A brief note about the modal components:

1. Search bar, to narrow down the list of linked records displayed
2. Icon represents `Many-to-Many` relation. The count indicates the number of linked records
3. List (cards) of linked records
4. To view additional information (expanded record), hover on the card & click on the `<>` icon
5. Click on the `-` icon to unlink the record
6. Click on `+ New record` button to create and link a new record to the current one
7. Click on `Link more records` to link an existing record [Read more](#link-new-records)
8. Pagination bar

### Link new records

Modal to add new links can be opened by

* Clicking on `+ Link more Records` button in the `Linked Records` modal
* Clicking on the `+` icon in the cell (appears on clicking on the cell)

<img alt="image" src={__img3} placeholder="blur" />

A brief note about the modal components:

1. Search bar, to narrow down the list of records displayed
2. Icon represents `Many-to-Many` relation. The count indicates the number of linked records
3. List (cards) of records available for linking
4. To view additional information (expanded record) before linking, hover on the card & click on the `<>` icon
5. Click on the `+` icon to link the record
6. Click on `+ New record` button to create and link a new record to the current one
7. Pagination bar

<Callout type="info">
  Multiple records can be linked at once
</Callout>

### Unlink records

To unlink a record, open the `Linked Records` modal & click on the `-` icon on the card of the record to be unlinked.

<Callout type="info">
  Multiple records can be unlinked at once
</Callout>

## Limit record selection

This feature enables users to restrict the records available for selection within the `Link records` modal. This can be achieved by two modes:

* Limit by view
* Limit by filter ☁

Note that,

* These options are not mutually exclusive & can be used together. When both are used, the records available for selection will be the **intersection of the records satisfying all conditions**.
* This feature only affects the records available for selection & **does not affect the existing links**.
* The limit is applied only on the **Link records** modal & does not restrict the link modification process via API, Copy-Paste or any other mechanisms.
* **Limit by filter** option is available only in cloud version.

### Limit by view

To limit the records available for selection based on a view, follow the steps below:

#### Steps

1. Enable `Limit record selection to view`
2. Select the view from the dropdown
3. Click on `Save Field` button

<img alt="image" src={__img4} placeholder="blur" />

In the example image above, the records available for selection will be limited to the records available in `Trailers` view.

Note that,

* Only one view can be selected at a time.
* Deleting the view associated with links field will disable the limit by view option.
* Change in filters within the view will also reflect records available for selection during linking.

### Limit by filter ☁

To limit the records available for selection based on filters, follow the steps below:

#### Steps

1. Enable `Limit record selection by filter`
2. Configure filter

* Click on `Add filter` button.
* Select the field, operator
* Configure value

3. Click on `Save Field` button

<img alt="image" src={__img5} placeholder="blur" />

In the example image above, the records available for selection will be limited to the records available in `Trailers` view where `rating` is `PG`.

Note that,

* Multiple filters can be added.
* Deleting the field associated with links field will disable associated filters.

#### Filter Type

Conditions in the filter can be of two types: Static & Dynamic.

* **Static condition**: Filter value is a constant value.
* **Dynamic condition**: Filter value is a field value from the current record.

Use the ⚙️ icon to the right of the filter to toggle between static & dynamic filter values.

<img alt="image" src={__img6} placeholder="blur" />
<img alt="image" src={__img7} placeholder="blur" />

Note that, it's allowed to have a mix of static & dynamic conditions in the filter.

## Related fields

* [Lookup](/docs/product-docs/fields/field-types/links-based/lookup)
* [Rollup](/docs/product-docs/fields/field-types/links-based/rollup)


# Lookup
URL: /docs/product-docs/fields/field-types/links-based/lookup

This article explains how to create & work with a Lookup field.



`Lookup` fields help bring additional field information from related table into the current table. This is useful when you want to display additional information about a record in a table. For example, if you have a table of `Orders` and a table of `Customers`, you can use a `Lookup` field to display the customer's name and address in the `Orders` table.

<Callout type="note">
  Lookup fields are read-only. You cannot edit the values in a lookup field.
</Callout>

## Create a Lookup Field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Lookup` from the dropdown.
4. Select the link field from the dropdown. This is the field that links the current table to the related table.
5. Select the field for display from the dropdown. This is the field that will be displayed in the current table.
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

## Conditional Lookup ☁

<Callout type="note">
  Availability: NocoDB cloud plus plan onwards & self-hosted enterprise edition.
</Callout>

By default, a Lookup field pulls in **all** linked records from the related table. However, in many cases, you may want to display only a subset of those records — for example, only recent entries or records above a certain threshold.

To achieve this, you can enable the option:
**Only include linked records that meet specific conditions**

<img src="/img/v2/fields/types/lookup-filter.png" style={{ width: "75%" }} />

This option allows you to filter the linked records based on criteria defined from fields in the related table. It helps tailor the Lookup field to show only the data that’s most relevant to your use case.

### Applying filters

1. Toggle ON **Only include linked records that meet specific conditions**.
2. Click **Add filter** to define one or more conditions using fields from the related table.
3. Use **Add filter group** to combine filters with AND/OR logic.
4. Click **Save Field** to apply.

## Similar links-based fields

* [Link to Another Record](/docs/product-docs/fields/field-types/links-based/link-to-another-record)
* [Rollup](/docs/product-docs/fields/field-types/links-based/rollup)


# Rollup
URL: /docs/product-docs/fields/field-types/links-based/rollup

This article explains how to create & work with a Rollup field.



`Rollup` fields are used to aggregate data from fields in the related table. Often used to calculate totals, averages, and other aggregate data.

## Create a Rollup Field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `Rollup` from the dropdown.
4. Select the link field from the dropdown. This is the field that links the current table to the related table.
5. Select the field for display from the dropdown. This is the field that will be displayed in the current table.
6. Select the aggregation function from the dropdown. This is the function that will be used to aggregate the data.
7. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Aggregation Functions

Here's a table with brief descriptions for each of the aggregation functions supported by NocoDB:

| Aggregation Function | Description                                             |
| -------------------- | ------------------------------------------------------- |
| Count                | Counts the number of records in a dataset.              |
| Minimum              | Retrieves the minimum value from a dataset.             |
| Maximum              | Retrieves the maximum value from a dataset.             |
| Average              | Calculates the average value in a dataset.              |
| Sum                  | Adds up all the values in a dataset.                    |
| Count Distinct       | Counts the number of distinct values in a dataset.      |
| Sum Distinct         | Adds up all the distinct values in a dataset.           |
| Average Distinct     | Calculates the average of distinct values in a dataset. |

## Conditional Rollup ☁

<Callout type="note">
  Availability: NocoDB cloud plus plan onwards & self-hosted enterprise edition.
</Callout>

Rollup fields are used to perform calculations—such as sum, average, count—on linked records from a related table. By default, the rollup includes **all** linked records. However, you can fine-tune the results by including only those records that meet specific criteria.

To do this, enable the option:
**Only include linked records that meet specific conditions**

<img src="/img/v2/fields/types/rollup-filter.png" style={{ width: "75%" }} />

This option allows you to apply filters to the linked records before the rollup calculation is performed. It’s particularly useful when you want to aggregate values conditionally—like summing revenue for a specific period or counting items that meet a threshold.

### Applying filters

1. Toggle ON **Only include linked records that meet specific conditions**.
2. Click **Add filter** to define the condition(s) using fields from the related table.
3. Use **Add filter group** to combine filters using AND/OR logic.
4. Click **Save Field** to apply.

## Similar links-based fields

* [Link to Another Record](/docs/product-docs/fields/field-types/links-based/link-to-another-record)
* [Lookup](/docs/product-docs/fields/field-types/links-based/lookup)


# Currency
URL: /docs/product-docs/fields/field-types/numerical/currency

This article explains how to create and use a Currency field.



The **Currency** field is a numerical field used to store monetary values. It provides additional options to configure the currency locale and symbol for display.

<Callout type="warning">
  Currency formatting is applied only for display. The stored value remains numerical for calculations and formulas.
</Callout>

## Create a Currency field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Currency** from the list of field types.
4. Configure **Currency Locale** (defaults to `en-US`).
5. Configure **Currency Symbol** (defaults to `$`).
6. (Optional) Set a default value for the field and add a description.
7. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

## Cell display

The **Currency** field appears as a numeric cell with the configured currency symbol and formatting.

<img alt="Cell display" src={__img0} placeholder="blur" />

## Supported locales

NocoDB supports locale codes based on the [ISO639-1 standard](https://www.npmjs.com/package/locale-codes#locale-list).

<Callout type="info">
  Ensure the correct locale is selected to apply region-specific number formatting (e.g., 

  **en-US**

  , 

  **fr-FR**

  ).
</Callout>

## Supported currencies

The **Currency** field supports a wide range of ISO 4217 currency codes, including but not limited to:

|     |     |     |     |     |     |
| --- | --- | --- | --- | --- | --- |
| AED | AFN | ALL | AMD | ANG | AOA |
| ARS | AUD | AWG | AZN | BAM | BBD |
| BDT | BGN | BHD | BIF | BMD | BND |
| BOB | BOV | BRL | BSD | BTN | BWP |
| BYR | BZD | CAD | CDF | CHE | CHF |
| CHW | CLF | CLP | CNY | COP | COU |
| CRC | CUP | CVE | CYP | CZK | DJF |
| DKK | DOP | DZD | EEK | EGP | ERN |
| ETB | EUR | FJD | FKP | GBP | GEL |
| GHC | GIP | GMD | GNF | GTQ | GYD |
| HKD | HNL | HRK | HTG | HUF | IDR |
| ILS | INR | IQD | IRR | ISK | JMD |
| JOD | JPY | KES | KGS | KHR | KMF |
| KPW | KRW | KWD | KYD | KZT | LAK |
| LBP | LKR | LRD | LSL | LTL | LVL |
| LYD | MAD | MDL | MGA | MKD | MMK |
| MNT | MOP | MRO | MTL | MUR | MVR |
| MWK | MXN | MXV | MYR | MZN | NAD |
| NGN | NIO | NOK | NPR | NZD | OMR |
| PAB | PEN | PGK | PHP | PKR | PLN |
| PYG | QAR | ROL | RON | RSD | RUB |
| RWF | SAR | SBD | SCR | SDD | SEK |
| SGD | SHP | SIT | SKK | SLL | SOS |
| SRD | STD | SYP | SZL | THB | TJS |
| TMM | TND | TOP | TRY | TTD | TWD |
| TZS | UAH | UGX | USD | USN | USS |
| UYU | UZS | VEB | VND | VUV | WST |
| XAF | XAG | XAU | XBA | XBB | XBC |
| XBD | XCD | XDR | XFO | XFU | XOF |
| XPD | XPF | XPT | XTS | XXX | YER |
| ZAR | ZMK | ZWD |     |     |     |

***


# Decimal
URL: /docs/product-docs/fields/field-types/numerical/decimal

This article explains how to create and use a Decimal field.



The **Decimal** field is a numerical field used to store decimal values. It is commonly used for data such as salary, price, or other values requiring fractional precision.

<Callout type="warning">
  NocoDB supports up to 8 digits of precision.
</Callout>

## Create a Decimal field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Decimal** from the list of field types.
4. Configure the **Precision** setting (up to 8 digits).
5. Toggle **Show thousands separator** to format large numbers with a thousand separator (e.g., 1,000.00 instead of 1000.00).
6. (Optional) Set a default value for the field and add a description.
7. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  The default precision is set to 1 digit.
</Callout>

## Cell display

The **Decimal** field appears as a numeric cell in the table, right-aligned for readability. Values are displayed with the configured number of decimal places. If the **Show thousands separator** option is enabled, large numbers will be formatted with a comma as the thousand separator.

<img alt="Number field cell display" src={__img0} placeholder="blur" />

***


# Number
URL: /docs/product-docs/fields/field-types/numerical/number

This article explains how to create and use a Number field.



The **Number** field is a numerical field used to store integer values. It is commonly used for data such as age, salary, price, or quantity.

<Callout type="warning">
  Supported range (JavaScript): -9,007,199,254,740,991 to 9,007,199,254,740,991
</Callout>

## Create a Number field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Number** from the list of field types.
4. (Optional) Toggle **Show thousands separator** to format large numbers with a thousand separator (e.g., 1,000 instead of 1000).
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  The Number field supports both positive and negative values.
</Callout>

## Cell display

The **Number** field appears as a numeric cell in the table. Its display aligns to the right by default for clarity and consistency when handling numerical data. If the **Show thousands separator** option is enabled, large numbers will be formatted with a comma as the thousand separator.

<img alt="Cell display" src={__img0} placeholder="blur" />

***


# Percent
URL: /docs/product-docs/fields/field-types/numerical/percent

This article explains how to create and use a Percent field.



The **Percent** field is a numerical field used to store percentage values. It is useful for data such as completion rates, discount percentages, or performance metrics.

<Callout type="warning">
  Values are entered as whole numbers and displayed with a percentage sign (e.g., 

  **75**

   is shown as 

  **75%**

  ).
</Callout>

## Create a Percent field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Percent** from the list of field types.
4. (Optional) Enable **Display as progress** to show the percentage as a progress bar.
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
   The 

  **Percent**

   field does not include a 

  `Show thousand separator`

   option.
</Callout>

## Cell display

The **Percent** field appears as a numeric cell in the table, right-aligned by default.

* When **Display as progress** is enabled, the value is represented as a progress bar.
* Without progress display, the value appears as a standard percentage.

<img alt="Cell display" src={__img0} placeholder="blur" />


# Multi select
URL: /docs/product-docs/fields/field-types/select-based/multi-select

This article explains how to create and use a Multi select field.









The **Multi select** field allows you to choose multiple options from a predefined list. It is useful for fields like skills, tags, or applicable categories.

## Create a Multi select field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Multi select** from the list of field types.
4. Click **Add option** to define available options.
5. (Optional) Set default values for the field from the defined options.
6. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="note">
   

  `✨✨✨`

   

  **NocoAI**

   can assist in generating options for your Multi select field. Click the 

  **Auto Suggest**

   button to get AI-generated suggestions based on your field name & existing options.
</Callout>

## Edit options

### Rename options

Click on the option text box to rename an option. Save changes using **Save field**.

### Configure colors

Assign background colors to options to visually distinguish them. For example, tag `Urgent` as red to highlight importance.
Click the **color** icon next to an option, select a color, and save changes.

<img alt="image" src={__img1} placeholder="blur" />

### Reorder options

Drag and drop options using the **drag** icon to reorder them. The new order is reflected in the dropdown inside cells.

<img alt="image" src={__img2} placeholder="blur" />

<Callout type="info">
  The order you define for options is preserved in the cell dropdown list.
</Callout>

### Delete options

Click the `x` icon to delete an option. Deleted options can be restored using the **undo** icon before saving.

<img alt="image" src={__img3} placeholder="blur" />

<Callout type="warning">
   Removing an option clears it from all cells where it was selected. If the deleted option was set as a default value, the default will be cleared. 
</Callout>

## Cell display

The **Multi select** field displays as a dropdown in table cells, showing the configured options with their respective colors. Multiple options can be selected for a single cell.

<img src="/img/v2/fields/types/multi-select/display.png" alt="display" style={{width: "80%"}} />

***


# Single select
URL: /docs/product-docs/fields/field-types/select-based/single-select

This article explains how to create and use a Single select field.









The **Single select** field allows you to choose one option from a predefined list. It is useful for fields like status, priority, or category.

## Create a Single select field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Single select** from the list of field types.
4. Click **Add option** to define available options.
5. (Optional) Set a default value for the field from the defined options.
6. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="note">
   

  `✨✨✨`

   

  **NocoAI**

   can assist in generating options for your Single select field. Click the 

  **Auto Suggest**

   button to get AI-generated suggestions based on your field name & existing options.
</Callout>

## Edit options

### Rename options

Click on the option text box to rename an option. Save changes using **Save field**.

### Configure colors

Assign background colors to options to visually distinguish them. For example, mark `High` as red to highlight urgency.
Click the **color** icon next to an option, select a color, and save changes.

<img alt="image" src={__img1} placeholder="blur" />

### Reorder options

Drag and drop options using the **drag** icon to reorder them. The new order is reflected in the dropdown inside cells.

<img alt="image" src={__img2} placeholder="blur" />

<Callout type="info">
  The order you define for options is preserved in the cell dropdown list.
</Callout>

### Delete options

Click the `x` icon to delete an option. Deleted options can be restored using the **undo** icon before saving.

<img alt="image" src={__img3} placeholder="blur" />

<Callout type="warning">
   Removing an option clears it from all cells where it was selected. If the deleted option was set as the default value, the default will be cleared. 
</Callout>

## Cell display

The **Single select** field displays as a dropdown in table cells, showing the configured options with their respective colors. Only one option can be selected at a time.

<img src="/img/v2/fields/types/select-based/display.png" alt="display" style={{width: "80%"}} />

***


# Email
URL: /docs/product-docs/fields/field-types/text-based/email

This article explains how to create and use an Email field.

The **Email** field is a text-based field designed specifically for storing email addresses. It is a specialized version of the **Single line text** field with the following enhancements:

* Optional validation to ensure values follow a valid email format
* Display of values as clickable email links

## Create an Email field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Email** as the field type.
4. (Optional) Enable validation by toggling the **Validate Email** option.
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add it to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="note">
  Validation only ensures the format is a valid email address; it does not verify whether the email address exists
</Callout>

***


# Long text
URL: /docs/product-docs/fields/field-types/text-based/long-text

This article explains how to create and use a Long text field.







The **Long text** field is a text-based field that supports multiple lines of text. It is ideal for storing extended content such as descriptions, notes, or comments.

<Callout type="warning">
  Limit: 100,000 characters
</Callout>

## Create a Long text field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Long text** from the list of field types.
4. (Optional) Enable **Rich text** formatting. Learn more [here](/docs/product-docs/fields/field-types/text-based/rich-text).
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add the field to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  Enter the default value without quotes. Use the 

  `Enter`

   key to add a new line.
</Callout>

## Cell display

The **Long text** field appears as a standard text cell in the table. The number of visible lines depends on the row height.

<img alt="image" src={__img0} placeholder="blur" />

Double-clicking the cell, or pressing the `Enter` key while the cell is selected, expands the editor to display more lines for inline editing.

<img alt="image" src={__img1} placeholder="blur" />

Alternatively, click the **Expand** icon in the cell to pop out a larger editor for easier editing. Pop-up editor can be resized by dragging its bottom-right corner & moved around by dragging its header.

<img alt="image" src={__img2} placeholder="blur" />

***


# Phone Number
URL: /docs/product-docs/fields/field-types/text-based/phonenumber

This article explains how to create and use a Phone number field.

The **Phone number** field is a text-based field designed for storing phone numbers. It provides an option to validate values to ensure they follow a valid phone number format.

## Create a Phone number field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **Phone number** as the field type.
4. (Optional) Enable validation by toggling the **Validate Phone number** option.
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add it to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="note">
  Validation only ensures the format is a valid phone number; it does not verify whether the number exists
</Callout>

***


# Rich text
URL: /docs/product-docs/fields/field-types/text-based/rich-text

This article explains how to create and use a Rich text field.





The **Rich text** field is an extension of the **Long text** field that supports text formatting. It allows you to style content with options such as bold, italic, underline, strikethrough, horizontal rules, ordered and unordered lists, code blocks, quotes, and more.

<Callout type="warning">
  Limit: 100,000 characters
</Callout>

## Create a Rich text field

1. Click the `+` icon to the right of the **Fields** header.
2. Enter a field name (optional).
3. Select **Long text** as the field type.
4. Enable the **Rich text** toggle.
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add it to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  Enter the default value without quotes. Use the 

  `Enter`

   key to add a new line.
</Callout>

## Cell display

In the table view, the **Rich text** field appears as a single-line cell. To view or edit the full content, click the **Expand** icon.

<img alt="image" src={__img0} placeholder="blur" />

## Formatting options

NocoDB supports Markdown syntax for formatting the text. Sections below explain various formatting options available in the rich text editor.

### Heading

To create a heading, prefix `#` symbol preceding your heading text. The number of # symbols employed will dictate the heading's hierarchy level and typeface size. Three levels of headings are supported.

```
# Heading 1
## Heading 2
### Heading 3
```

<img alt="image" src={__img1} placeholder="blur" />

### Text formatting

You can emphasise text with bold, italic, strikethrough or underline formatting options. Table below shows syntax, keyboard shortcut, example & output for each formatting option.

| Style         | Syntax                   | Keyboard shortcut      | Output                 |
| ------------- | ------------------------ | ---------------------- | ---------------------- |
| Bold          | `**bold text**`          | `Ctrl/Cmd + B`         | **bold text**          |
| Italic        | `*italicized text*`      | `Ctrl/Cmd + I`         | *italicized text*      |
| Strikethrough | `~~strikethrough text~~` | `Ctrl/Cmd + Shift + X` | ~~strikethrough text~~ |
| Underline     |                          | `Ctrl/Cmd + U`         | <u>underlined text</u> |

### Quote block

You can quote text with a `>`

**Usage**

```
normal text
> quoted text
```

**Display**

normal text

> quoted text

### Code block

Code block can be created by using (3 backticks) before & after the code.

**Usage**

````
```
This is a code block
```
````

**Display**

```
This is a code block
```

### Link

Use the **Link** option in the rich text toolbar to add inline links. Alternatively, you can use markdown syntax `[link text](URL)`.

### Bullet List

You can create an unordered list using the **Bulleted list** option in the toolbar or by starting lines with `-`, `+`, or `*`.

**Usage**

```
- Item 1
- Item 2

+ Item 1
+ Item 2

* Item 1
* Item 2
```

**Display**

* Item 1
* Item 2

- Item 1
- Item 2

* Item 1
* Item 2

<Callout type="info">
  You can create nested lists by using 

  `tab`

   key & 

  `shift + tab`

   key to indent & outdent the list items
</Callout>

### Numbered List

You can create an ordered list using the **Numbered list** option in the toolbar or by prefixing text with numbers.

**Usage**

```
1. Item 1
2. Item 2
```

**Display**

1. Item 1
2. Item 2

### Task list

You can create task lists using the **Task list** option in the toolbar or with `[ ]` and `[x]` for incomplete and completed tasks.

**Usage**

```
[ ] Item 1
[x] Item 2
```

**Display**

* [ ] Item 1
* [x] Item 2

***


# Single line text
URL: /docs/product-docs/fields/field-types/text-based/single-line-text

This article explains how to create & work with a Single line text field.

The **Single line text** field is used to store short, freeform text values. It is suitable for entries like names, titles, tags, or labels. This is the most commonly used field type for capturing simple text in a structured format. For storing longer text or multiple lines, consider using the [Long text](/docs/product-docs/fields/field-types/text-based/long-text) field instead.

<Callout type="warning">
  Limit: 100,000 characters
</Callout>

## Create a Single line text field

1. Click on the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select `Single line text` from the list of field types.
4. Optionally, you can set a default value for the field & add a description.
5. Click on `Save field` to add the field to your table.

Refer here for generic guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="info">
  Specify default value as is, without quotes
</Callout>

***


# URL
URL: /docs/product-docs/fields/field-types/text-based/url

This article explains how to create and use a URL field.

The **URL** field is a text-based field designed specifically for storing web addresses. It is a specialized version of the **Single line text** field with the following enhancements:

* Optional validation to ensure values follow a valid URL format
* Display of values as clickable links

## Create a URL field

1. Click the `+` icon next to the last field in your table.
2. Enter a name for the field.
3. Select **URL** as the field type.
4. (Optional) Enable validation by toggling the **Validate URL** option.
5. (Optional) Set a default value for the field and add a description.
6. Click **Save field** to add it to your table.

Refer to the general guidelines on [creating a field](/docs/product-docs/fields#create-a-field).

<Callout type="note">
  Validation only ensures the format is a valid URL; it does not verify whether the URL exists
</Callout>

***


# Created By
URL: /docs/product-docs/fields/field-types/user-based/created-by

This article explains how to create & work with a Created By field.



Since version v0.204.0 (Jan 2024), NocoDB internally captures the user who created a record. This information is stored as a system field in the database & is not included in the table by default. To view this information on the table, you can create a `Created By` field manually by following the steps below.

### Create a `Created By` field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `CreatedBy` from the dropdown.
4. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="note">
  * When connected to an external database, user creating record information is not captured automatically. You can create a `Created By` field manually by following the steps above. For external database connections, this field is not a system field & can be deleted.
  * `Created By` field is empty indicates the record either
    * predates the created by feature (v0.204.0, Jan 2024). Prior to this feature release, this information was not captured.
    * was created using shared form.
    * external database connection : information is captured only after the field is explicitly created.
</Callout>

### Cell display

`Created By` field is displayed as a read-only field in the table view. Displays email address of the user who created the record if the user has no display name set. If the user has a display name set, the display name is displayed.

### Current User Filter ☁

NocoDB allows you to filter views based on the currently logged-in user. This is particularly useful for creating personalized views that display records relevant to the user currently logged in. Find more details on how to filter by current user in the [Filtering records by current user](/docs/product-docs/table-operations/filter#filter-by-current-user-) section.

### Related fields

* [Last Modified By](/docs/product-docs/fields/field-types/user-based/last-modified-by)


# Last Modified By
URL: /docs/product-docs/fields/field-types/user-based/last-modified-by

This article explains how to create & work with a Last Modified By field.



Since version v0.204.0 (Jan 2024), NocoDB internally captures the user who last modified a record. This information is stored as a system field in the database & is not included in the table by default. To view this information on the table, you can create a `Last Modified By` field manually by following the steps below.

### Create a `Last Modified By` field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `LastModifiedBy` from the dropdown.
4. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

<Callout type="note">
  * When connected to an external database, user last modifying record information is not captured automatically. You can create a `Last Modified By` field manually by following the steps above. For external database connections, this field is not a system field & can be deleted.
  * `Last Modified By` field is empty indicates the record either
    * record was created & never modified.
    * predates the last modified by feature (v0.204.0, Jan 2024). Prior to this feature release, this information was not captured.
    * external database connection : information is captured only after the field is explicitly created.
  * `Last Modified By` field is not updated when a record is initially created (is initialized to NULL).
</Callout>

### Cell display

`Last Modified By` field is displayed as a read-only field in the table view. Displays email address of the user who last modified the record if the user has no display name set. If the user has a display name set, the display name is displayed.

### Current User Filter ☁

NocoDB allows you to filter views based on the currently logged-in user. This is particularly useful for creating personalized views that display records relevant to the user currently logged in. Find more details on how to filter by current user in the [Filtering records by current user](/docs/product-docs/table-operations/filter#filter-by-current-user-) section.

### Related fields

* [Created By](/docs/product-docs/fields/field-types/user-based/created-by)


# User
URL: /docs/product-docs/fields/field-types/user-based/user

This article explains how to create & work with a User field.





`User` field type allows you to assign a user from your current workspace to a record. For example, you can create a `Task` table with a `User` field type to assign a task to a user. You can also configure the field to allow assigning multiple users to a record.

## Create a User field

1. Click on `+` icon to the right of `Fields header`
2. On the dropdown modal, enter the field name (Optional).
3. Select the field type as `User` from the dropdown.
4. Configure `Allow adding multiple users` toggle field (Optional).
5. Configure default value (Optional)
6. Click on `Save Field` button.

<img alt="image" src={__img0} placeholder="blur" />

### Cell display

`User` field display is quite identical to `Select` field. It is displayed as a dropdown in the table view. Click on the dropdown to select a user. If `Allow adding multiple users` is enabled, you can select multiple users from the dropdown.

<img alt="image" src={__img1} placeholder="blur" />

<Callout type="note">
  * If a user is removed from workspace, the user will be removed from the dropdown list. If such user was assigned to a record already, the user will be displayed as is.
  * To remove a user from a record, click on the `x` icon next to the user name.
  * If display name is not set for a user, the user's email address will be displayed.
</Callout>

### Current User Filter ☁

NocoDB allows you to filter views based on the currently logged-in user. This is particularly useful for creating personalized views that display records relevant to the user currently logged in. Find more details on how to filter by current user in the [Filtering records by current user](/docs/product-docs/table-operations/filter#filter-by-current-user-) section.


# Changelog
URL: /docs/scripts/changelog

NocoDB Scripts API changelog and version history

This page documents all changes to the NocoDB Scripts API, including new features, improvements, bug fixes, and breaking changes.

## February 17, 2026

#### Links Field Enhancement

* **Links as LinkToAnotherRecord (LTAR) Support** - Links fields now return full linked record data instead of just counts
  * All record query methods automatically include complete linked record information (id and display value)
  * Applies to `table.selectRecordsAsync()`, `view.selectRecordsAsync()`, `table.selectRecordAsync()`, and `view.selectRecordAsync()`
  * For Has-Many (HM) and Many-to-Many (MM) relationships, linked records are now returned as `LazyRecordQueryResult` objects earlier used to return only counts.
  * For Belongs-To (BT) and One-to-One (OO) relationships, linked records are returned as complete record objects as before.
  * **Note:** This is automatically enabled for all scripts - no code changes required

***

## January 29, 2026

#### Script Settings Enhancement

* **Default Values for Configuration Items** - All `input.config` methods now support an optional `default` parameter
  * `input.config.table()` - Pre-select a table by ID: `default: 'tbl_abc123'`
  * `input.config.view()` - Pre-select a view by ID: `default: 'vw_xyz789'`
  * `input.config.field()` - Pre-select a field by ID: `default: 'fld_email456'`
  * `input.config.text()` - Pre-fill text input: `default: 'Weekly Report'`
  * `input.config.number()` - Pre-fill number input: `default: 7`
  * `input.config.select()` - Pre-select dropdown option: `default: 'medium'`
  * Default values are applied when users haven't provided a value, making scripts easier to use with sensible defaults

***

## October 03, 2025

#### Input Methods Enhancement

* **Default Values for `input.textAsync()`** - Added optional `defaultValue` parameter in options object
  * Example: `await input.textAsync('Enter name:', {defaultValue: 'Anonymous'})`
  * Pre-fills the input field with a default value that users can accept or modify
* **Default Values for `input.selectAsync()`** - Added optional `defaultValue` parameter
  * Example: `await input.selectAsync('Select option:', options, defaultValue)`
  * Pre-selects an option in the dropdown menu

#### External Package Imports

* **Dynamic Import Support** - Scripts can now import external JavaScript packages from CDN using dynamic imports
  * Use `await import('package-name')` syntax to load external libraries
  * Example: `const _ = await import('lodash')` or `const dayjs = await import('dayjs')`
  * Supports popular CDNs: esm.sh (default), unpkg, skypack, jsdelivr
  * Enables use of libraries like lodash, dayjs, axios, etc.
  * **Note:** Only dynamic imports are supported; static imports are not available

***

## July 28, 2025

#### Script Steps API

* **Added `script` object** - New global object for creating visual steps
* **`script.step(config)`** - Create and start steps with rich customization options
  * Support for titles, descriptions, icons, and colors
  * Automatic step management (previous step ends when new step starts)
  * String shorthand: `script.step('Step Title')` or full config object
* **`script.clear()`** - Manually end the current step
* **`script.colors`** - Predefined color constants (red, blue, green, yellow, purple, orange, gray)
* **`script.icons`** - Comprehensive icon library with 100+ icons across different categories.

#### Improvements

* Increased script timeout to 30 Minutes

***

## June 30, 2025

#### Initial Scripts Release

* **`base` object** - Access to base metadata and configuration
* **`table` object** - Create, Read operations on tables
* **`record` object** - Rich record manipulation capabilities
* **`field` object** - Field metadata and validation
* **`input` object** - User input collection methods
* **`output` object** - Rich output formatting options
* **`fetch` function** - HTTP requests to external APIs
* **`session` object** - Script execution context and state

#### Core Functionality

* **JavaScript runtime** - Full ES6+ support
* **Async/await support** - Modern asynchronous programming
* **Error handling** - Comprehensive error reporting
* **Type safety** - TypeScript definitions for all APIs

***

## Support and Resources

* **Documentation**: [Scripts API Reference](/docs/scripts/api-reference)
* **Examples**: [Script Examples](/docs/scripts/examples)
* **Community**: [NocoDB Discord](https://discord.gg/5RgZmkW)
* **Issues**: [GitHub Issues](https://github.com/nocodb/nocodb/issues)

For questions about specific API changes or migration help, please reach out to our community or support team.


# Scripts
URL: /docs/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.

<Callout type="info">
  Scripts are available from the NocoDB Plus plan on the cloud, and with the Enterprise license in self-hosted environments.
</Callout>

## 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
* **External Package Imports**: Import and use NPM packages from CDN (lodash, dayjs, etc.)
* **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](/docs/scripts/api-reference) to interact with your NocoDB base, tables, and records. Changes are saved automatically.
5. Run your script with the ▶️ button

<img alt="Create Script" src={__img0} placeholder="blur" />
<img alt="Create Script" src={__img1} placeholder="blur" />
<img alt="Create Script" src={__img2} placeholder="blur" />

## Script Structure

A typical NocoDB script follows this pattern:

```javascript
// 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
* **External Packages**: Import and use NPM packages


# Base
URL: /docs/scripts/api-reference/base

Documentation for the base object in NocoDB Scripts

The `base` object is the primary entry point to your database in NocoDB Scripts. It provides access to tables, views, records, and collaborators within your base.

## Overview

In every script, you have access to a global `base` object that represents the current NocoDB base where your script is running. This object lets you:

* Access tables within your base
* List collaborators
* Create new tables (in supported environments)

## Properties

| Property              | Type             | Description                                                                          |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `id`                  | `string`         | The unique identifier of the base                                                    |
| `name`                | `string`         | The name of the base                                                                 |
| `tables`              | `Table[]`        | Array of all tables in the base with their fields and views                          |
| `activeCollaborators` | `Collaborator[]` | Array of active collaborators having access to this base (with read-only properties) |

## Methods

### getTable

Retrieves a table from the base using its **ID** or **name**.

**Parameters:**

* `idOrName` (`string`): The ID or name of the table to retrieve

<Callout type="info">
  Both the table name and table ID are case-sensitive
</Callout>

**Returns:**

* `Table` object if a match is found
* `null` if no table matches the provided input

**Example:**

```javascript
// Get a table by name
const projects = base.getTable('Projects');

// Get a table by ID
const tasks = base.getTable('m123456789');

// Check if a table exists
const tableName = 'Customers';
const table = base.getTable(tableName);
if (table) {
  output.text(`Table ${tableName} found!`);
} else {
  output.text(`Table ${tableName} not found.`);
}
```

### getCollaborator

Retrieves a collaborator from the base by their **ID**, **email**, or **name**.

**Parameters:**

* `idOrEmailOrName` (`string`): The collaborator’s ID, email address, or display name.

<Callout type="info">
  Email addresses are case-insensitive. ID and name are case-sensitive
</Callout>

**Returns:**

* `Collaborator` object if a match is found.
* `null` if no collaborator matches the provided input.

**Example:**

```javascript
// Get a collaborator by email
const user = base.getCollaborator('user@example.com');

// Check if a user has access to the base
if (user) {
  output.text(`User ${user.name} (${user.email}) has access to this base.`);
} else {
  output.text('User not found in collaborators.');
}
```

### createTableAsync

Creates a new table in the base with the specified name and fields.

**Parameters:**

* `name` (`string`): The name for the new table
* `fields` (`Array`): Array of field configurations where each field should have:
  * `name` (`string`): The field name
  * `type` (`UITypes`): The field type
  * `options` (`Object`, optional): Field-specific options

**Returns:** `Promise<Table>` - A promise that resolves to the newly created table

Note that, `fields` can be an empty array. A table with only system fields will be created. The first field in the fields array will be marked as display value field. Fields must have case sensitive unique names. Fields of all type except 'Button' are allowed.

**Example:**

```javascript
try {
  const newTable = await base.createTableAsync('Orders', [
    {
      name: 'Order ID',
      type: UITypes.SingleLineText
    },
    {
      name: 'Customer',
      type: UITypes.SingleLineText
    },
    {
      name: 'Order Date',
      type: UITypes.Date,
      options: {
        date_format: 'YYYY-MM-DD'
      }
    },
    {
      name: 'Status',
      type: UITypes.SingleSelect,
      options: {
        choices: [
          { title: 'Pending', color: '#FFC107' },
          { title: 'Processing', color: '#007BFF' },
          { title: 'Shipped', color: '#28A745' },
          { title: 'Delivered', color: '#6F42C1' },
          { title: 'Cancelled', color: '#DC3545' }
        ]
      }
    }
  ]);
  
  output.text(`Table ${newTable.name} created successfully!`);
} catch (error) {
  output.text(`Error creating table: ${error.message}`);
}
```

## Examples

### Getting All Tables

```javascript
// Print all tables in the base
output.markdown('# Tables in this base:');

for (const table of base.tables) {
  output.text(`- ${table.name} (${table.id}): ${table.fields.length} fields, ${table.views.length} views`);
}
```

### Checking for a Specific Table

```javascript
// Check if a specific table exists and create it if it doesn't
const inventoryTableName = 'Inventory';
let inventoryTable = base.getTable(inventoryTableName);

if (!inventoryTable) {
  output.text(`${inventoryTableName} table not found. Creating it now...`);
  
  try {
    inventoryTable = await base.createTableAsync(inventoryTableName, [
      { name: 'Item ID', type: UITypes.SingleLineText },
      { name: 'Item Name', type: UITypes.SingleLineText },
      { name: 'Quantity', type: UITypes.Number },
      { 
        name: 'Category', 
        type: UITypes.SingleSelect, 
        options: {
          choices: [
            { title: 'Electronics', color: '#FFC107' },
            { title: 'Clothing', color: '#007BFF' },
            { title: 'Home & Garden', color: '#28A745' },
            { title: 'Books', color: '#6F42C1' },
            { title: 'Sports', color: '#DC3545' }
          ]
        }
      }
    ]);
    output.text(`${inventoryTableName} table created successfully!`);
  } catch (error) {
    output.text(`Error creating table: ${error.message}`);
  }
} else {
  output.text(`${inventoryTableName} table already exists.`);
}
```

### Working with Collaborators

```javascript
// List all collaborators
output.markdown('# Active Collaborators:');

for (const collaborator of base.activeCollaborators) {
  const displayName = collaborator.name || 'Unnamed User';
  output.text(`- ${displayName} (${collaborator.email}) - ID: ${collaborator.id}`);
}

// Find the current user
const currentUser = session.currentUser;
const currentUserName = currentUser.name || currentUser.email;
output.markdown(`## Current User: ${currentUserName} (${currentUser.email})`);

// Check if a specific user has access using getCollaborator method
const userEmail = 'team@example.com';
const teamMember = base.getCollaborator(userEmail);

if (teamMember) {
  const memberName = teamMember.name || 'Unnamed User';
  output.text(`${memberName} has access to this base.`);
} else {
  output.text(`No collaborator found with email ${userEmail}.`);
}

// You can also search by ID or name
const memberById = base.getCollaborator('u123456789'); // Replace with actual ID
const memberByName = base.getCollaborator('John Doe');

// getCollaborator returns null if no match is found
if (memberById) {
  output.text(`Found collaborator by ID: ${memberById.name || memberById.email}`);
}
```

## Best Practices

1. **Await async operations** - Always use `await` when calling async methods to ensure proper execution flow.

## Related Resources

* [Table](/docs/scripts/api-reference/table)
* [Field](/docs/scripts/api-reference/field)
* [Session](/docs/scripts/api-reference/session)


# Collaborator
URL: /docs/scripts/api-reference/collaborator

Documentation for the Collaborator object in NocoDB Scripts

The `Collaborator` object represents a user who has access to a NocoDB base. It contains key identity attributes such as the user's **ID**, **name**, and **email address**.

## Overview

Collaborator objects appear in several contexts within NocoDB Scripts:

* `session.currentUser` returns a Collaborator object representing the current user running the script
* `User fields` in records return Collaborator objects
* `base.activeCollaborators` returns an array of Collaborator objects for the current base
* Field types such as `CreatedBy` and `LastModifiedBy` return Collaborator objects

This object enables user identification, tracking ownership, assigning responsibilities, and implementing user-specific logic in scripts.

## Properties

| Property | Type             | Description                                                              |
| -------- | ---------------- | ------------------------------------------------------------------------ |
| `id`     | `string`         | The unique identifier of the collaborator (read-only)                    |
| `name`   | `string \| null` | The display name of the collaborator (read-only, may be null if not set) |
| `email`  | `string`         | The email address of the collaborator (read-only)                        |

**Note:** All Collaborator properties are read-only and cannot be modified.

## Contexts Where Collaborator Objects Appear

### Session Object

The `session.currentUser` property returns a Collaborator object representing the current user running the script:

```javascript
// Get the current user
const currentUser = session.currentUser;

output.text(`Current user: ${currentUser.name || currentUser.email}`);
output.text(`User ID: ${currentUser.id}`);
output.text(`Email: ${currentUser.email}`);
```

### Base Object

The `base.activeCollaborators` property returns an array of all Collaborator objects for the current base:

```javascript
// Get all collaborators for this base
const collaborators = base.activeCollaborators;

output.markdown('# Base Collaborators');
output.text(`Number of collaborators: ${collaborators.length}`);

// List all collaborators
for (const collaborator of collaborators) {
  output.text(`- ${collaborator.name || 'Unnamed'} (${collaborator.email})`);
}
```

The `base.getCollaborator()` method allows you to find a specific Collaborator by ID, name, or email:

```javascript
// Find a collaborator by email
const collaborator = base.getCollaborator('john.doe@example.com');

if (collaborator) {
  output.text(`Found collaborator: ${collaborator.name || 'Unnamed'}`);
  output.text(`ID: ${collaborator.id}`);
} else {
  output.text('Collaborator not found.');
}
```

### User Field

When a table has a User field type, `getCellValue()` returns a Collaborator object (or an array of Collaborator objects if multiple selection is enabled):

```javascript
// Get a record from the Tasks table
const tasksTable = base.getTable('Tasks');
const taskRecord = await tasksTable.selectRecordAsync('123');

// Get the assigned user (assuming 'Assigned To' is a User field)
const assignedTo = taskRecord.getCellValue('Assigned To');

if (assignedTo) {
  // This is a Collaborator object
  output.text(`Task assigned to: ${assignedTo.name || assignedTo.email}`);
} else {
  output.text('Task is unassigned.');
}

// For a User field that allows multiple users
const reviewers = taskRecord.getCellValue('Reviewers') || [];

if (reviewers.length > 0) {
  output.text('Reviewers:');
  for (const reviewer of reviewers) {
    // Each reviewer is a Collaborator object
    output.text(`- ${reviewer.name || reviewer.email}`);
  }
} else {
  output.text('No reviewers assigned.');
}
```

### Created By and Last Modified By Fields

The `CreatedBy` and `LastModifiedBy` field types return Collaborator objects:

```javascript
// Get a record with system user fields
const recordsTable = base.getTable('Documents');
const document = await recordsTable.selectRecordAsync('123');

// Get the user who created the record
const createdBy = document.getCellValue('Created By');
if (createdBy) {
  output.text(`Created by: ${createdBy.name || createdBy.email}`);
  output.text(`Creation date: ${document.getCellValueAsString('Created Time')}`);
}

// Get the user who last modified the record
const lastModifiedBy = document.getCellValue('Last Modified By');
if (lastModifiedBy) {
  output.text(`Last modified by: ${lastModifiedBy.name || lastModifiedBy.email}`);
  output.text(`Last modified: ${document.getCellValueAsString('Last Modified Time')}`);
}
```

## Working with Collaborator Objects

### Finding a Specific Collaborator

```javascript
// Get all collaborators
const collaborators = base.activeCollaborators;

// Find a collaborator by email (case-insensitive)
function findCollaboratorByEmail(email) {
  const lowerEmail = email.toLowerCase();
  return collaborators.find(collaborator => 
    collaborator.email.toLowerCase() === lowerEmail
  );
}

// Find a collaborator by name (case-insensitive)
function findCollaboratorByName(name) {
  const lowerName = name.toLowerCase();
  return collaborators.find(collaborator => 
    collaborator.name && collaborator.name.toLowerCase().includes(lowerName)
  );
}

// Example usage
const collaborator1 = findCollaboratorByEmail('jane.smith@example.com');
const collaborator2 = findCollaboratorByName('john');

if (collaborator1) {
  output.text(`Found by email: ${collaborator1.name || collaborator1.email}`);
}

if (collaborator2) {
  output.text(`Found by name: ${collaborator2.name || collaborator2.email}`);
}
```

### Checking if Current User Matches a Specific Collaborator

```javascript
// Get the current user
const currentUser = session.currentUser;

// Check if the current user is a specific person
function isUser(emailOrId) {
  if (currentUser.email.toLowerCase() === emailOrId.toLowerCase()) {
    return true;
  }
  
  if (currentUser.id === emailOrId) {
    return true;
  }
  
  return false;
}

// Example usage
if (isUser('admin@example.com')) {
  output.text('You are the admin user.');
  // Show admin-specific content
} else {
  output.text('You are not the admin user.');
  // Show regular user content
}
```

## Best Practices

1. **Check for null names** - Always check if `collaborator.name` is null before using it, as not all users have names set. Use `collaborator.name || collaborator.email` as a fallback.

2. **Be cautious with personal information** - Be mindful about how you display and use collaborator information, particularly when creating outputs that might be shared.

3. **Handle missing collaborators** - When working with User fields, always check if the value is null before trying to access Collaborator properties.

4. **Consider multi-user fields** - Remember that User fields can be configured to allow multiple selections, so the value might be an array of Collaborator objects.

5. **Use IDs for references** - When updating records with User fields, use the collaborator's ID as the value, not the entire Collaborator object.

## Related Resources

* [Base](/docs/scripts/api-reference/base)
* [Session](/docs/scripts/api-reference/session)
* [Field](/docs/scripts/api-reference/field)
* [Record](/docs/scripts/api-reference/record)


# Cursor
URL: /docs/scripts/api-reference/cursor

Documentation for the Cursor object in NocoDB Scripts

The `cursor` object provides contextual information about the current script execution environment, including which base, table, view, and row is active when the script runs.

## Overview

The `cursor` object is particularly useful for scripts that are triggered from specific contexts, such as button scripts that run within a record view. It allows you to access:

* The currently active base
* The currently active table (if applicable)
* The currently active view (if applicable)
* The currently selected row's data (if applicable)

This contextual awareness helps you create scripts that respond intelligently to where and how they are executed.

## Properties

| Property        | Type                                 | Description                                                             |
| --------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| `activeBaseId`  | `string`                             | The ID of the currently active base                                     |
| `activeTableId` | `string \| null`                     | The ID of the currently active table, or `null` if no table is active   |
| `activeViewId`  | `string \| null`                     | The ID of the currently active view, or `null` if no view is active     |
| `row`           | `Record < string, unknown > \| null` | The data of the currently selected row, or `null` if no row is selected |

## Usage Examples

### Checking the Context

```javascript
// Check where the script is running
output.markdown('# Script Context');

// Base context is always available
output.text(`Active Base ID: ${cursor.activeBaseId}`);

// Table context may not be available
if (cursor.activeTableId) {
  const activeTable = base.getTable(cursor.activeTableId);
  output.text(`Active Table: ${activeTable.name}`);
} else {
  output.text('No active table context.');
}

// View context may not be available
if (cursor.activeViewId) {
  // Find the active view
  for (const table of base.tables) {
    const view = table.views.find(v => v.id === cursor.activeViewId);
    if (view) {
      output.text(`Active View: ${view.name} in ${table.name}`);
      break;
    }
  }
} else {
  output.text('No active view context.');
}

// Row context may not be available
if (cursor.row) {
  output.text('Active row data:');
  output.table(cursor.row);
} else {
  output.text('No active row context.');
}
```

### Bulk Update Script

This example shows how to create a script that operates on multiple selected records in a table:

```javascript
// First, prompt the user to select a table
const table = await input.tableAsync('Select a table to update records');

// Then prompt for a view within that table
const view = await input.viewAsync('Select a view with the records to update', table);

// Get the records from the view
const records = await view.selectRecordsAsync();

// Let the user choose a field to update
const field = await input.fieldAsync('Select a field to update', table);

// Get the new value for the field
let newValue;
switch (field.type) {
  case UITypes.SingleLineText:
  case UITypes.LongText:
    newValue = await input.textAsync(`Enter new value for ${field.name}`);
    break;
  case UITypes.Checkbox:
    newValue = await input.buttonsAsync(`Set ${field.name} to:`, [
      { label: 'Checked', value: true },
      { label: 'Unchecked', value: false }
    ]);
    break;
  case UITypes.SingleSelect:
    const choices = field.options.choices.map(c => ({ label: c.title, value: c.title }));
    newValue = await input.selectAsync(`Select new value for ${field.name}`, choices);
    break;
  // Add cases for other field types as needed
  default:
    output.text(`Update for field type ${field.type} is not implemented in this script.`);
    return;
}

// Confirm the update
const confirmation = await input.buttonsAsync(
  `Are you sure you want to update ${field.name} to "${newValue}" for ${records.records.length} records?`,
  [
    { label: 'Yes, update records', value: true, variant: 'primary' },
    { label: 'Cancel', value: false, variant: 'secondary' }
  ]
);

if (!confirmation) {
  output.text('Update cancelled.');
  return;
}

// Perform the update
output.text(`Updating ${records.records.length} records...`);

const recordUpdates = records.records.map(record => ({
  id: record.id,
  fields: {
    [field.name]: newValue
  }
}));

await table.updateRecordsAsync(recordUpdates);
output.text(`Update complete! Updated ${recordUpdates.length} records.`);

// If we're in an active table context, reload the view
if (cursor.activeTableId === table.id && cursor.activeViewId) {
  await viewActions.reloadView();
}
```

## Best Practices

1. **Always check context availability** - Use conditional checks on cursor properties since they may be null depending on where the script runs.

2. **Enhance user experience** - Provide meaningful errors when a script requires a specific context to run.

## Related Resources

* [Base](/docs/scripts/api-reference/base)
* [Table](/docs/scripts/api-reference/table)
* [View](/docs/scripts/api-reference/view)
* [Session](/docs/scripts/api-reference/session)


# External Packages
URL: /docs/scripts/api-reference/external-packages

Documentation for the external packages in NocoDB Scripts

NocoDB Scripts supports importing external JavaScript packages using **dynamic imports**, allowing you to leverage NPM libraries in your scripts.

<Callout type="info">
  External packages are only available in browser environment and does not work in Webhook Scripts.
</Callout>

<Callout type="warning">
  **Important:** Only dynamic imports using `import()` are supported. Static imports (e.g., `import _ from 'lodash'`) are not supported.
</Callout>

### Which type of imports are supported?

Only dynamic imports using `import()` are supported. Static imports (`import ... from '...'`) will not work.

### Can I import any NPM package?

Not all packages will work.

✅ **Works:** Pure JavaScript/ESM libraries (e.g., lodash, dayjs, uuid, zod, axios).

❌ **Doesn't work:** Packages that require DOM (react-dom, jquery, chart.js) or Node.js APIs (fs, net, crypto Node module, express, sharp).

**Tip:** If it runs inside a Web Worker, it will usually work in NocoDB Scripts.

### Why do some packages fail in NocoDB Scripts?

Scripts run in a Web Worker sandbox. This environment:

* Has no DOM (`document`, `window`, `HTMLElement`).
* Has no Node APIs (`fs`, `process`, `child_process`, native addons).
* Disallows synchronous browser storage (`localStorage`, `document.cookie`).

### How do I import multiple packages?

Use separate dynamic imports:

```javascript
const _ = (await import('lodash')).default;
const dayjs = (await import('dayjs')).default;
```

### Do I need .default after import?

Many CDN-transpiled packages expose the default export at `.default`. If you see `undefined`, try:

```javascript
const dayjs = (await import('dayjs')).default;
```

### How do I pin a specific package version?

Include a version or semver tag in the CDN URL to avoid breaking changes.

```javascript
const _ = (await import('https://esm.sh/lodash@4.17.21')).default;
```

### Common gotchas & troubleshooting

* **Named vs default exports:** Check the package's docs; you might need named imports:
  ```javascript
  const { nanoid } = await import('nanoid');
  const { z } = await import('zod');
  ```
* **Tree-shaking:** Import subpaths when available for smaller bundles (e.g., lodash-es functions).

### Examples that work well

* lodash / lodash-es
* dayjs
* zod
* uuid
* axios (uses fetch in browsers)

### Examples that won't work

* react-dom, jquery, chart.js, leaflet (DOM-bound)
* express, fs-extra, sharp, sqlite3 (Node-only)
* js-cookie (needs document.cookie)

### Security considerations

* Prefer pinned versions.
* Review package reputation; avoid importing untrusted code at runtime.
* Validate and sanitize any data flowing into third‑party libs.

### Example: Full flow

```javascript
// Load external libs
const _ = (await import('https://esm.sh/lodash@4.17.21')).default;
const dayjs = (await import('https://esm.sh/dayjs@1')).default;

// Query data
const customers = base.getTable('Customers');
const recordQueryResult = await customers.selectRecordsAsync();

// Group and format
const groupedByStatus = _.groupBy(recordQueryResult.records, r => r.getCellValue('Status'));
for (const [status, customers] of Object.entries(groupedByStatus)) {
  output.text(`${status}: ${recordQueryResult.records.length} customers`);
}
output.text(`Report generated on: ${dayjs().format('MMMM D, YYYY')}`);
```


# Remote Fetch
URL: /docs/scripts/api-reference/fetch

Documentation for the remoteFetchAsync function in NocoDB Scripts

The `remoteFetchAsync` function provides a way to make HTTP requests to external services from within NocoDB scripts. This enables you to integrate with third-party APIs, fetch external data, and connect your base to other systems.

## Overview

The `remoteFetchAsync` function is similar to the standard web Fetch API but runs in the secure context of NocoDB Scripts. It allows you to:

* Make GET, POST, PUT, and DELETE requests to external APIs
* Send and receive JSON data, text, and other formats
* Set custom headers like authentication tokens
* Integrate your base with external services

This function is asynchronous and returns a Promise, so it must be used with `await` to get the result.

## Basic Syntax

```javascript
const response = await remoteFetchAsync(url, options);
```

**Parameters:**

* `url` (`string`): The URL to which the request should be sent
* `options` (`object`, optional): Configuration options for the request:
  * `method` (`'GET' | 'POST' | 'PUT' | 'DELETE'`, optional): The HTTP method to use (default: 'GET')
  * `headers` (`object`, optional): Headers to include in the request
  * `body` (`string | null`, optional): Body content to send with the request

**Returns:** `Promise<any>` - A promise that resolves to the response data or rejects with an axios-like error object

## Error Handling

The `remoteFetchAsync` function provides enhanced error handling that mimics the axios error structure. When a request fails, the rejected error object includes:

* `message` (`string`): The error message
* `response` (`object`): Response details including:
  * `data`: Response data from the server
  * `status`: HTTP status code
  * `statusText`: HTTP status text
  * `headers`: Response headers
  * `config`: Request configuration
* `config` (`object`): The original request configuration
* `code` (`string`): Error code (if available)
* `name` (`string`): Error name (defaults to 'AxiosError')

### Handling Errors

```javascript
try {
  const response = await remoteFetchAsync('https://api.example.com/data');
  output.inspect(response.data);
} catch (error) {
  // Error object mimics axios structure
  output.text(`Error: ${error.message}`, 'error');
  
  if (error.response) {
    // Server responded with error status
    output.text(`Status: ${error.response.status}`, 'error');
    output.text(`Status Text: ${error.response.statusText}`, 'error');
    output.inspect(error.response.data);
  } else {
    // Network error or other issue
    output.text('Network error or request failed', 'error');
  }
}
```

## Basic Examples

### Making a GET Request

```javascript
// Simple GET request
const response = await remoteFetchAsync('https://api.example.com/data');
output.text(`Response status: ${response.status}`);
output.inspect(response.data);
```

### Making a POST Request with JSON Data

```javascript
// POST request with JSON data
const response = await remoteFetchAsync('https://api.example.com/items', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'New Item',
    description: 'This is a new item',
    quantity: 10
  })
});

if (response.status === 201) {
  output.text('Item created successfully!');
  output.inspect(response.data);
} else {
  output.text(`Error creating item: ${response.status}`, 'error');
}
```

### Making a Request with Authentication

```javascript
// GET request with authorization header
const apiKey = 'your_api_key_here';

const response = await remoteFetchAsync('https://api.example.com/secure-data', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

if (response.status === 200) {
  output.text('Successfully fetched secure data');
  output.table(response.data);
} else if (response.status === 401) {
  output.text('Authentication failed: Invalid API key', 'error');
} else {
  output.text(`Request failed with status: ${response.status}`, 'error');
}
```

## Common Use Cases

### Fetching Data from a Public API

```javascript
// Fetch weather data from a public API
async function getWeatherData(city) {
  try {
    const response = await remoteFetchAsync(
      `https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=${encodeURIComponent(city)}`
    );
    
    if (response.status !== 200) {
      throw new Error(`API returned status ${response.status}`);
    }
    
    const weatherData = response.data;
    
    output.markdown(`# Weather for ${weatherData.location.name}, ${weatherData.location.country}`);
    output.text(`Temperature: ${weatherData.current.temp_c}°C / ${weatherData.current.temp_f}°F`);
    output.text(`Condition: ${weatherData.current.condition.text}`);
    output.text(`Wind: ${weatherData.current.wind_kph} km/h, ${weatherData.current.wind_dir}`);
    output.text(`Humidity: ${weatherData.current.humidity}%`);
    output.text(`Last Updated: ${weatherData.current.last_updated}`);
    
    return weatherData;
  } catch (error) {
    output.text(`Error fetching weather data: ${error.message}`, 'error');
    return null;
  }
}

// Get weather for a city
const city = await input.textAsync('Enter city name:');
await getWeatherData(city);
```

### Sending Data to a Webhook

```javascript
// Send data to a webhook (e.g., Zapier, Make.com, etc.)
async function sendToWebhook(data) {
  try {
    output.text('Sending data to webhook...');
    
    const response = await remoteFetchAsync('https://hooks.zapier.com/hooks/catch/123456/abcdef/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    if (response.status >= 200 && response.status < 300) {
      output.text('Data sent successfully!', 'log');
      return true;
    } else {
      throw new Error(`Webhook returned status ${response.status}`);
    }
  } catch (error) {
    output.text(`Error sending to webhook: ${error.message}`, 'error');
    return false;
  }
}

// Example: Send new customer data to a webhook
const customersTable = base.getTable('Customers');
const newCustomersView = customersTable.getView('New Customers');

const customers = await newCustomersView.selectRecordsAsync({
  fields: ['Name', 'Email', 'Phone', 'Signup Date']
});

// Process each customer
for (const customer of customers.records) {
  const customerData = {
    name: customer.getCellValue('Name'),
    email: customer.getCellValue('Email'),
    phone: customer.getCellValue('Phone'),
    signupDate: customer.getCellValue('Signup Date'),
    source: 'NocoDB'
  };
  
  const success = await sendToWebhook(customerData);
  
  if (success) {
    // Update the customer record to mark as processed
    await customersTable.updateRecordAsync(customer.id, {
      'Webhook Sent': true,
      'Processing Date': new Date().toISOString()
    });
  }
}
```

### Integrating with Google Sheets API

```javascript
// Import data from Google Sheets (simplified example)
// Note: Doesn't work if the spreadsheet is owned by a user with a Google Workspace (formerly G Suite) account
// and requires the Google Sheets API to be enabled in your Google Cloud project. Share sheet with Viewer access publicly
async function importFromGoogleSheets(spreadsheetId, range) {
  const apiKey = 'API_KEY';
  
  try {
    output.text(`Fetching data from Google Sheets (${spreadsheetId})...`);

    const response = await remoteFetchAsync(
      `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}/values/${range}?key=${apiKey}`
    );

    if (response.status !== 200) {
      throw new Error(`API returned status ${response.status}`);
    }

    const sheetData = response.data;

    if (!sheetData.values || sheetData.values.length === 0) {
      output.text('No data found in the specified range.', 'warning');
      return null;
    }

    // Extract headers from the first row
    const headers = sheetData.values[0];

    // Convert the data to an array of objects
    const records = sheetData.values.slice(1).map(row => {
      const record = {};
      headers.forEach((header, index) => {
        record[header] = row[index] || null;
      });
      return record;
    });

    output.text(`Fetched ${records.length} records from Google Sheets.`);
    output.table(records.slice(0, 5)); // Show first 5 records as preview

    return records;
  } catch (error) {
    output.text(`Error fetching data from Google Sheets: ${error.message}`, 'error');
    return null;
  }
}

// Example usage
const spreadsheetId = '1o_HhLwbUYJuwwPok8poOjRZxxxxxIgQF9z5aoEZrzXU'; // Example Spreadsheet ID
const range = 'Sheet1!A1:B10'; // Range to fetch

const sheetsData = await importFromGoogleSheets(spreadsheetId, range);

if (sheetsData) {
  // Import the data into a NocoDB table
  const importTable = base.getTable('Imported Data');

  // Clear confirmation before proceeding
  const confirm = await input.buttonsAsync(
    `Import ${sheetsData.length} records into the "${importTable.name}" table?`,
    [
      { label: 'Import Data', value: true, variant: 'primary' },
      { label: 'Cancel', value: false, variant: 'secondary' }
    ]
  );

  if (confirm) {
    // Import data in batches
    const batchSize = 50;
    let imported = 0;

    // output.inspect(sheetsData);

    for (let i = 0; i < sheetsData.length; i += batchSize) {
      const batch = sheetsData.slice(i, i + batchSize);

      // Wrap each record in a { fields: ... } object
      const formattedBatch = batch.map(record => ({ fields: record }));
      output.inspect(batch);

      await importTable.createRecordsAsync(formattedBatch);
      imported += batch.length;
      output.text(`Imported ${imported} of ${sheetsData.length} records...`);
    }
    
    output.text(`Import complete! ${imported} records imported.`, 'log');
  } else {
    output.text('Import cancelled.');
  }
}
```

## Working with Different Data Formats

### JSON Data

```javascript
// Working with JSON data
async function fetchJsonData() {
  try {
    const response = await remoteFetchAsync('https://api.example.com/data', {
      headers: {
        'Accept': 'application/json'
      }
    });
    
    if (response.status !== 200) {
      throw new Error(`API returned status ${response.status}`);
    }
    
    // The response data is automatically parsed as JSON
    const data = response.data;
    
    return data;
  } catch (error) {
    output.text(`Error fetching JSON data: ${error.message}`, 'error');
    return null;
  }
}
```

### Form Data

```javascript
// Submitting form data
async function submitFormData(formData) {
  try {
    // Convert the form data object to URL-encoded format
    const formBody = Object.entries(formData)
      .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
      .join('&');
    
    const response = await remoteFetchAsync('https://api.example.com/submit-form', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: formBody
    });
    
    if (response.status === 200 || response.status === 201) {
      output.text('Form submitted successfully!', 'log');
      return true;
    } else {
      throw new Error(`Server returned status ${response.status}`);
    }
  } catch (error) {
    output.text(`Error submitting form: ${error.message}`, 'error');
    return false;
  }
}

// Example usage
const formData = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  message: 'This is a test message',
  subscribe: 'true'
};

await submitFormData(formData);
```

## Best Practices

1. **Use try/catch blocks** - Always wrap `remoteFetchAsync` calls in try/catch blocks to handle connection errors, timeouts, and other issues. The function provides axios-like error objects with detailed error information.

2. **Check error.response for server errors** - When handling errors, check if `error.response` exists to distinguish between server errors (4xx, 5xx status codes) and network/connection errors.

3. **Validate response status in success cases** - Even for successful requests, validate the HTTP status code before attempting to use the response data.

4. **Set appropriate headers** - Include the correct `Content-Type` and `Accept` headers for your request.

5. **Handle authentication properly** - Use secure methods to store and transmit authentication credentials.

6. **Implement rate limiting** - Be mindful of API rate limits and implement throttling or backoff strategies when needed.

7. **Cache responses when appropriate** - For data that doesn't change frequently, consider storing the response and reusing it.

8. **Log meaningful errors** - Provide clear error messages to help troubleshoot issues.

9. **Validate input data** - Ensure data being sent to external APIs is valid and properly formatted.

10. **Respect API terms of service** - Ensure your usage of external APIs complies with their terms of service and documentation.

11. **Consider timeouts** - Be aware that remote requests may time out if they take too long to complete.

## Security Considerations

1. **Never expose API keys in output** - Be careful not to include sensitive information like API keys in your output.

2. **Use secure endpoints** - Prefer HTTPS URLs over HTTP to ensure encrypted data transmission.

3. **Validate and sanitize input** - Be cautious with user-provided data that will be sent to external APIs.

4. **Be mindful of data privacy** - Consider the privacy implications of transmitting data to third-party services.

5. **Implement proper error handling** - Don't expose detailed error messages from APIs that might reveal sensitive information.

## Related Resources

* [Input Methods](/docs/scripts/api-reference/input)
* [Output Methods](/docs/scripts/api-reference/output)
* [Table](/docs/scripts/api-reference/table)


# Field
URL: /docs/scripts/api-reference/field

Documentation for the Field object and Field Types in NocoDB Scripts

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

```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`): New description text, or null to remove 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

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

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

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.

```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 that can optionally 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

Different field types store and return values in specific formats. Understanding these formats is crucial when working 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 verify a field's type before trying to work with type-specific options.

2. **Handle null values** - Remember that almost any field can have a null/empty value, so include null checks in your code.

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

4. **Be cautious with system fields** - Some fields are system-controlled and have limitations on what you can modify.

5. **Consider field dependencies** - Remember that some fields (like Lookup and Rollup) depend on other fields, so consider the impact of changes.

6. **Check field existence** - Always verify a field exists before trying to access it.

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

8. **Await async operations** - Always use `await` when calling async methods to ensure proper execution flow.

## Related Resources

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


# API Reference
URL: /docs/scripts/api-reference

Explore the NocoDB Scripts API for advanced automation and integration

### Core Objects

* [Base Object](/docs/scripts/api-reference/base) - Access tables, collaborators, and create new structures
* [Table Object](/docs/scripts/api-reference/table) - Query, create, update, and delete records with advanced options
* [View Object](/docs/scripts/api-reference/view) - Work with filtered and sorted table perspectives
* [Record Object](/docs/scripts/api-reference/record) - Individual data entries with rich cell value handling
* [Field Object](/docs/scripts/api-reference/field) - Table structure with comprehensive field type support
* [RecordQueryResult](/docs/scripts/api-reference/record-query-result) - Paginated query results with load-more capabilities

### User and Session Management

* [Collaborator](/docs/scripts/api-reference/collaborator) - User information and permissions
* [Session](/docs/scripts/api-reference/session) - Current user context and session data

### Input and Output

* [Input Methods](/docs/scripts/api-reference/input) - Interactive prompts, file uploads, and user selections
* [Output Methods](/docs/scripts/api-reference/output) - Text, markdown, tables, progress indicators, and debugging

### External Integration

* [Remote Fetch](/docs/scripts/api-reference/fetch) - HTTP requests, external APIs, and NocoDB REST API proxy
* [Script Settings](/docs/scripts/api-reference/script-settings) - Configuration and environment variables
* [External Packages](/docs/scripts/api-reference/external-packages) - Import and use popular NPM packages from CDN


# Input
URL: /docs/scripts/api-reference/input

Documentation for the input object and its methods in NocoDB Scripts





















The `input` object provides methods for collecting user input during script execution. These methods allow you to create interactive scripts that can prompt users for information, choices, and file uploads.

## Overview

Input methods are asynchronous and pause script execution until the user provides a response. This enables you to:

* Collect text input from users
* Present users with choices using buttons or dropdown menus
* Allow users to select tables, views, fields, or records
* Collect file uploads for data processing

All input methods return a Promise that resolves to the value provided by the user, so they must be used with `await` to get the result.

## Available Methods

### input.textAsync()

Prompts the user to enter text.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `options` (`object`, optional): Additional options for the text input
  * `defaultValue` (`string`, optional): Default value for the text input

**Returns:** `Promise<string>` - A promise that resolves to the text entered by the user

**Example:**

```javascript
// Ask for user's name
const name = await input.textAsync('What is your name?');
output.text(`Hello, ${name}!`);

// Ask for an email subject with a default value
const subject = await input.textAsync('Enter email subject:', {defaultValue: 'Monthly Newsletter'});
output.text(`Email subject: ${subject}`);

// Ask for user's name with a default
const userName = await input.textAsync('What is your name?', {defaultValue: 'Anonymous'});
output.text(`Hello, ${userName}!`);
```

**Output:**
<img alt="Text Input Example" src={__img0} placeholder="blur" />

### input.buttonsAsync()

Presents the user with buttons to choose from.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `options` (`Array<string | ButtonOption>`): An array of options, either as strings or button option objects

**Button Option Properties:**

* `label` (`string`): Text to display on the button
* `value` (any): Value to return when the button is clicked (defaults to the label if using strings)
* `variant` (`'default' | 'primary' | 'secondary' | 'danger'`, optional): Visual style of the button

**Returns:** `Promise<any>` - A promise that resolves to the value of the selected option

**Example with simple strings:**

```javascript
// Ask user to choose a status
const status = await input.buttonsAsync(
  'Select a status for this record:',
  ['Active', 'Pending', 'Completed', 'Cancelled']
);
output.text(`Selected status: ${status}`);
```

**Output:**
<img alt="Button Input Example" src={__img1} placeholder="blur" />

**Example with button options:**

```javascript
// Ask for confirmation with styled buttons
const confirmation = await input.buttonsAsync(
  'Are you sure you want to delete these records?',
  [
    { label: 'Yes, delete them', value: true, variant: 'danger' },
    { label: 'Cancel', value: false, variant: 'secondary' }
  ]
);

if (confirmation) {
  output.text('Deleting records...');
  // Delete operation would go here
} else {
  output.text('Operation cancelled.');
}
```

**Output:**
<img alt="Button Input Example" src={__img2} placeholder="blur" />

### input.selectAsync()

Presents a dropdown menu of options for the user to choose from.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `options` (`Array<string | { label: string, value: any }>`): An array of options, either as strings or objects with label and value properties
* `defaultValue` (any, optional): Default selected value

**Returns:** `Promise<any>` - A promise that resolves to the value of the selected option

**Example with simple strings:**

```javascript
// Ask user to select a department
const department = await input.selectAsync(
  'Select a department:',
  ['Marketing', 'Sales', 'Engineering', 'Customer Support', 'Finance', 'HR']
);
output.text(`Selected department: ${department}`);

// Ask user to select a department with a default value
const dept = await input.selectAsync(
  'Select a department:',
  ['Marketing', 'Sales', 'Engineering', 'Customer Support', 'Finance', 'HR'],
  'Engineering' // default value
);
output.text(`Selected department: ${dept}`);
```

**Output:**
<img alt="Select Input Example" src={__img3} placeholder="blur" />

**Example with label/value objects:**

```javascript
// Ask user to select a priority level
const priority = await input.selectAsync(
  'Select priority level:',
  [
    { label: 'High (Urgent)', value: 3 },
    { label: 'Medium (Normal)', value: 2 },
    { label: 'Low (When time permits)', value: 1 }
  ]
);
output.text(`Selected priority level: ${priority}`);

// Ask user to select a priority level with a default value
const priorityLevel = await input.selectAsync(
  'Select priority level:',
  [
    { label: 'High (Urgent)', value: 3 },
    { label: 'Medium (Normal)', value: 2 },
    { label: 'Low (When time permits)', value: 1 }
  ],
  2 // default value (Medium)
);
output.text(`Selected priority level: ${priorityLevel}`);
```

**Output:**
<img alt="Select Input Example" src={__img4} placeholder="blur" />

### input.fileAsync()

Prompts the user to upload a file.

**Parameters:**

* `label` (`string`, optional): The prompt text to display to the user (defaults to " --Select a file-- ")
* `options` (`object`, optional): Additional options for file upload:
  * `allowedFileTypes` (`Array<string>`): File extensions or MIME types to accept (e.g., '.csv', '.xlsx', 'application/json')
  * `hasHeaderRow` (`boolean`): For spreadsheets, whether to treat the first row as headers
  * `useRawValues` (`boolean`): For spreadsheets, whether to return raw string values vs. parsed types

**Returns:** `Promise<any>` - A promise that resolves to the parsed file contents. The data is automatically parsed from JSON if possible, otherwise returned as-is

**Example:**

```javascript
// Ask user to upload a CSV file
const result = await input.fileAsync('Please upload a CSV file of contacts', {
  allowedFileTypes: ['.csv'],
  hasHeaderRow: true
});

if (result && result.parsedContents) {
  const contacts = result.parsedContents;
  output.text(`Uploaded ${contacts.length} contacts.`);
  
  // Display the first contact as an example
  if (contacts.length > 0) {
    output.text('First contact:');
    output.table([contacts[0]]);
  }
}
```

**Output:**
<img alt="File Input Example" src={__img5} placeholder="blur" />

### input.tableAsync()

Prompts the user to select a table from the base.

**Parameters:**

* `label` (`string`): The prompt text to display to the user

**Returns:** `Promise<Table>` - A promise that resolves to the selected Table object

**Example:**

```javascript
// Ask user to select a table
const table = await input.tableAsync('Select a table to process:');
output.text(`Selected table: ${table.name}`);

// Get the table's fields
output.text(`Fields in ${table.name}:`);
for (const field of table.fields) {
  output.text(`- ${field.name} (${field.type})`);
}
```

**Output:**
<img alt="Table Input Example" src={__img6} placeholder="blur" />

### input.viewAsync()

Prompts the user to select a view from a specified table.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `tableOrTableNameOrTableId` (`Table | string`): The table, table name, or table ID to select from

**Returns:** `Promise<View>` - A promise that resolves to the selected View object

**Example:**

```javascript
// First select a table
const table = await input.tableAsync('Select a table:');

// Then select a view from that table
const view = await input.viewAsync('Select a view from this table:', table);
output.text(`Selected view: ${view.name} (type: ${view.type})`);

// Query records from the view
const records = await view.selectRecordsAsync();
output.text(`This view contains ${records.records.length} records.`);
```

**Output:**
<img alt="View Input Example" src={__img7} placeholder="blur" />

### input.fieldAsync()

Prompts the user to select a field from a specified table.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `tableOrTableNameOrTableId` (`Table | string`): The table, table name, or table ID to select from

**Returns:** `Promise<Field>` - A promise that resolves to the selected Field object

**Example:**

```javascript
// First select a table
const table = await input.tableAsync('Select a table:');

// Then select a field from that table
const field = await input.fieldAsync('Select a field to analyze:', table);
output.text(`Selected field: ${field.name} (${field.type})`);

// Now use the field for something
const records = await table.selectRecordsAsync({
  fields: [field.name]
});

// Count non-empty values in the field
let nonEmptyCount = 0;
for (const record of records.records) {
  if (record.getCellValue(field.name) !== null) {
    nonEmptyCount++;
  }
}

output.text(`The field "${field.name}" has values in ${nonEmptyCount} out of ${records.records.length} records.`);
```

**Output:**
<img alt="Field Input Example" src={__img8} placeholder="blur" />

### input.recordAsync()

Prompts the user to select a record from a table, view, or set of records.

**Parameters:**

* `label` (`string`): The prompt text to display to the user
* `source` (`Table | View | RecordQueryResult | Array<NocoDBRecord>`): The source to select from
* `options` (`object`, optional): Additional options:
  * `fields` (`Array<Field | string>`): Specific fields to display. Primary key and primary value fields are automatically included.

**Returns:** `Promise<NocoDBRecord | null>` - A promise that resolves to the selected NocoDBRecord object, or null if no record is selected

**Example:**

```javascript
// First select a table
const table = await input.tableAsync('Select a table:');

// Then select a record from that table
const record = await input.recordAsync('Select a record to update:', table);

if (record) {
  output.text(`Selected record: ${record.name}`);
  
  // Ask for a new value
  const newValue = await input.textAsync('Enter a new value:');
  
  // Update the record
  const fieldToUpdate = await input.fieldAsync('Select a field to update:', table);
  
  await table.updateRecordAsync(record.id, {
    [fieldToUpdate.name]: newValue
  });
  
  output.text(`Updated "${fieldToUpdate.name}" to "${newValue}".`);
} else {
  output.text('No record selected.');
}
```

**Output:**
<img alt="Record Input Example" src={__img9} placeholder="blur" />

## Practical Examples

### Form-Based Data Entry

```javascript
// Interactive form for creating a new project
async function createNewProject() {
  const projectsTable = base.getTable('Projects');
  const tasksTable = base.getTable('Tasks');
  
  output.markdown('# Create New Project');
  
  // Just the basics
  const projectName = await input.textAsync('Project Name:');
  const projectDescription = await input.textAsync('Description:');
  const dueDate = await input.textAsync('Due Date (YYYY-MM-DD):');
  
  // Add a few tasks
  output.markdown('## Add Tasks');
  const tasks = [];
  let addingTasks = true;
  
  while (addingTasks) {
    const taskName = await input.textAsync('Task Name:');
    tasks.push({ name: taskName });
    
    const addAnother = await input.buttonsAsync(
      'Add another task?',
      ['Yes', 'No, create project']
    );
    
    addingTasks = (addAnother === 'Yes');
  }
  
  // Create everything
  try {
    output.text('Creating project...');
    
    const projectId = await projectsTable.createRecordAsync({
      'Project Name': projectName,
      'Description': projectDescription,
      'Due Date': dueDate
    });
    
    // Create tasks
    for (const task of tasks) {
      await tasksTable.createRecordAsync({
        'Task Name': task.name,
        'Projects': [{id: projectId}],
        'Status': 'To Do'
      });
    }
    
    output.markdown('# ✅ Project Created!');
    output.text(`Created "${projectName}" with ${tasks.length} tasks`);
    
  } catch (error) {
    output.text(`Error: ${error.message}`);
  }
}

await createNewProject();
```

### File Upload and Processing

```javascript
// Example of using file upload to import data
async function importCSVData(): Promise<void> {
  try {
    // Step 1: Select destination table
    const table: Table = await input.tableAsync('Select a table to import data into:');
    
    // Step 2: Upload CSV file
    const result: any = await input.fileAsync('Upload CSV file:', {
      allowedFileTypes: ['.csv'],
      hasHeaderRow: true,
      useRawValues: false
    });
    
    if (!result || !result.parsedContents) {
      output.text('No file uploaded or file could not be parsed.');
      return;
    }
    
    const csvData: Record<string, any>[] = result.parsedContents;
    
    if (csvData.length === 0) {
      output.text('CSV file is empty.');
      return;
    }
    
    // Step 3: Show file preview
    output.markdown('# CSV Import Preview');
    output.text(`File contains ${csvData.length} rows and ${Object.keys(csvData[0] || {}).length} columns.`);
    
    if (csvData.length > 0) {
      output.text('Sample data (first 3 rows):');
      output.table(csvData.slice(0, 3));
    }
    
    // Step 4: Configure duplicate handling
    const duplicateHandling: 'skip' | 'update' | 'allow' | 'cancel' = await input.selectAsync(
      'How should duplicate records be handled?',
      [
        { label: 'Skip duplicates', value: 'skip' },
        { label: 'Update existing records', value: 'update' },
        { label: 'Allow duplicates', value: 'allow' },
        { label: '-- Cancel Import --', value: 'cancel' }
      ]
    );
    
    if (duplicateHandling === 'cancel') {
      output.text('Import cancelled by user.');
      return;
    }
    
    // Step 5: Select unique field if handling duplicates
    let uniqueField: Field | undefined;
    let uniqueColumnName: string | null = null;
    
    if (duplicateHandling !== 'allow') {
      // Create field options with cancel option
      const fieldOptions = [
        { label: '-- Cancel Import --', value: 'cancel' },
        ...table.fields
          .filter(field => !field.isComputed && !field.is_system_field)
          .map(field => ({
            label: `${field.name} (${field.type})`,
            value: field.name
          }))
      ];
      
      const selectedFieldName: string = await input.selectAsync(
        'Select a field to use for identifying duplicates:', 
        fieldOptions
      );
      
      if (selectedFieldName === 'cancel') {
        output.text('Import cancelled by user.');
        return;
      }      
      uniqueField = table.getField(selectedFieldName);

      if(uniqueField) {
      const csvColumns: string[] = Object.keys(csvData[0] || {});
      uniqueColumnName = csvColumns.find(col => 
        col.toLowerCase().trim() === uniqueField!.name.toLowerCase().trim()
      ) || null;
      
      if (!uniqueColumnName) {
        const availableColumns = [
          { label: '-- Cancel Import --', value: 'cancel' },
          ...csvColumns.map(col => ({ label: col, value: col }))
        ];
        
        uniqueColumnName = await input.selectAsync(
          `No CSV column matches "${uniqueField.name}". Select the CSV column to use:`,
          availableColumns
        );
        
        if (uniqueColumnName === 'cancel') {
          output.text('Import cancelled by user.');
          return;
        }
      }

      }
    }
    
    // Step 6: Map CSV columns to table fields
    output.markdown('## Field Mapping');
    output.text('Map each CSV column to a field in the table:');
    
    const csvColumns: string[] = Object.keys(csvData[0] || {});
    const fieldMap: Record<string, string> = {};
    
    // Get available fields (exclude computed and system fields)
    const availableFields: Field[] = table.fields.filter(field => 
      !field.isComputed && 
      !field.primary_key && 
      !field.is_system_field
    );
    
    for (const column of csvColumns) {
      // Find best match for auto-suggestion
      const bestMatchField: Field | undefined = availableFields.find(field => 
        field.name.toLowerCase().trim() === column.toLowerCase().trim()
      );
      
      const fieldOptions: Array<{ label: string; value: string }> = [
        { label: '-- Skip this column --', value: 'skip' },
        { label: '-- Cancel Import --', value: 'cancel' },
        ...availableFields.map(field => ({
          label: `${field.name} (${field.type})`,
          value: field.name
        }))
      ];
      
      let selectedField: string;
      if (bestMatchField) {
        // Auto-confirm perfect matches, but give option to change
        const autoConfirm: string = await input.buttonsAsync(
          `Auto-mapped: "${column}" → "${bestMatchField.name}". Accept this mapping?`,
          [
            { label: 'Accept', value: 'accept', variant: 'primary' },
            { label: 'Change Mapping', value: 'change', variant: 'secondary' },
            { label: 'Skip Column', value: 'skip', variant: 'secondary' },
            { label: 'Cancel Import', value: 'cancel', variant: 'danger' }
          ]
        );
        
        if (autoConfirm === 'cancel') {
          output.text('Import cancelled by user.');
          return;
        } else if (autoConfirm === 'accept') {
          selectedField = bestMatchField.name;
          output.text(`✓ Mapped: "${column}" → "${bestMatchField.name}"`);
        } else if (autoConfirm === 'skip') {
          selectedField = 'skip';
        } else {
          selectedField = await input.selectAsync(
            `Map CSV column "${column}" to:`,
            fieldOptions
          );
        }
      } else {
        selectedField = await input.selectAsync(
          `Map CSV column "${column}" to:`,
          fieldOptions
        );
      }
      
      if (selectedField === 'cancel') {
        output.text('Import cancelled by user.');
        return;
      } else if (selectedField && selectedField !== 'skip') {
        fieldMap[column] = selectedField;
      }
    }
    
    // Ensure at least one field is mapped
    if (Object.keys(fieldMap).length === 0) {
      output.text('No fields mapped. Import cancelled.');
      return;
    }
    
    // Step 7: Show mapping preview
    output.markdown('## Import Configuration');
    output.text('The following columns will be imported:');
    
    const mappingTable = Object.entries(fieldMap).map(([csvCol, fieldName]) => {
      const field = table.getField(fieldName);
      return {
        'CSV Column': csvCol,
        'Table Field': fieldName,
        'Field Type': field?.type || 'Unknown'
      };
    });
    
    output.table(mappingTable);
    
    // Step 8: Final confirmation
    const confirmation: boolean = await input.buttonsAsync(
      `Ready to import ${csvData.length} records with ${duplicateHandling} duplicate handling. Continue?`,
      [
        { label: 'Import Data', value: true, variant: 'primary' },
        { label: 'Cancel', value: false, variant: 'secondary' }
      ]
    );
    
    if (!confirmation) {
      output.text('Import cancelled.');
      return;
    }
    
    // Step 9: Begin import process
    output.markdown('# Importing Data');
    
    // Initialize counters
    let created: number = 0;
    let updated: number = 0;
    let skipped: number = 0;
    let failed: number = 0;
    let processed: number = 0;
    const failedRows: Array<{ Row: number | string; Error: string; 'Data Sample': string }> = [];
    
    const batchSize: number = 10;
    const totalBatches: number = Math.ceil(csvData.length / batchSize);
    
    // Process data in batches
    for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
      const startIndex: number = batchIndex * batchSize;
      const endIndex: number = Math.min(startIndex + batchSize, csvData.length);
      const batch: Record<string, any>[] = csvData.slice(startIndex, endIndex);
      
      // Prepare records for this batch
      const recordsToCreate: Record<string, any>[] = [];
      const recordsToUpdate: Array<{ id: string; fields: Record<string, any> }> = [];
      
      for (let rowIndex = 0; rowIndex < batch.length; rowIndex++) {
        const row: Record<string, any> = batch[rowIndex];
        const actualRowIndex: number = startIndex + rowIndex;
        
        try {
          // Transform CSV data according to field mapping and types
          const recordData: Record<string, any> = {};
          
          for (const [csvColumn, fieldName] of Object.entries(fieldMap)) {
            const rawValue: any = row[csvColumn];
            
            if (rawValue !== undefined && rawValue !== null && rawValue !== '') {
              const field: Field | undefined = table.getField(fieldName);
              if (field) {
                recordData[fieldName] = transformValue(rawValue, field);
              }
            }
          }
          
          // Skip empty records
          if (Object.keys(recordData).length === 0) {
            skipped++;
          } else {
            // Handle duplicates
            let shouldCreateRecord = true;
            
            if (duplicateHandling !== 'allow' && uniqueField && uniqueColumnName) {
              const uniqueValue: any = row[uniqueColumnName];
              
              if (uniqueValue !== undefined && uniqueValue !== null && uniqueValue !== '') {
                // Check for existing record using efficient server-side filtering
                const existingRecords: RecordQueryResult = await table.selectRecordsAsync({
                  fields: [uniqueField.name],
                  where: `(${uniqueField.name},eq,${uniqueValue})`,
                  pageSize: 1
                });
                
                if (existingRecords.records.length > 0) {
                  const existingRecord: NocoDBRecord = existingRecords.records[0];
                  
                  if (duplicateHandling === 'update') {
                    recordsToUpdate.push({
                      id: existingRecord.id,
                      fields: recordData
                    });
                    shouldCreateRecord = false;
                  } else if (duplicateHandling === 'skip') {
                    skipped++;
                    shouldCreateRecord = false;
                  }
                }
              }
            }
            
            // Add to creation queue if not handled as duplicate
            if (shouldCreateRecord) {
              recordsToCreate.push({fields: recordData});
            }
          }
          
        } catch (error: any) {
          console.error(`Error processing row ${actualRowIndex + 1}:`, error);
          failedRows.push({
            'Row': actualRowIndex + 1,
            'Error': error.message || String(error),
            'Data Sample': JSON.stringify(row).substring(0, 100) + '...'
          });
          failed++;
        }
      }
      
      // Execute batch operations
      try {
        // Bulk create new records
        if (recordsToCreate.length > 0) {
          const createdIds: string[] = await table.createRecordsAsync(recordsToCreate);
          created += createdIds.length;
        }
        
        // Bulk update existing records
        if (recordsToUpdate.length > 0) {
          await table.updateRecordsAsync(recordsToUpdate);
          updated += recordsToUpdate.length;
        }
        
      } catch (batchError: any) {
        console.error(`Error in batch ${batchIndex + 1}:`, batchError);
        failed += recordsToCreate.length + recordsToUpdate.length;
        
        // Log batch failure
        failedRows.push({
          'Row': `Batch ${batchIndex + 1}`,
          'Error': `Batch operation failed: ${batchError.message || String(batchError)}`,
          'Data Sample': `${recordsToCreate.length} creates, ${recordsToUpdate.length} updates`
        });
      }
      
      processed = endIndex;
    }
    
    // Step 10: Show final results
    output.markdown('# Import Complete! 🎉');
    
    const resultsTable: Array<{ Metric: string; Count: number }> = [
      { 'Metric': 'Total Records Processed', 'Count': csvData.length },
      { 'Metric': 'Records Created', 'Count': created },
      { 'Metric': 'Records Updated', 'Count': updated },
      { 'Metric': 'Records Skipped', 'Count': skipped },
      { 'Metric': 'Failed Records', 'Count': failed }
    ];
    
    output.table(resultsTable);
    
    // Show failed records if any
    if (failedRows.length > 0) {
      output.markdown('## Failed Records');
      output.text(`${failedRows.length} records failed to import. First 10 failures:`);
      output.table(failedRows.slice(0, 10));
    }
    
    // Success summary
    const successRate: number = Math.round(((created + updated + skipped) / csvData.length) * 100);
    output.text(`Import completed with ${successRate}% success rate.`);
    
  } catch (error: any) {
    console.error('Import failed:', error);
    output.text(`Import failed: ${error.message || String(error)}`);
  }
}

/**
 * Transform CSV value to appropriate type based on field definition
 * @param {any} value - Raw CSV value
 * @param {Field} field - NocoDB field definition
 * @returns {any} Transformed value
 */
function transformValue(value: unknown, field: Field) {
  if (value === null || value === undefined || value === '') {
    return null;
  }
  
  const stringValue = String(value).trim();
  
  switch (field.type) {
    case UITypes.Number:
    case UITypes.Decimal:
    case UITypes.Currency:
    case UITypes.Percent:
    case UITypes.Rating:
      const numValue = parseFloat(stringValue.replace(/[^\d.-]/g, ''));
      return isNaN(numValue) ? null : numValue;
      
    case UITypes.Checkbox:
      return ['true', '1', 'yes', 'on', 'checked'].includes(stringValue.toLowerCase());
      
    case UITypes.Time:
      // Try to parse time format
      const timeMatch = stringValue.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
      if (timeMatch) {
        const [, hours, minutes, seconds = '00'] = timeMatch;
        return `${hours.padStart(2, '0')}:${minutes}:${seconds}`;
      }
      return stringValue;
      
    case UITypes.Year:
      const yearValue = parseInt(stringValue);
      return (yearValue >= 1900 && yearValue <= 2100) ? yearValue : null;
      
    case UITypes.Duration:
      // Try to parse duration format (h:mm:ss or seconds)
      if (stringValue.includes(':')) {
        const parts = stringValue.split(':');
        if (parts.length >= 2) {
          const hours = parseInt(parts[0]) || 0;
          const minutes = parseInt(parts[1]) || 0;
          const seconds = parseInt(parts[2]) || 0;
          return hours * 3600 + minutes * 60 + seconds; // Convert to seconds
        }
      }
      // Try parsing as seconds
      const durationSeconds = parseFloat(stringValue);
      return isNaN(durationSeconds) ? null : durationSeconds;
      
    case UITypes.MultiSelect:
      // Split on common delimiters
      if (stringValue.includes(',')) {
        return stringValue.split(',').map(s => s.trim()).filter(s => s);
      } else if (stringValue.includes(';')) {
        return stringValue.split(';').map(s => s.trim()).filter(s => s);
      } else if (stringValue.includes('|')) {
        return stringValue.split('|').map(s => s.trim()).filter(s => s);
      }
      return [stringValue];
      
    case UITypes.SingleSelect:
      return stringValue;
      
    case UITypes.JSON:
      try {
        return JSON.parse(stringValue);
      } catch {
        return stringValue; // Keep as string if not valid JSON
      }
      
    case UITypes.Email:
      // Basic email validation
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      return emailRegex.test(stringValue) ? stringValue : null;
      
    case UITypes.URL:
      // Basic URL validation
      try {
        new URL(stringValue);
        return stringValue;
      } catch {
        // Try adding https:// if it looks like a domain
        if (stringValue.includes('.') && !stringValue.includes(' ')) {
          try {
            new URL(`https://${stringValue}`);
            return `https://${stringValue}`;
          } catch {
            return null;
          }
        }
        return null;
      }
      
    case UITypes.PhoneNumber:
      // Clean phone number - keep digits, +, parentheses, hyphens, spaces
      return stringValue.replace(/[^\d+()-\s]/g, '');
      
    case UITypes.GeoData:
      // Try to parse as lat,lng or JSON
      if (stringValue.includes(',')) {
        const [lat, lng] = stringValue.split(',').map(s => parseFloat(s.trim()));
        if (!isNaN(lat) && !isNaN(lng)) {
          return { latitude: lat, longitude: lng };
        }
      }
      try {
        const geoData = JSON.parse(stringValue);
        if (geoData.latitude !== undefined && geoData.longitude !== undefined) {
          return geoData;
        }
      } catch {
        // Not valid JSON
      }
      return null;
      
    case UITypes.Attachment:
      // For attachments, we can only handle URLs
      try {
        new URL(stringValue);
        return [{
          url: stringValue,
          title: stringValue.split('/').pop() || 'attachment'
        }];
      } catch {
        return null;
      }
      
    case UITypes.User:
      // Try to find user by email
      const collaborator = base.getCollaborator(stringValue);
      if (collaborator) {
        return [collaborator.id]; // Users are stored as arrays of IDs
      }
      return null;
    case UITypes.Barcode:
    case UITypes.QrCode:
      return { value: stringValue };
      
    case UITypes.SingleLineText:
    case UITypes.LongText:
    case UITypes.SpecificDBType:
    default:
      return stringValue;
  }
}

// Execute the import
await importCSVData();
```

### Interactive Record Selection and Update

```javascript
// Example of selecting and updating records
async function updateRecords() {
  // Select a table
  const table = await input.tableAsync('Select a table:');
  
  // Select a view (optional)
  const useView = await input.buttonsAsync(
    'Do you want to select a specific view?',
    ['Yes', 'No, use all records']
  );
  
  let records;
  
  if (useView === 'Yes') {
    const view = await input.viewAsync('Select a view:', table);
    records = await view.selectRecordsAsync();
    output.text(`Selected view "${view.name}" with ${records.records.length} records.`);
  } else {
    records = await table.selectRecordsAsync();
    output.text(`Selected table "${table.name}" with ${records.records.length} records.`);
  }
  
  // No records found
  if (records.records.length === 0) {
    output.text('No records found. Nothing to update.');
    return;
  }
  
  // Ask which field to update
  const field = await input.fieldAsync('Select a field to update:', table);
  
  // Check if field is computed
  if (field.isComputed) {
    output.text(`Cannot update computed field "${field.name}". Please select a different field.`);
    return;
  }
  
  // Different update strategies based on field type
  let newValue;
  
  switch (field.type) {
    case 'SingleSelect':
      // Get options from field
      const options = field.options?.choices?.map(choice => choice.title) || [];
      newValue = await input.selectAsync(`Select new value for "${field.name}":`, options);
      break;
      
    case 'MultiSelect':
      // Get options from field
      const multiOptions = field.options?.choices?.map(choice => choice.title) || [];
      
      // Let user select multiple options (workaround since there's no direct multi-select)
      const selectedOptions = [];
      let selecting = true;
      
      while (selecting) {
        const option = await input.selectAsync(
          `Select an option to add (${selectedOptions.length} selected so far):`,
          [
            ...multiOptions.filter(opt => !selectedOptions.includes(opt)),
            '-- Done selecting --'
          ]
        );
        
        if (option === '-- Done selecting --') {
          selecting = false;
        } else {
          selectedOptions.push(option);
          output.text(`Added "${option}". Selected: ${selectedOptions.join(', ')}`);
        }
      }
      
      newValue = selectedOptions;
      break;
      
    case 'Checkbox':
      newValue = await input.buttonsAsync(
        `Set "${field.name}" to:`,
        [
          { label: 'Checked', value: true },
          { label: 'Unchecked', value: false }
        ]
      );
      break;
      
    case 'Date':
    case 'DateTime':
      newValue = await input.textAsync(
        `Enter new date for "${field.name}" (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS):`
      );
      break;
      
    case 'Number':
    case 'Currency':
    case 'Percent':
    case 'Rating':
      const numValue = await input.textAsync(`Enter new value for "${field.name}":`);
      // Convert to number
      newValue = numValue ? parseFloat(numValue) : null;
      break;
      
    default:
      // Default to text input for most field types
      newValue = await input.textAsync(`Enter new value for "${field.name}":`);
  }
  
  // Ask which records to update
  const updateTarget = await input.selectAsync(
    'Which records do you want to update?',
    [
      { label: 'All records in the current view/table', value: 'all' },
      { label: 'Select specific records', value: 'select' },
      { label: 'Records matching certain criteria', value: 'filter' }
    ]
  );
  
  let recordsToUpdate = [];
  
  if (updateTarget === 'all') {
    // Update all records
    recordsToUpdate = records.records;
  } else if (updateTarget === 'select') {
    // Let user select records one by one
    const selectedIds = [];
    let selecting = true;
    
    // Show a simplified list of records for selection
    const recordOptions = records.records.map(record => ({
      label: record.name,
      value: record.id
    }));
    
    while (selecting && recordOptions.length > 0) {
      const record = await input.selectAsync(
        `Select a record to update (${selectedIds.length} selected so far):`,
        [
          ...recordOptions.filter(opt => !selectedIds.includes(opt.value)),
          { label: '-- Done selecting --', value: 'done' }
        ]
      );
      
      if (record === 'done') {
        selecting = false;
      } else {
        selectedIds.push(record);
        output.text(`Added record "${recordOptions.find(opt => opt.value === record)?.label}"`);
      }
    }
    
    // Get the full records for the selected IDs
    recordsToUpdate = records.records.filter(record => selectedIds.includes(record.id));
  } else if (updateTarget === 'filter') {
    // Let user select a field to filter on
    const filterField = await input.fieldAsync('Select a field to filter on:', table);
    
    // Get filter value
    const filterValue = await input.textAsync(`Enter value to match in "${filterField.name}":`);
    
    // Filter records (case-insensitive for strings)
    recordsToUpdate = records.records.filter(record => {
      const value = record.getCellValue(filterField.name);
      
      if (typeof value === 'string' && typeof filterValue === 'string') {
        return value.toLowerCase().includes(filterValue.toLowerCase());
      } else {
        return value == filterValue; // Use loose equality for other types
      }
    });
  }
  
  // Confirm the update
  output.markdown('# Update Preview');
  output.text(`You are about to update the field "${field.name}" to "${newValue}" for ${recordsToUpdate.length} records.`);
  
  if (recordsToUpdate.length > 0) {
    output.text('Records to be updated:');
    // Show first few records
    const previewRecords = recordsToUpdate.slice(0, 5).map(record => ({
      'Name': record.name,
      'Current Value': record.getCellValueAsString(field.name)
    }));
    
    output.table(previewRecords);
    
    if (recordsToUpdate.length > 5) {
      output.text(`...and ${recordsToUpdate.length - 5} more records.`);
    }
  }
  
  const confirmation = await input.buttonsAsync(
    'Proceed with the update?',
    [
      { label: 'Update Records', value: true, variant: 'primary' },
      { label: 'Cancel', value: false, variant: 'secondary' }
    ]
  );
  
  if (!confirmation) {
    output.text('Update cancelled.');
    return;
  }
  
  // Perform the update
  output.text(`Updating ${recordsToUpdate.length} records...`);
  
  let successCount = 0;
  let failCount = 0;
  
  for (const record of recordsToUpdate) {
    try {
      await table.updateRecordAsync(record.id, {
        [field.name]: newValue
      });
      successCount++;
    } catch (error) {
      console.error(`Error updating record ${record.id}:`, error);
      failCount++;
    }
  }
  
  // Report results
  output.markdown('# Update Complete');
  output.text(`Successfully updated ${successCount} records.`);
  
  if (failCount > 0) {
    output.text(`Failed to update ${failCount} records. Check the console for details.`);
  }
}

// Run the update function
await updateRecords();
```

## Best Practices

1. **Use descriptive prompts** - Provide clear instructions in prompt labels so users know what input is expected.

2. **Handle null/cancelled responses** - Always check if the user provided a value, especially for optional inputs.

3. **Validate user input** - Validate text inputs to ensure they meet your requirements before using them.

4. **Show confirmation for destructive actions** - Use buttons with confirmation prompts before performing actions that modify data.

5. **Provide progress updates** - Show progress information between input prompts, especially for multi-step processes.

6. **Use appropriate input methods** - Choose the right input method for the data type (e.g., buttons for boolean choices, select for enumerated values).

7. **Limit choices when possible** - Use select or buttons instead of free-form text when the valid inputs are known.

8. **Handle errors gracefully** - Catch and handle errors that might occur when processing user input.

9. **Provide default values** - When possible, suggest sensible defaults to make the script easier to use.

10. **Break complex workflows into steps** - For scripts with many inputs, organize them into logical sections with appropriate headings.

## Related Resources

* [Output Methods](/docs/scripts/api-reference/output)
* [Table Object](/docs/scripts/api-reference/table)
* [View Object](/docs/scripts/api-reference/view)
* [Field Object](/docs/scripts/api-reference/field)
* [Record Object](/docs/scripts/api-reference/record)


# Output Methods
URL: /docs/scripts/api-reference/output

Documentation for the output object and its methods in NocoDB Scripts









The `output` object provides methods for displaying information to users during script execution. These methods allow you to create formatted output in various styles to communicate results, show progress, and present data in a readable format.

## Overview

The output methods enable you to:

* Display plain text messages
* Format content with Markdown for better readability
* Present data in formatted tables
* Inspect complex objects in an expandable format
* Clear previous output content

These methods help create a better user experience by providing clear, structured information about what your script is doing and what results it has produced.

## Available Methods

### output.text(message)

Displays plain text in the output area.

**Parameters:**

* `message` (`string | number | boolean | null`): The message to display

**Example:**

```javascript
// Basic usage
output.text('Processing complete.');

// Display numbers or other values
output.text(`Records processed: ${recordCount}`);
output.text(`Success: ${isSuccess}`);
```

**Output:**
<img alt="output.text example" src={__img0} placeholder="blur" />

### output.markdown()

Renders text with Markdown formatting.

**Parameters:**

* `content` (`string`): The Markdown content to render

**Example:**

````javascript
// Basic heading and text
output.markdown('# Monthly Sales Report');
output.markdown('Report generated on ' + new Date().toLocaleDateString());

// Lists
output.markdown('## Key Findings\n\n' +
  '* Sales increased by 15% compared to last month\n' +
  '* Top product: Widget X (1,245 units)\n' +
  '* Top region: West (42% of total)');

// Tables
output.markdown('## Summary Table\n\n' +
  '| Month | Revenue | Growth |\n' +
  '|-------|---------|--------|\n' +
  '| Jan   | $10,000 | -      |\n' +
  '| Feb   | $12,500 | 25%    |\n' +
  '| Mar   | $15,000 | 20%    |');
  
// Code blocks
output.markdown('## Example Query\n\n' +
  '```sql\n' +
  'SELECT product_name, SUM(quantity) as total_sold\n' +
  'FROM sales\n' +
  'GROUP BY product_name\n' +
  'ORDER BY total_sold DESC\n' +
  'LIMIT 5;\n' +
  '```');
````

**Output:**
<img alt="output.markdown example" src={__img1} placeholder="blur" />

### output.table()

Displays data in a formatted table.

**Parameters:**

* `data` (`Array<object> | object`): Array of objects where each object represents a row, or a single object to display

**Example:**

```javascript
// Display array of objects as table
const salesData = [
  { Product: 'Widget A', Units: 150, Revenue: 15000 },
  { Product: 'Widget B', Units: 100, Revenue: 8500 },
  { Product: 'Widget C', Units: 200, Revenue: 20000 }
];

output.table(salesData);

// Display a single object as a table
const summary = {
  'Total Units': 450,
  'Total Revenue': 43500,
  'Average Price': 96.67,
  'Best Seller': 'Widget C'
};

output.table(summary);
```

**Output:**
<img alt="output.table example" src={__img2} placeholder="blur" />

### output.inspect()

Displays an object in an expandable, interactive format for inspection.

**Parameters:**

* `data` (`any`): The data to inspect

**Example:**

```javascript
// Inspect a complex object
const projectData = {
  id: 'proj123',
  name: 'Website Redesign',
  status: 'In Progress',
  startDate: '2023-06-01',
  endDate: '2023-08-31',
  team: [
    { name: 'John Doe', role: 'Project Manager' },
    { name: 'Jane Smith', role: 'Designer' },
    { name: 'Bob Johnson', role: 'Developer' }
  ],
  tasks: [
    { 
      id: 'task1', 
      name: 'Wireframes', 
      status: 'Completed',
      assignee: 'Jane Smith',
      subtasks: [
        { name: 'Homepage wireframe', completed: true },
        { name: 'About page wireframe', completed: true },
        { name: 'Contact page wireframe', completed: true }
      ]
    },
    { 
      id: 'task2', 
      name: 'Design', 
      status: 'In Progress',
      assignee: 'Jane Smith',
      subtasks: [
        { name: 'Homepage design', completed: true },
        { name: 'About page design', completed: false },
        { name: 'Contact page design', completed: false }
      ]
    },
    { 
      id: 'task3', 
      name: 'Development', 
      status: 'Not Started',
      assignee: 'Bob Johnson',
      subtasks: [
        { name: 'Frontend setup', completed: false },
        { name: 'Homepage implementation', completed: false },
        { name: 'Testing', completed: false }
      ]
    }
  ]
};

output.inspect(projectData);
```

**Output:**
<img alt="output.inspect example" src={__img3} placeholder="blur" />

### output.clear()

Clears all previous output content.

**Example:**

```javascript
// Clear previous output before showing new results
output.clear();
output.markdown('# New Results');
output.text('Previous output has been cleared.');
```

## Practical Examples

### Creating a Structured Report

```javascript
// Structured report with sections and formatting
async function generateSalesReport() {
  // Get the Sales table
  const salesTable = base.getTable('Sales');
  
  // Query sales data
  const salesData = await salesTable.selectRecordsAsync({
    fields: ['Date', 'Product', 'Quantity', 'Unit Price', 'Total', 'Region']
  });
  
  // Clear any previous output
  output.clear();
  
  // Report header
  output.markdown('# Monthly Sales Report');
  output.markdown(`Generated on: ${new Date().toLocaleDateString()}`);
  output.markdown(`Data period: ${getLastMonthRange()}`);
  
  // Summary metrics
  const totalSales = calculateTotalSales(salesData.records);
  const totalUnits = calculateTotalUnits(salesData.records);
  const averageOrderValue = totalSales / salesData.records.length;
  
  output.markdown('## Summary Metrics');
  
  const summaryData = {
    'Total Sales': `$${totalSales.toLocaleString()}`,
    'Total Units Sold': totalUnits.toLocaleString(),
    'Number of Orders': salesData.records.length.toLocaleString(),
    'Average Order Value': `$${averageOrderValue.toFixed(2)}`,
    'Average Units per Order': (totalUnits / salesData.records.length).toFixed(1)
  };
  
  output.table(summaryData);
  
  // Products breakdown
  output.markdown('## Product Performance');
  
  const productData = getProductBreakdown(salesData.records);
  output.table(productData);
  
  // Regional breakdown
  output.markdown('## Regional Performance');
  
  const regionData = getRegionalBreakdown(salesData.records);
  output.table(regionData);
  
  
  // Daily trend
  output.markdown('## Daily Sales Trend');
  output.text('Daily sales for the past month:');
  
  const dailyData = getDailySales(salesData.records);
  output.table(dailyData);
  
  // Helper functions
  function getLastMonthRange() {
    const today = new Date();
    const lastMonth = new Date(today);
    lastMonth.setMonth(lastMonth.getMonth() - 1);
    
    return `${lastMonth.toLocaleDateString()} - ${today.toLocaleDateString()}`;
  }
  
  function calculateTotalSales(records) {
    return records.reduce((sum, record) => {
      return sum + (record.getCellValue('Total') || 0);
    }, 0);
  }
  
  function calculateTotalUnits(records) {
    return records.reduce((sum, record) => {
      return sum + (record.getCellValue('Quantity') || 0);
    }, 0);
  }
  
  function getProductBreakdown(records) {
    const productMap = {};
    
    for (const record of records) {
      const product = record.getCellValue('Product');
      const quantity = record.getCellValue('Quantity') || 0;
      const total = record.getCellValue('Total') || 0;
      
      if (!product) continue;
      
      if (!productMap[product]) {
        productMap[product] = {
          units: 0,
          sales: 0
        };
      }
      
      productMap[product].units += quantity;
      productMap[product].sales += total;
    }
    
    // Convert to array for table display
    return Object.entries(productMap).map(([product, data]) => ({
      'Product': product,
      'Units Sold': data.units,
      'Revenue': `$${data.sales.toLocaleString()}`,
      'Average Price': `$${(data.sales / data.units).toFixed(2)}`
    }));
  }
  
  function getRegionalBreakdown(records) {
    const regionMap = {};
    
    for (const record of records) {
      const region = record.getCellValue('Region') || 'Unknown';
      const total = record.getCellValue('Total') || 0;
      
      if (!regionMap[region]) {
        regionMap[region] = 0;
      }
      
      regionMap[region] += total;
    }
    
    // Calculate total for percentages
    const grandTotal = Object.values(regionMap).reduce((sum, val) => sum + val, 0);
    
    // Convert to array for table display
    return Object.entries(regionMap).map(([region, sales]) => ({
      'Region': region,
      'Revenue': `$${sales.toLocaleString()}`,
      'Percentage': `${((sales / grandTotal) * 100).toFixed(1)}%`
    }));
  }
  
  function getDailySales(records) {
    const dailyMap = {};
    
    for (const record of records) {
      const dateValue = record.getCellValue('Date');
      if (!dateValue) continue;
      
      const date = new Date(dateValue);
      const dateString = date.toISOString().split('T')[0]; // YYYY-MM-DD
      const total = record.getCellValue('Total') || 0;
      
      if (!dailyMap[dateString]) {
        dailyMap[dateString] = 0;
      }
      
      dailyMap[dateString] += total;
    }
    
    // Convert to array and sort by date
    return Object.entries(dailyMap)
      .map(([date, sales]) => ({
        'Date': new Date(date).toLocaleDateString(),
        'Sales': `$${sales.toLocaleString()}`
      }))
      .sort((a, b) => new Date(a.Date) - new Date(b.Date));
  }
}
 
// Run the report
await generateSalesReport();
```

## Best Practices

1. **Use clear headings** - Organize your output with markdown headings to create a logical structure that's easy to scan.

2. **Include timestamps** - Add timestamps to long-running processes so users know when actions occurred.

3. **Use the right output type** - Choose the appropriate output method for your content:
   * `text()` for simple messages
   * `markdown()` for formatted content with headers and lists
   * `table()` for tabular data
   * `inspect()` for complex nested objects

4. **Show progress updates** - For long-running operations, provide regular progress updates so users know the script is still working.

5. **Provide summary information** - Include summary metrics and totals to give users a quick overview of results.

6. **Format numbers and dates** - Use `toLocaleString()`, `toFixed()`, and other formatting methods to make numbers and dates more readable.

7. **Use visual elements** - Employ markdown features like lists, tables, and code blocks to enhance readability.

8. **Keep error messages informative** - Provide clear, actionable error messages that help users understand what went wrong and how to fix it.

## Related Resources

* [Input Methods](/docs/scripts/api-reference/input)
* [Table](/docs/scripts/api-reference/table)
* [Record](/docs/scripts/api-reference/record)


# RecordQueryResult
URL: /docs/scripts/api-reference/record-query-result

Documentation for the RecordQueryResult object in NocoDB Scripts

The `RecordQueryResult` object represents the results of a record query operation in NocoDB Scripts. It provides access to the records returned by the query and supports pagination for working with large datasets.

## Overview

When you query records from a table or view using `selectRecordsAsync()`, the method returns a `RecordQueryResult` object. This object allows you to:

* Access the array of returned records
* Check if there are more records available beyond what was initially returned
* Load additional pages of records when needed
* Get record count and pagination information
* Access specific records by ID

The RecordQueryResult object is designed to help you work efficiently with query results, especially when dealing with large tables where loading all records at once might not be practical.

## Properties

| Property         | Type                          | Description                                                       |
| ---------------- | ----------------------------- | ----------------------------------------------------------------- |
| `records`        | `ReadonlyArray<NocoDBRecord>` | Array of NocoDBRecord objects returned by the query               |
| `recordIds`      | `ReadonlyArray<string>`       | Array of record IDs (strings) returned by the query               |
| `hasMoreRecords` | `boolean`                     | Whether there are more records available beyond what was returned |
| `table`          | `Table`                       | Reference to the table from which records were queried            |
| `raw_data`       | `Array`                       | The raw underlying data from the API response                     |

## Methods

### getRecord

Retrieves a specific record from the query result by its ID.

**Parameters:**

* `recordId` (`string`): The ID of the record to retrieve

**Returns:** `NocoDBRecord` object corresponding to the specified ID

**Throws:** Error with message "No record matching "\[recordId]" found in query" if the record with the specified ID is not found in the query result

**Example:**

```javascript
// Get a table and query some records
const projectsTable = base.getTable('Projects');
const projectsResult = await projectsTable.selectRecordsAsync();

// Get a specific record from the results
try {
  const projectId = projectsResult.recordIds[0];
  const project = projectsResult.getRecord(projectId);
  
  output.text(`Project name: ${project.getCellValue('Name')}`);
} catch (error) {
  output.text(`Error retrieving record: ${error.message}`);
}
```

### loadMoreRecords

Loads the next page of records when hasMoreRecords is true. This method appends the newly loaded records to the existing records array and returns the same RecordQueryResult instance with the updated data.

**Returns:** `Promise<RecordQueryResult>` - A promise that resolves to the same RecordQueryResult instance with newly loaded records appended to the records array, or `null` if there are no more records to load

**Example:**

```javascript
// Get a table with many records
const tasksTable = base.getTable('Tasks');

// Initial query with a small page size
const tasksResult = await tasksTable.selectRecordsAsync({
  pageSize: 50 // Start with 50 records
});

while (tasksResult.hasMoreRecords) {
  await tasksResult.loadMoreRecords();
}

output.text(`Loaded ${tasksResult.records.length} tasks.`);
```

## Working with Query Results

### Basic Usage

```javascript
// Query records from a table
const projectsTable = base.getTable('Projects');
const queryResult = await projectsTable.selectRecordsAsync({
  fields: ['Name', 'Status', 'Due Date', 'Assigned To'],
  sorts: [
    { field: 'Due Date', direction: 'asc' }
  ],
  pageSize: 100
});

// Output basic information about the result
output.text(`Query returned ${queryResult.records.length} records.`);
output.text(`Has more records: ${queryResult.hasMoreRecords}`);

// Process the records
for (const record of queryResult.records) {
  const projectName = record.getCellValue('Name');
  const status = record.getCellValue('Status');
  const dueDate = record.getCellValue('Due Date');
  
  output.text(`- ${projectName} (${status}), due on ${dueDate}`);
}
```

### Paginated Processing

For tables with many records, use pagination to process records in batches:

```javascript
// Process all records in a large table using pagination
const customersTable = base.getTable('Customers');

// Process all records in a large table using pagination
async function processAllRecords() {
  let totalProcessed = 0;
  let batchNumber = 1;
  
  // Start with initial query
  let queryResult = await customersTable.selectRecordsAsync({
    fields: ['Name', 'Email', 'Last Order Date', 'Total Spend'],
    pageSize: 100
  });
  
  // Process records in batches
  do {
    const currentBatchSize = queryResult.records.length - totalProcessed;
    const startIndex = totalProcessed;
    
    output.text(`Processing batch ${batchNumber} (${currentBatchSize} records)...`);
    
    // Process only the new records from this batch
    for (let i = startIndex; i < queryResult.records.length; i++) {
      const record = queryResult.records[i];
      const data = await processCustomerRecord(record);
      output.inspect({
        recordId: record.id,
        name: record.getCellValue('Name'),
        status: data
      });
      totalProcessed++;
    }
    
    output.text(`✓ Completed batch ${batchNumber}: ${currentBatchSize} records processed`);
    
    // Load next batch if available
    if (queryResult.hasMoreRecords) {
      await queryResult.loadMoreRecords();
      batchNumber++;
      
      // Optional: Add delay between batches to avoid rate limits
      await new Promise(resolve => setTimeout(resolve, 100));
    }
    
  } while (queryResult.hasMoreRecords);
  
  output.text(`Total records processed: ${totalProcessed}`);
  return totalProcessed;
}



// Example of a record processing function
async function processCustomerRecord(record) {
  // Simulate processing time
  await new Promise(resolve => setTimeout(resolve, 10));
  
  // Get the last order date
  const lastOrderDate = record.getCellValue('Last Order Date');
  
  // Check if it's been more than 90 days since the last order
  if (lastOrderDate) {
    const daysSinceOrder = Math.floor((new Date() - new Date(lastOrderDate)) / (1000 * 60 * 60 * 24));
    
    if (daysSinceOrder > 90) {
      return 'inactive';
    } else {
      return 'active';
    }
  } else {
    return 'never-ordered';
  }
}

// Run the process
await processAllRecords();
```

### Finding Records in the Result

```javascript
// Query records and then find specific ones
const employeesTable = base.getTable('Employees');
const employeesResult = await employeesTable.selectRecordsAsync({
  fields: ['Name', 'Department', 'Position', 'Hire Date', 'Salary']
});

// Find employees from a specific department
const hrEmployees = employeesResult.records.filter(
  record => record.getCellValue('Department') === 'Human Resources'
);

output.text(`Found ${hrEmployees.length} employees in HR department.`);

// Find the employee with the highest salary
let highestPaidEmployee = null;
let highestSalary = 0;

for (const record of employeesResult.records) {
  const salary = record.getCellValue('Salary') || 0;
  
  if (salary > highestSalary) {
    highestSalary = salary;
    highestPaidEmployee = record;
  }
}

if (highestPaidEmployee) {
  output.text('Highest paid employee:');
  output.text(`- Name: ${highestPaidEmployee.getCellValue('Name')}`);
  output.text(`- Department: ${highestPaidEmployee.getCellValue('Department')}`);
  output.text(`- Position: ${highestPaidEmployee.getCellValue('Position')}`);
  output.text(`- Salary: $${highestPaidEmployee.getCellValue('Salary').toLocaleString()}`);
}
```

### Grouping Records

```javascript
// Query and group records
const tasksTable = base.getTable('Tasks');
const tasksResult = await tasksTable.selectRecordsAsync({
  fields: ['Task Name', 'Status', 'Priority', 'Assigned To', 'Due Date']
});

// Group tasks by status
const tasksByStatus = {};

for (const record of tasksResult.records) {
  const status = record.getCellValue('Status') || 'No Status';
  
  if (!tasksByStatus[status]) {
    tasksByStatus[status] = [];
  }
  
  tasksByStatus[status].push({
    id: record.id,
    name: record.getCellValue('Task Name'),
    priority: record.getCellValue('Priority'),
    assignee: record.getCellValue('Assigned To')?.name || 'Unassigned',
    dueDate: record.getCellValue('Due Date')
  });
}

// Display grouped tasks
output.markdown('# Tasks by Status');

for (const [status, tasks] of Object.entries(tasksByStatus)) {
  output.markdown(`## ${status} (${tasks.length})`);
  
  // Sort tasks by priority (if available)
  tasks.sort((a, b) => (b.priority || 0) - (a.priority || 0));
  
  // Display tasks in this group
  output.table(tasks);
}
```

## Analytics on Query Results

```javascript
// Query sales data and perform analytics
const salesTable = base.getTable('Sales');
const salesResult = await salesTable.selectRecordsAsync({
  fields: ['Date', 'Product', 'Quantity', 'Unit Price', 'Total', 'Sales Rep', 'Region']
});

while(salesResult.hasMoreRecords) {
  await salesResult.loadMoreRecords()
}

// Calculate total sales
let totalSales = 0;
const salesByProduct = {};
const salesByRep = {};
const salesByRegion = {};
const salesByMonth = {};

for (const record of salesResult.records) {
  const total = record.getCellValue('Total') || 0;
  const product = record.getCellValue('Product') || 'Unknown';
  const salesRep = record.getCellValue('Sales Rep')?.name || 'Unknown';
  const region = record.getCellValue('Region') || 'Unknown';
  const date = record.getCellValue('Date');
  
  // Add to total sales
  totalSales += total;
  
  // Group by product
  if (!salesByProduct[product]) {
    salesByProduct[product] = 0;
  }
  salesByProduct[product] += total;
  
  // Group by sales rep
  if (!salesByRep[salesRep]) {
    salesByRep[salesRep] = 0;
  }
  salesByRep[salesRep] += total;
  
  // Group by region
  if (!salesByRegion[region]) {
    salesByRegion[region] = 0;
  }
  salesByRegion[region] += total;
  
  // Group by month
  if (date) {
    const month = new Date(date).toLocaleString('default', { month: 'long', year: 'numeric' });
    if (!salesByMonth[month]) {
      salesByMonth[month] = 0;
    }
    salesByMonth[month] += total;
  }
}

// Prepare data for output
output.markdown('# Sales Analysis');
output.text(`Total Sales: $${totalSales.toLocaleString()}`);
output.text(`Number of Transactions: ${salesResult.records.length}`);

// Sales by product
output.markdown('## Sales by Product');
const productData = Object.entries(salesByProduct)
  .map(([product, total]) => ({ Product: product, 'Total Sales': total }))
  .sort((a, b) => b['Total Sales'] - a['Total Sales']);
output.table(productData);

// Sales by rep
output.markdown('## Sales by Representative');
const repData = Object.entries(salesByRep)
  .map(([rep, total]) => ({ 'Sales Rep': rep, 'Total Sales': total }))
  .sort((a, b) => b['Total Sales'] - a['Total Sales']);
output.table(repData);

// Sales by region
output.markdown('## Sales by Region');
const regionData = Object.entries(salesByRegion)
  .map(([region, total]) => ({ Region: region, 'Total Sales': total }))
  .sort((a, b) => b['Total Sales'] - a['Total Sales']);
output.table(regionData);

// Sales by month
output.markdown('## Sales by Month');
const monthData = Object.entries(salesByMonth)
  .map(([month, total]) => ({ Month: month, 'Total Sales': total }))
  .sort((a, b) => {
    // Sort chronologically
    const dateA = new Date(a.Month);
    const dateB = new Date(b.Month);
    return dateA - dateB;
  });
output.table(monthData);
```

## Best Practices

1. **Use appropriate page sizes** - Choose a pageSize that balances performance and memory usage. The default is 50 records, but you may need larger or smaller page sizes based on your needs.

2. **Check for more records** - Always check the `hasMoreRecords` property to determine if you need to load additional pages of records.

3. **Process records in batches** - For large tables, process records in batches rather than loading all records at once.

4. **Track record indices when paginating** - Since `loadMoreRecords()` appends to the existing records array, keep track of which records you've already processed to avoid duplicate processing.

5. **Handle linked records carefully** - Remember that linked records might require additional queries to retrieve full details.

6. **Use getRecord() for lookups** - When you need to find a specific record by ID, use the `getRecord()` method instead of searching through the records array.

7. **Await async operations** - Always use `await` when calling async methods to ensure proper execution flow.

## Related Resources

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


# Record
URL: /docs/scripts/api-reference/record

Documentation for the NocoDBRecord object in NocoDB Scripts

The `NocoDBRecord` object represents a single row of data in a NocoDB table and provides methods to access and work with the cell values within that record.

## Overview

Records are typically retrieved from tables or views using query methods like `selectRecordsAsync()` or `selectRecordAsync()`. Each NocoDBRecord object provides access to:

* The record's unique identifier
* The record's primary display value (name)
* All cell values in the record
* Formatted string representations of cell values

Working with NocoDBRecord objects is central to most NocoDB scripts, as they allow you to read, manipulate, and interpret the data in your base with rich type support.

## Properties

| Property | Type     | Description                                                            |
| -------- | -------- | ---------------------------------------------------------------------- |
| `id`     | `string` | The unique identifier for this record                                  |
| `name`   | `string` | The primary display value for this record (derived from display field) |

## Methods

### getCellValue

Retrieves the value of a specific cell in the record.

**Parameters:**

* `fieldOrFieldIdOrName` (`Field | string`): The field, field ID, or field name to get the value for

**Returns:** The value of the cell in a format determined by the field type (see Cell Value Types section)

**Throws:** Error if the field is not found or not included in the query

**Example:**

```javascript
// Get the Projects table
const projectsTable = base.getTable('Projects');

// Query a specific record
const projectRecord = await projectsTable.selectRecordAsync('123');

if (projectRecord) {
  // Get cell values using field names
  const projectName = projectRecord.getCellValue('Project Name');
  const dueDate = projectRecord.getCellValue('Due Date');
  const status = projectRecord.getCellValue('Status');
  
  output.text(`Project: ${projectName}`);
  output.text(`Due Date: ${dueDate}`);
  output.text(`Status: ${status}`);
  
  // Get a cell value using a field object
  const assignedToField = projectsTable.getField('Assigned To');
  const assignedTo = projectRecord.getCellValue(assignedToField);
  
  if (assignedTo) {
    output.text(`Assigned To: ${assignedTo.name}`);
  } else {
    output.text('This project is unassigned.');
  }
}
```

### getCellValueAsString

Gets a cell value formatted as a string, applying appropriate formatting based on the field type.

**Parameters:**

* `fieldOrFieldIdOrName` (`Field | string`): The field, field ID, or field name to get the value for

**Returns:** `string` - A string representation of the cell value with proper field-type formatting

**Throws:** Error if the field is not found or not included in the query

**Note:** This method provides comprehensive formatting for all field types including currency, dates, durations, percentages, and more.

**Example:**

```javascript
// Get the Invoices table
const invoicesTable = base.getTable('Invoices');

// Query a specific record
const invoiceRecord = await invoicesTable.selectRecordAsync('123');

if (invoiceRecord) {
  // Get formatted string values
  const invoiceNumber = invoiceRecord.getCellValueAsString('Invoice Number');
  const amount = invoiceRecord.getCellValueAsString('Amount'); // Formatted as currency
  const date = invoiceRecord.getCellValueAsString('Date'); // Formatted as date
  const isPaid = invoiceRecord.getCellValueAsString('Paid'); // "Checked" or "Unchecked"
  const attachments = invoiceRecord.getCellValueAsString('Attachments'); // Comma-separated file names
  
  // Output the formatted values
  output.text(`Invoice: ${invoiceNumber}`);
  output.text(`Amount: ${amount}`);
  output.text(`Date: ${date}`);
  output.text(`Paid: ${isPaid}`);
  output.text(`Attachments: ${attachments}`);
}
```

## Cell Value Types

Different field types return values in specific formats when using `getCellValue()`. Here's a reference for the most common field types:

### 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
const quantity = record.getCellValue('Quantity'); // number or null
const price = record.getCellValue('Price'); // number or null
const discount = record.getCellValue('Discount'); // number or null (without % sign)
```

### Boolean Fields

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

### Date and Time Fields

```javascript
// Date
const dueDate = record.getCellValue('Due Date'); // string in ISO format or null
// e.g., "2023-08-15"

// DateTime
const createdAt = record.getCellValue('Created At'); // string in ISO format or null
// e.g., "2023-08-15T14:30:00.000Z"

// Time
const startTime = record.getCellValue('Start Time'); // string in ISO format or null
// e.g., "14:30:00.000"
```

### Selection Fields

```javascript
// Single Select
const status = record.getCellValue('Status'); // string or null
// e.g., "In Progress"

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

### Relationship Fields

```javascript
// LinkToAnotherRecord (one to one / belongs to relationship)
const project = record.getCellValue('Project'); // NocoDBRecord object or null
if (project) {
  output.text(`Project ID: ${project.id}`);
  output.text(`Project Name: ${project.name}`);
}

// LinkToAnotherRecord (many-to-many / has-many relationship)
const team = record.getCellValue('Team Members'); // RecordQueryResult object or null
while (team.hasMoreRecords) {
  await team.loadMoreRecords();
}

output.text(`Team members: ${team.records.length}`);

// Links (new field type for relationships)
const linkedProjects = record.getCellValue('Related Projects');
// For many-to-many/has-many: returns RecordQueryResult object or null
// For belongs-to/one-to-one: returns NocoDBRecord object or null
```

### Attachment Field

```javascript
// Attachment
const documents = record.getCellValue('Documents'); // Array of attachment objects or empty array

/*
Each attachment object has:
{
  url: string,
  title: string,
  mimetype: string,
  size: number,
  signedUrl?: string,
  thumbnails?: {
    tiny: { signedUrl: string },
    small: { signedUrl: string },
    card_cover: { signedUrl: string }
  }
}
*/

if (documents && documents.length > 0) {
  for (const doc of documents) {
    output.text(`File: ${doc.title}`);
    output.text(`Type: ${doc.mimetype}`);
    output.text(`Size: ${doc.size} bytes`);
    output.text(`URL: ${doc.url}`);
  }
}
```

### User Field

```javascript
// User (single)
const assignee = record.getCellValue('Assigned To'); // Collaborator object or null

if (assignee) {
  output.text(`Assignee ID: ${assignee.id}`);
  output.text(`Assignee Name: ${assignee.name}`);
  output.text(`Assignee Email: ${assignee.email}`);
}

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

if (reviewers && reviewers.length > 0) {
  for (const reviewer of reviewers) {
    output.text(`Reviewer ID: ${reviewer.id}`);
    output.text(`Reviewer Name: ${reviewer.name}`);
    output.text(`Reviewer Email: ${reviewer.email}`);
  }
}
```

### Formula Field

```javascript
// Formula fields return a value of the appropriate type based on the formula's output type
const fullName = record.getCellValue('Full Name'); // string or null
const age = record.getCellValue('Age'); // number or null
const isAdult = record.getCellValue('Is Adult'); // boolean or null
```

### Lookup Field

```javascript
// Lookup fields return values of the type that is being looked up
const managerName = record.getCellValue('Manager Name'); // string or null
const departmentSize = record.getCellValue('Department Size'); // number or null

// Lookup to multiple values
const teamEmails = record.getCellValue('Team Emails'); // Array of values or empty array
```

### Rollup Field

```javascript
// Rollup fields return values based on the rollup function and field type
const totalHours = record.getCellValue('Total Hours'); // number or null
const averageScore = record.getCellValue('Average Score'); // number or null
const taskCount = record.getCellValue('Task Count'); // number or null
```

## Working with Records

### Reading Record Data

```javascript
// Get the Tasks table
const tasksTable = base.getTable('Tasks');

// Get a specific record
const taskRecord = await tasksTable.selectRecordAsync('123', {
  fields: ['Task Name', 'Description', 'Status', 'Due Date', 'Assigned To', 'Priority']
});

if (taskRecord) {
  // Read basic properties
  output.text(`Record ID: ${taskRecord.id}`);
  output.text(`Primary Value: ${taskRecord.name}`);
  
  // Read values using getCellValue
  const taskName = taskRecord.getCellValue('Task Name');
  const description = taskRecord.getCellValue('Description');
  const status = taskRecord.getCellValue('Status');
  const dueDate = taskRecord.getCellValue('Due Date');
  const assignedTo = taskRecord.getCellValue('Assigned To');
  const priority = taskRecord.getCellValue('Priority');
  
  // Display the task information
  output.markdown(`# Task: ${taskName}`);
  output.text(`Description: ${description || 'No description provided'}`);
  output.text(`Status: ${status || 'Not set'}`);
  output.text(`Due Date: ${dueDate ? new Date(dueDate).toLocaleDateString() : 'No due date'}`);
  
  if (assignedTo) {
    output.text(`Assigned To: ${assignedTo.name} (${assignedTo.email})`);
  } else {
    output.text('This task is unassigned.');
  }
  
  output.text(`Priority: ${priority || 'Not set'}`);
}
```

### Comparing Records

```javascript
// Get the Employees table
const employeesTable = base.getTable('Employees');

// Get two employee records
const employee1 = await employeesTable.selectRecordAsync('123');
const employee2 = await employeesTable.selectRecordAsync('456');

if (employee1 && employee2) {
  // Compare salary values
  const salary1 = employee1.getCellValue('Salary') || 0;
  const salary2 = employee2.getCellValue('Salary') || 0;
  
  // Compare departments
  const dept1 = employee1.getCellValue('Department');
  const dept2 = employee2.getCellValue('Department');
  
  // Compare hire dates
  const hireDate1 = employee1.getCellValue('Hire Date');
  const hireDate2 = employee2.getCellValue('Hire Date');
  
  // Output comparison
  output.markdown(`# Employee Comparison`);
  output.markdown(`## ${employee1.getCellValue('Name')} vs. ${employee2.getCellValue('Name')}`);
  
  output.text(`Salary: $${salary1.toLocaleString()} vs. $${salary2.toLocaleString()}`);
  output.text(`Department: ${dept1} vs. ${dept2}`);
  
  if (hireDate1 && hireDate2) {
    const date1 = new Date(hireDate1);
    const date2 = new Date(hireDate2);
    const seniorityDiff = Math.floor((date2 - date1) / (1000 * 60 * 60 * 24));
    
    if (seniorityDiff > 0) {
      output.text(`${employee1.getCellValue('Name')} has been with the company ${seniorityDiff} days longer.`);
    } else if (seniorityDiff < 0) {
      output.text(`${employee2.getCellValue('Name')} has been with the company ${Math.abs(seniorityDiff)} days longer.`);
    } else {
      output.text('Both employees were hired on the same day.');
    }
  }
}
```

### Working with Linked Records

```javascript
// Get the Projects and Tasks tables
const projectsTable = base.getTable('Projects');
const tasksTable = base.getTable('Tasks');

// Get a project record with its linked tasks
const projectRecord = await projectsTable.selectRecordAsync('25', {
  fields: ['Project Name', 'Description', 'Status', 'Tasks']
});
 
if (projectRecord) {
  const projectName = projectRecord.getCellValue('Project Name');
  const tasks = projectRecord.getCellValue('Tasks') || [];

  while(tasks.hasMoreRecords) {
    await tasks.loadMoreRecords()
  }
  
  output.markdown(`# Project: ${projectName}`);
  output.text(`Status: ${projectRecord.getCellValue('Status')}`);
  output.text(`Number of Tasks: ${tasks.records.length}`);
  
  if (tasks.records.length > 0) {
    // Direct access to linked record information
    output.markdown('## Task Summary');
    
    for (const task of tasks.records) {
      output.text(`- ${task.name}`);
    }
    
    // For detailed task information, we need to query each task
    output.markdown('## Detailed Task Information');
    
    // Get all task IDs
    const taskIds = tasks.recordIds
    
    // Query the tasks with additional fields
    const taskRecords = await tasksTable.selectRecordsAsync({
      fields: ['Task Name', 'Status', 'Due Date', 'Assigned To'],
      recordIds: taskIds
    });
    
    // Process each task with full details
    for (const taskRecord of taskRecords.records) {
      const taskName = taskRecord.getCellValue('Task Name');
      const status = taskRecord.getCellValue('Status');
      const dueDate = taskRecord.getCellValue('Due Date');
      const assignedTo = taskRecord.getCellValue('Assigned To');
      
      output.markdown(`### ${taskName}`);
      output.text(`Status: ${status || 'Not set'}`);
      output.text(`Due Date: ${dueDate ? new Date(dueDate).toLocaleDateString() : 'No due date'}`);
      output.text(`Assigned To: ${assignedTo ? assignedTo.name : 'Unassigned'}`);
    }
  }
}
```

### Using Record Values in Calculations

```javascript
// Get the Sales table
const salesTable = base.getTable('Sales');

// Query sales records for a specific period
const salesRecords = await salesTable.selectRecordsAsync({
  fields: ['Date', 'Product', 'Quantity', 'Unit Price', 'Total']
});

while(salesRecords.hasMoreRecords) {
  await salesRecords.loadMoreRecords()
}

// Perform calculations with record values
let totalSales = 0;
let totalQuantity = 0;
let highestSale = { amount: 0, product: null, date: null };

for (const record of salesRecords.records) {
  const quantity = record.getCellValue('Quantity') || 0;
  const total = record.getCellValue('Total') || 0;
  
  // Update totals
  totalSales += total;
  totalQuantity += quantity;
  
  // Check if this is the highest sale
  if (total > highestSale.amount) {
    highestSale = {
      amount: total,
      product: record.getCellValue('Product'),
      date: record.getCellValue('Date')
    };
  }
}

// Calculate average sale value
const averageSale = salesRecords.records.length > 0 
  ? totalSales / salesRecords.records.length 
  : 0;

// Output the results
output.markdown('# Sales Analysis');
output.text(`Total Sales: $${totalSales.toLocaleString()}`);
output.text(`Total Quantity: ${totalQuantity.toLocaleString()} units`);
output.text(`Average Sale: $${averageSale.toFixed(2)}`);

if (highestSale.product) {
  output.markdown('## Highest Sale');
  output.text(`Product: ${highestSale.product}`);
  output.text(`Amount: $${highestSale.amount.toLocaleString()}`);
  output.text(`Date: ${highestSale.date ? new Date(highestSale.date).toLocaleDateString() : 'Unknown'}`);
}
```

### Complex Record Processing

```javascript
// Get the Inventory table
const inventoryTable = base.getTable('Inventory');

// Get all inventory records
const inventoryRecords = await inventoryTable.selectRecordsAsync({
  fields: ['Item Name', 'Category', 'Quantity', 'Reorder Level', 'Supplier', 'Price']
});

// Identify items that need to be reordered
const reorderItems = [];
const lowStockItems = [];
const outOfStockItems = [];

for (const record of inventoryRecords.records) {
  const itemName = record.getCellValue('Item Name');
  const quantity = record.getCellValue('Quantity') || 0;
  const reorderLevel = record.getCellValue('Reorder Level') || 0;
  
  // Add to appropriate lists
  if (quantity === 0) {
    outOfStockItems.push({
      id: record.id,
      name: itemName,
      category: record.getCellValue('Category'),
      supplier: record.getCellValue('Supplier'),
      price: record.getCellValue('Price')
    });
  } else if (quantity <= reorderLevel) {
    reorderItems.push({
      id: record.id,
      name: itemName,
      category: record.getCellValue('Category'),
      currentQuantity: quantity,
      reorderLevel: reorderLevel,
      supplier: record.getCellValue('Supplier'),
      price: record.getCellValue('Price')
    });
  } else if (quantity <= reorderLevel * 1.2) {
    // Items at 120% or less of reorder level are considered low stock
    lowStockItems.push({
      id: record.id,
      name: itemName,
      category: record.getCellValue('Category'),
      currentQuantity: quantity,
      reorderLevel: reorderLevel
    });
  }
}

// Group reorder items by supplier
const itemsBySupplier = {};

for (const item of reorderItems) {
  const supplier = item.supplier || 'Unknown Supplier';
  
  if (!itemsBySupplier[supplier]) {
    itemsBySupplier[supplier] = [];
  }
  
  itemsBySupplier[supplier].push(item);
}

// Output the inventory report
output.markdown('# Inventory Report');

if (outOfStockItems.length > 0) {
  output.markdown('## Out of Stock Items');
  output.table(outOfStockItems);
}

if (reorderItems.length > 0) {
  output.markdown('## Items to Reorder');
  output.table(reorderItems);
  
  output.markdown('## Reorder by Supplier');
  for (const [supplier, items] of Object.entries(itemsBySupplier)) {
    output.markdown(`### ${supplier}`);
    
    // Calculate order totals
    const orderTotal = items.reduce((sum, item) => sum + (item.price || 0), 0);
    
    output.table(items);
    output.text(`Order Total: $${orderTotal.toLocaleString()}`);
  }
}

if (lowStockItems.length > 0) {
  output.markdown('## Low Stock Items');
  output.table(lowStockItems);
}
```

## Best Practices

1. **Check for null values** - Always handle the possibility of null or undefined field values with default values or conditional logic.

2. **Use appropriate methods** - Use `getCellValue()` when you need the actual value for calculations or logic, and `getCellValueAsString()` for display purposes.

3. **Handle linked records properly** - Remember that linked records from `getCellValue()` only contain minimal information (id and name). For detailed information, query the linked records from their table.

4. **Field parameter consistency** - Prefer using field names (strings) for consistency unless you need special field object functionality.

5. **Error handling** - Wrap record operations in try-catch blocks to handle possible errors gracefully.

6. **Update records with care** - When updating records, preserve existing values for fields you don't intend to change.

## Related Resources

* [Base](/docs/scripts/api-reference/base)
* [Table](/docs/scripts/api-reference/table)
* [Field](/docs/scripts/api-reference/field)
* [RecordQueryResult](/docs/scripts/api-reference/record-query-result)


# Script Settings
URL: /docs/scripts/api-reference/script-settings

Documentation for script settings and configuration using input.config()

The `input.config()` method allows you to define settings and inputs for your NocoDB script, creating a configuration form that appears when users run the script. This feature enables you to create reusable, configurable scripts with a friendly user interface.

## Overview

When you use `input.config()` at the beginning of your script, NocoDB generates a settings form based on your configuration. This form is displayed to users before the script runs, allowing them to:

* Enter text values
* Select options from dropdowns
* Choose tables, views, and fields
* Provide numeric inputs
* Configure other script-specific settings

The values entered by users are returned as an object that you can use throughout your script.

## Basic Usage

```javascript
// Define script settings
const config = input.config({
  title: "My Script",
  description: "This script processes data based on your configuration.",
  items: [
    input.config.table('sourceTable', {
      label: 'Source Table',
      description: 'Select the table containing your source data'
    }),
    input.config.text('prefix', {
      label: 'Record Prefix',
      description: 'Prefix to add to processed record names'
    }),
    input.config.number('limit', {
      label: 'Processing Limit',
      description: 'Maximum number of records to process'
    })
  ]
});

// Use the configured values
const table = base.getTable(config.sourceTable);
const prefix = config.prefix;
const limit = config.limit;

output.text(`Using table: ${table.name}`);
output.text(`Using prefix: ${prefix}`);
output.text(`Processing limit: ${limit}`);

// Rest of your script...
```

## Configuration Options

### Main Configuration Object

The `input.config()` method accepts a configuration object with the following properties:

| Property      | Type                | Description                                                    |
| ------------- | ------------------- | -------------------------------------------------------------- |
| `title`       | `string`            | Title of the script, displayed at the top of the settings form |
| `description` | `string`            | Description of what the script does (supports some markdown)   |
| `items`       | `Array<ConfigItem>` | Array of configuration items for the settings form             |

### Configuration Item Types

The `input.config` object provides several methods for creating different types of configuration items:

#### input.config.table()

Creates a table selector in the settings form.

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options` (optional): Object with additional options:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `default` (`string`): Default table ID to pre-select

**Example:**

```javascript
input.config.table('contactsTable', {
  label: 'Contacts Table',
  description: 'Select the table containing your contacts',
  default: 'tbl_abc123' // Optional: pre-select a table by ID
})
```

#### input.config.view()

Creates a view selector in the settings form (requires a parentTable to be defined first).

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options`: Object with the following properties:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `parentTable` (`string`): The key of a previously defined table setting
  * `default` (`string`): Default view ID to pre-select

**Example:**

```javascript
input.config.view('activeContactsView', {
  label: 'Active Contacts View',
  description: 'Select the view containing active contacts only',
  parentTable: 'contactsTable', // References a previously defined table setting
  default: 'vw_xyz789' // Optional: pre-select a view by ID
})
```

#### input.config.field()

Creates a field selector in the settings form (requires a parentTable to be defined first).

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options`: Object with the following properties:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `parentTable` (`string`): The key of a previously defined table setting
  * `default` (`string`): Default field ID to pre-select

**Example:**

```javascript
input.config.field('emailField', {
  label: 'Email Field',
  description: 'Select the field containing email addresses',
  parentTable: 'contactsTable', // References a previously defined table setting
  default: 'fld_email456' // Optional: pre-select a field by ID
})
```

#### input.config.text()

Creates a text input in the settings form.

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options` (optional): Object with additional options:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `default` (`string`): Default text value to pre-fill

**Example:**

```javascript
input.config.text('emailSubject', {
  label: 'Email Subject',
  description: 'Subject line for the email notification',
  default: 'Weekly Report' // Optional: pre-fill with default text
})
```

#### input.config.select()

Creates a dropdown select menu in the settings form.

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options`: Object with the following properties:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `options` (`Array<{value: string, label?: string}>`): Array of options for the dropdown
  * `default` (`string`): Default option value to pre-select (must be one of the defined option values)

**Example:**

```javascript
input.config.select('priority', {
  label: 'Task Priority',
  description: 'Select the priority level for the tasks',
  options: [
    { value: 'high', label: 'High Priority' },
    { value: 'medium', label: 'Medium Priority' },
    { value: 'low', label: 'Low Priority' }
  ],
  default: 'medium' // Optional: pre-select 'Medium Priority'
})
```

#### input.config.number()

Creates a numeric input in the settings form.

**Parameters:**

* `key` (`string`): Unique identifier for this setting
* `options` (optional): Object with additional options:
  * `label` (`string`): Display label for the setting
  * `description` (`string`): Description text explaining the setting
  * `default` (`number`): Default number value to pre-fill

**Example:**

```javascript
input.config.number('daysAhead', {
  label: 'Days Ahead',
  description: 'Number of days to look ahead in the schedule',
  default: 7 // Optional: pre-fill with default number
})
```

## Best Practices

1. **Order matters** - Place related items together, and make sure dependent fields (like views or fields that depend on a table selection) appear after their parent items.

2. **Provide clear labels and descriptions** - Use descriptive labels and helpful descriptions to guide users in making the right choices.

3. **Use select inputs for constrained choices** - When there's a fixed set of options, use `input.config.select()` rather than free-form text input.

4. **Validate configuration** - Check that all required configuration values are present and valid before proceeding with your script.

5. **Keep it simple** - Don't overwhelm users with too many options. Focus on the essential configuration needed for your script.

6. **Test with different configurations** - Make sure your script works correctly with various combinations of settings.

## Limitations

1. **Limited input types** - Only the input types described above are supported. For more complex inputs, you may need to use the interactive `input` methods after the script starts.

2. **Order dependency** - When using dependent fields (like a view that depends on a table), the parent must be defined first.

## Related Resources

* [Input](/docs/scripts/api-reference/input)
* [Base](/docs/scripts/api-reference/base)
* [Table](/docs/scripts/api-reference/table)
* [Field](/docs/scripts/api-reference/field)


# Script Steps
URL: /docs/scripts/api-reference/script-steps

Visually guide users through your script with clear subsections

Script Steps let your users see what’s happening while your script runs—making complex operations easier to follow with clear, real-time visual subsections.

Instead of a blank screen, users get progress feedback through titled steps, icons, colors, and descriptions—bringing transparency, trust, and a polished experience.

<img src="/img/v2/scripts/steps.png" alt="script steps" style={{ width: "50%" }} />

### Basic Step

Add a step with just a title:

```js
script.step('Loading your data...');
```

<img src="/img/v2/scripts/simple-step.png" alt="script steps" style={{ width: "50%" }} />

### Detailed Step

Enhance the step with optional visuals:

```js
script.step({
  title: 'Getting Latest Data',
  description: 'Fetching records from your selected table',
  color: 'blue',
  icon: 'download'
});
```

<img src="/img/v2/scripts/detailed-step.png" alt="detailed step" style={{ width: "50%" }} />

## Customization Options

### Colors

Use colors to indicate the type of action:

| Color    | Use Case                         |
| -------- | -------------------------------- |
| `blue`   | General info, loading data       |
| `green`  | Success, completed actions       |
| `yellow` | Validation, warnings             |
| `red`    | Errors, critical issues          |
| `purple` | Special or custom operations     |
| `orange` | Updates or changes               |
| `gray`   | Background or neutral operations |

### Icons

Suggested icons for common use cases:

| Icon          | Meaning                     |
| ------------- | --------------------------- |
| `download`    | Fetching or retrieving data |
| `upload`      | Sending or submitting data  |
| `database`    | Interacting with tables     |
| `sync`        | Updating or syncing         |
| `checkCircle` | Completion or success       |
| `settings`    | Configuration steps         |
| `mail`        | Email-related actions       |

## Full Example

Here’s a complete example that guides the user through an import process:

```js
// Step 1: Start import
script.step({
  title: 'Starting Import',
  description: 'Preparing to import customer data',
  color: 'blue',
  icon: 'database'
});

const sourceTable = await input.tableAsync('Which table has your customer data?');
const targetTable = await input.tableAsync('Which table should we import to?');

// Step 2: Validate data
script.step({
  title: 'Checking Your Data',
  description: 'Making sure the data will import correctly',
  color: 'yellow',
  icon: 'checkCircle'
});

const sourceRecords = await sourceTable.selectRecordsAsync();
if (sourceRecords.length === 0) {
  output.text('No records found to import!');
  return;
}

// Step 3: Import records
script.step({
  title: 'Importing Records',
  description: `Moving ${sourceRecords.length} customer records`,
  color: 'purple',
  icon: 'sync'
});

const newRecords = sourceRecords.map(record => ({
  'Customer Name': record.getCellValue('Name'),
  'Email': record.getCellValue('Email'),
  'Import Date': new Date()
}));

await targetTable.createRecordsAsync(newRecords);

// Step 4: Finish
script.step({
  title: 'Import Complete',
  description: `Successfully imported ${newRecords.length} customers`,
  color: 'green',
  icon: 'checkCircle'
});

script.clear();
output.text(`✅ Done! Imported ${newRecords.length} customer records.`);
```

## Advanced Usage

### Manually Clear a Step

Steps auto-clear when a new one starts, but you can also clear them explicitly:

```js
script.step('Processing...');
await someAsyncTask();
script.clear();
```

### Handling Errors Gracefully

Show errors in context to keep users informed:

```js
script.step({
  title: 'Sending Emails',
  description: 'Notifying customers about their orders',
  color: 'blue',
  icon: 'mail'
});

try {
  await sendEmails();

  script.step({
    title: 'Emails Sent',
    description: 'All customers have been notified',
    color: 'green',
    icon: 'checkCircle'
  });
} catch (err) {
  script.step({
    title: 'Email Error',
    description: 'Could not send some emails – check your settings',
    color: 'red',
    icon: 'alert'
  });
}
```

## Best practices

### Step Titles

Use descriptive, action-based titles:

| ✅ Do                    | 🚫 Avoid     |
| ----------------------- | ------------ |
| "Loading customer data" | "Step 1"     |
| "Sending invoices"      | "Processing" |
| "Updating inventory"    | "Working"    |

### When to Use Steps

Use script steps to improve clarity in:

* Long-running operations (API calls, imports, etc.)
* Multi-phase workflows (setup → validate → process → complete)
* Any place where user feedback improves trust

Avoid steps for very fast or trivial operations that don’t need explanation.

### How Many Steps?

* **3–7 steps** is ideal for most scripts
* Too few → lack of visibility
* Too many → unnecessary noise

### Step Descriptions

Explain **what’s happening**, not **how it’s implemented**:

| ✅ Good                                   | 🚫 Avoid                            |
| ---------------------------------------- | ----------------------------------- |
| "Fetching latest orders from your store" | "Calling API endpoint with headers" |

***


# Session
URL: /docs/scripts/api-reference/session

Documentation for the Session object in NocoDB Scripts

The `session` object provides information about the current user who is executing the script. It allows you to access contextual information about the user's identity and permissions.

## Overview

The `session` object is available in every NocoDB script and provides a way to:

* Access the current user's information (ID, name, email)

## Properties

| Property      | Type           | Description                                                                        |
| ------------- | -------------- | ---------------------------------------------------------------------------------- |
| `currentUser` | `Collaborator` | A Collaborator object representing the current user running the script (read-only) |

## Usage Examples

### Getting Current User Information

```javascript
// Access the current user information
const currentUser = session.currentUser;

output.markdown('# Current User Information');
output.text(`ID: ${currentUser.id}`);
output.text(`Name: ${currentUser.name || 'No name set'}`);
output.text(`Email: ${currentUser.email}`);
```

## Related Resources

* [Base](/docs/scripts/api-reference/base)
* [Cursor](/docs/scripts/api-reference/cursor)
* [Table](/docs/scripts/api-reference/table)
* [Input](/docs/scripts/api-reference/input)


# Table
URL: /docs/scripts/api-reference/table

Documentation for the Table object in NocoDB Scripts

The `Table` object represents a table in your NocoDB base and provides methods to access, query, and modify records within that table.

## Overview

Table objects are typically accessed through the `base` object and provide the primary way to:

* Query records using various filters and conditions
* Create, update, and delete records
* Access and modify table fields and views
* Perform bulk operations on table data

## Properties

| Property      | Type             | Description                                                        |
| ------------- | ---------------- | ------------------------------------------------------------------ |
| `id`          | `string`         | The unique identifier of the table                                 |
| `name`        | `string`         | The name of the table                                              |
| `description` | `string \| null` | The description of the table (if any)                              |
| `fields`      | `Field[]`        | Array of user-defined fields in the table (excludes system fields) |
| `views`       | `View[]`         | Array of all views defined for the table                           |
| `base`        | `Base`           | Reference to the parent base that this table belongs to            |

## Methods

### getField

Retrieves a field from the table by its ID or name. This method searches both user-defined fields and system fields.

**Parameters:**

* `idOrName` (`string`): The ID or name of the field to retrieve

**Returns:**

* `Field` object if a match is found
* `null` if no field matches the provided input

**Note:** While the `fields` property only includes user-defined fields, `getField()` can access both user fields and system fields (like Created Time, Last Modified Time, etc.)

**Example:**

```javascript
// Get a field by name
const titleField = projectsTable.getField('Title');

// Get a field by ID
const statusField = projectsTable.getField('c12345');

// Check if a field exists
if (titleField) {
  output.text(`Field "${titleField.name}" found with type: ${titleField.type}`);
} else {
  output.text('Field not found.');
}
```

### getView

Retrieves a view from the table by its ID or name.

**Parameters:**

* `idOrName` (`string`): The ID or name of the view to retrieve

**Returns:**

* `View` object if a match is found
* `null` if no view matches the provided input

**Example:**

```javascript
// Get a view by name
const activeProjectsView = projectsTable.getView('Active Projects');

// Get a view by ID
const completedTasksView = projectsTable.getView('viw12345');

// Check if a view exists
if (activeProjectsView) {
  output.text(`View "${activeProjectsView.name}" found with type: ${activeProjectsView.type}`);
} else {
  output.text('View not found.');
}
```

### selectRecordsAsync

Queries records from the table with optional filtering and sorting.

**Parameters:**

* `options` (optional): Object with the following properties:
  * `fields` (`Array<Field | string>`): Specific fields to include in the result. If not specified, all fields are included.
  * `sorts` (`Array<{field: Field | string, direction: 'asc' | 'desc'}>`): Sorting options
  * `recordIds` (`Array<string>`): Specific record IDs to retrieve
  * `pageSize` (`number`): Maximum number of records to return per page (default: 50)
  * `page` (`number`): Page number for pagination (default: 1)
  * `where` (`string`): Where filter condition.

**Returns:** `Promise<RecordQueryResult>` - A promise that resolves to a RecordQueryResult object with pagination support

**Example:**

```javascript
// Query records with options
const queryResult = await tasksTable.selectRecordsAsync({
  fields: ['Task Name', 'Status', 'Due Date'],
  sorts: [
    {field: 'Due Date', direction: 'asc'},
    {field: 'Status', direction: 'desc'}
  ],
  pageSize: 100
});

output.text(`Retrieved ${queryResult.records.length} records.`);

// Process the records
for (const record of queryResult.records) {
  const taskName = record.getCellValue('Task Name');
  const status = record.getCellValue('Status');
  output.text(`- ${taskName}: ${status}`);
}

// Check if there are more records
if (queryResult.hasMoreRecords) {
  // Load the next page of records
  const nextPage = await queryResult.loadMoreRecords();
  output.text(`Loaded ${nextPage.records.length} more records.`);
}
```

### selectRecordAsync

Retrieves a single record from the table by its ID.

**Parameters:**

* `recordId` (`string`): The ID of the record to retrieve
* `options` (optional): Object with the following properties:
  * `fields` (`Array<Field | string>`): Specific fields to include in the result

**Returns:** `Promise<Record | null>` - A promise that resolves to the Record object if a match is found

**Example:**

```javascript
// Get a specific record by ID
const recordId = '123';
const record = await contactsTable.selectRecordAsync(recordId, {
  fields: ['Name', 'Email', 'Phone']
});

if (record) {
  output.text(`Contact: ${record.getCellValue('Name')}`);
  output.text(`Email: ${record.getCellValue('Email')}`);
  output.text(`Phone: ${record.getCellValue('Phone')}`);
} else {
  output.text(`Record with ID ${recordId} not found.`);
}
```

### createRecordAsync

Creates a new record in the table with the specified field values.

**Parameters:**

* `data` (`Object`): Object mapping field names or IDs to their values.

**Returns:** `Promise<string>` - A promise that resolves to the ID of the created record

**Example:**

```javascript
// Create a new record
const newRecordId = await contactsTable.createRecordAsync({
  'Name': 'John Doe',
  'Email': 'john.doe@example.com',
  'Phone': '(555) 123-4567',
  'Status': 'Active'
});

output.text(`New record created with ID: ${newRecordId}`);

// Create a record with field IDs
const newRecordId2 = await contactsTable.createRecordAsync({
  'c123456': 'Jane Smith',  // Name field
  'c456789': 'jane@example.com'  // Email field
});
```

### createRecordsAsync

Creates multiple records in the table.

**Parameters:**

* `data` (`Array<Object>`): Array of objects mapping field names or IDs to their values.

**Returns:** `Promise<Array<string>>` - A promise that resolves to an array of IDs of the created records

**Example:**

```javascript
// Create multiple records at once
const newRecordIds = await contactsTable.createRecordsAsync([
  { fields: {
    'Name': 'John Doe',
    'Email': 'john.doe@example.com',
    'Status': 'Active'
  }},
  { fields: {
    'Name': 'Jane Smith',
    'Email': 'jane.smith@example.com',
    'Status': 'Pending'
  }},
  { fields: {
    'Name': 'Bob Johnson',
    'Email': 'bob.johnson@example.com',
    'Status': 'Active'
  }}
]);

output.text(`Created ${newRecordIds.length} new records.`);
```

### updateRecordAsync

Updates a record with the specified field values.

**Parameters:**

* `recordId` (`string | NocoDBRecord`): The ID of the record to update or a NocoDBRecord object
* `data` (`Object`): Object mapping field names or IDs to their new values.

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

**Example:**

```javascript
// Update a record by ID
await contactsTable.updateRecordAsync('123', {
  'Status': 'Inactive',
  'Last Contact Date': new Date().toISOString()
});

// Update a record using a Record object
const record = await contactsTable.selectRecordAsync('123');
if (record) {
  await contactsTable.updateRecordAsync(record, {
    'Notes': 'Customer requested follow-up next quarter.'
  });
  output.text('Record updated successfully.');
}
```

### updateRecordsAsync

Updates multiple records with the specified field values.

**Parameters:**

* `records` (`Array<{id: string | NocoDBRecord, fields: Object}>`): Array of objects with record IDs (or NocoDBRecord objects) and field values to update.

**Returns:** `Promise<void>` - A promise that resolves when all updates are complete

**Example:**

```javascript
// Update multiple records at once
await contactsTable.updateRecordsAsync([
  {
    id: '123',
    fields: {
      'Status': 'Active',
      'Last Contact Date': new Date().toISOString()
    }
  },
  {
    id: 'rec67890',
    fields: {
      'Status': 'Inactive',
      'Notes': 'Customer no longer interested.'
    }
  }
]);

output.text('Records updated successfully.');
```

### deleteRecordAsync

Deletes a record from the table.

**Parameters:**

* `recordIdOrRecord` (`string | NocoDBRecord`): The ID of the record to delete or a NocoDBRecord object

**Returns:** `Promise<boolean>` - A promise that resolves to `true` when the deletion is complete

**Example:**

```javascript
// Delete a record by ID
await tasksTable.deleteRecordAsync('123');
output.text('Record deleted successfully.');

// Delete a record using a Record object
const record = await tasksTable.selectRecordAsync('678');
if (record) {
  await tasksTable.deleteRecordAsync(record);
  output.text(`Record "${record.name}" deleted successfully.`);
}
```

### deleteRecordsAsync

Deletes multiple records from the table.

**Parameters:**

* `recordIds` (`Array<string>`): Array of record IDs to delete

**Returns:** `Promise<boolean>` - A promise that resolves to `true` when all deletions are complete

**Example:**

```javascript
// Delete multiple records by ID
await tasksTable.deleteRecordsAsync(['123', '678', '246']);
output.text('Records deleted successfully.');

// Delete records using a query result
const completedTasks = await tasksTable.selectRecordsAsync({
  fields: ['Status'],
  where: '(Status, eq, Completed)',
});

const recordsToDelete = completedTasks.records.map(record => record.id);

if (recordsToDelete.length > 0) {
  await tasksTable.deleteRecordsAsync(recordsToDelete);
  output.text(`Deleted ${recordsToDelete.length} completed tasks.`);
}
```

### createFieldAsync

Creates a new field in the table with the specified configuration.

**Parameters:**

* `field` (`Object`): Field configuration object with:
  * `name` (`string`): Name for the new field
  * `type` (`UITypes`): Type of field to create
  * `description` (`string`, optional): Description for the field
  * `options` (`Object`, optional): Type-specific options for the field

**Returns:** `Promise<Field>` - A promise that resolves to the created Field object

**Example:**

```javascript
// Create a new field
const ratingField = await projectsTable.createFieldAsync({
  name: 'Priority',
  type: UITypes.Rating,
  description: 'Project priority from 1-5',
  options: {
    icon: 'star',
    max_value: 5,
    color: '#FFCC00'
  }
});

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

// Create a select field
const statusField = await tasksTable.createFieldAsync({
  name: 'Status',
  type: UITypes.SingleSelect,
  options: {
    choices: [
      { title: 'Not Started', color: '#808080' },
      { title: 'In Progress', color: '#3366FF' },
      { title: 'Review', color: '#FF9900' },
      { title: 'Completed', color: '#33CC33' }
    ]
  }
});
```

## Examples

### Querying and Filtering Records

```javascript
// Get the "Tasks" table
const tasksTable = base.getTable('Tasks');

// Get all tasks
const allTasks = await tasksTable.selectRecordsAsync();
output.text(`Total tasks: ${allTasks.records.length}`);

// Use a view to get filtered records
const inProgressView = tasksTable.getView('In Progress Tasks');
if (inProgressView) {
  const inProgressTasks = await inProgressView.selectRecordsAsync();
  output.text(`In-progress tasks: ${inProgressTasks.records.length}`);
}

// Get specific fields and sort by due date
const upcomingTasks = await tasksTable.selectRecordsAsync({
  fields: ['Task Name', 'Due Date', 'Status', 'Assigned To'],
  sorts: [
    { field: 'Due Date', direction: 'asc' }
  ],
  pageSize: 10
});

// Display the upcoming tasks
output.markdown('# Upcoming Tasks');
for (const task of upcomingTasks.records) {
  const name = task.getCellValue('Task Name');
  const dueDate = task.getCellValue('Due Date');
  const status = task.getCellValue('Status');
  const assignee = task.getCellValue('Assigned To');
  
  const assigneeName = assignee ? assignee.name : 'Unassigned';
  
  output.text(`- ${name} (${status}) due on ${dueDate} - Assigned to: ${assigneeName}`);
}
```

### Creating and Updating Records

```javascript
// Get the "Projects" table
const projectsTable = base.getTable('Projects');

// Create a new project
const newProjectId = await projectsTable.createRecordAsync({
  'Project Name': 'Website Redesign',
  'Start Date': new Date().toISOString(),
  'Status': 'Planning',
  'Budget': 15000,
  'Description': 'Complete overhaul of company website.'
});

output.text(`Created new project with ID: ${newProjectId}`);

// Retrieve the created project
const newProject = await projectsTable.selectRecordAsync(newProjectId);
if (newProject) {
  output.text(`New project: ${newProject.getCellValue('Project Name')}`);
  
  // Update the project after creation
  await projectsTable.updateRecordAsync(newProjectId, {
    'Project Lead': session.currentUser.id,
    'Team Size': 5
  });
  
  output.text('Project updated with lead and team size.');
}

// Create multiple tasks for the project
const tasksTable = base.getTable('Tasks');
const tasks = [
  { fields: {
    'Task Name': 'Requirements Gathering',
    'Project': newProjectId,
    'Status': 'Not Started',
    'Due Date': new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
  }},
  { fields: {
    'Task Name': 'Wireframes',
    'Project': newProjectId,
    'Status': 'Not Started',
    'Due Date': new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toISOString()
  }},
  { fields: {
    'Task Name': 'Design Mockups',
    'Project': newProjectId,
    'Status': 'Not Started',
    'Due Date': new Date(Date.now() + 21 * 24 * 60 * 60 * 1000).toISOString()
  }}
];

const taskIds = await tasksTable.createRecordsAsync(tasks);
output.text(`Created ${taskIds.length} tasks for the project.`);
```

### Bulk Processing with Pagination

```javascript
// Get the "Contacts" table
const contactsTable = base.getTable('Contacts');

// Function to process all records with pagination
async function processAllRecords() {
  let queryResult = await contactsTable.selectRecordsAsync({
    fields: ['Name', 'Email', 'Last Contact Date'],
    pageSize: 100 // Process in batches of 100
  });
  
  let processedCount = 0;
  let updatedCount = 0;

  while (queryResult.hasMoreRecords) {
    await queryResult.loadMoreRecords();
  }
  
  // Process first batch
  let recordsToUpdate = [];
  for (const record of queryResult.records) {
    processedCount++;
    
    const lastContactDate = record.getCellValue('Last Contact Date');
    // If no contact in the last 90 days, mark for update
    if (!lastContactDate || new Date(lastContactDate) < new Date(Date.now() - 90 * 24 * 60 * 60 * 1000)) {
      recordsToUpdate.push({
        id: record.id,
        fields: {
          'Status': 'Needs Follow-up',
          'Notes': 'No contact in the last 90 days.'
        }
      });
    }
  }
  
  // Update any remaining records
  if (recordsToUpdate.length > 0) {
    await contactsTable.updateRecordsAsync(recordsToUpdate);
    updatedCount += recordsToUpdate.length;
  }
  
  output.text(`Processing complete! Processed ${processedCount} total records, updated ${updatedCount}.`);
}

// Run the process
await processAllRecords();
```

## Best Practices

1. **Batch operations** - When creating or updating many records, use the bulk methods (`createRecordsAsync`, `updateRecordsAsync`) instead of individual calls for better performance.

2. **Paginate large queries** - When working with large tables, use pagination via the `pageSize` option and `loadMoreRecords()` method to avoid memory issues.

3. **Error handling** - Always wrap async operations in try/catch blocks to handle errors gracefully.

4. **Optimize field selection** - Only request the fields you need by using the `fields` option in queries to improve performance.

## Related Resources

* [Base](/docs/scripts/api-reference/base)
* [Record](/docs/scripts/api-reference/record)
* [Field](/docs/scripts/api-reference/field)
* [View](/docs/scripts/api-reference/view)


# View
URL: /docs/scripts/api-reference/view

Documentation for the View object in NocoDB Scripts

The `View` object represents a specific view of a table in your NocoDB base. Views provide filtered, sorted, and customized perspectives of your table data.

## Overview

Views in NocoDB allow you to:

* Apply filters to show only specific records from a table
* Define custom sorting for records
* Show or hide specific fields

In NocoDB Scripts, View objects provide a convenient way to work with these filtered subsets of data without having to manually implement filtering logic in your script.

## Properties

| Property      | Type             | Description                                                              |
| ------------- | ---------------- | ------------------------------------------------------------------------ |
| `id`          | `string`         | The unique identifier of the view                                        |
| `name`        | `string`         | The name of the view                                                     |
| `description` | `string \| null` | The description of the view (if any)                                     |
| `type`        | `string`         | The type of view (e.g., 'grid', 'form', 'gallery', 'kanban', 'calendar') |
| `table`       | `Table`          | Reference to the parent table that this view belongs to                  |

## Methods

### selectRecordsAsync

Queries records from the view with optional parameters for field selection, sorting, and pagination.

**Parameters:**

* `options` (optional): Object with the following properties:
  * `fields` (`Array<Field | string>`): Specific fields to include in the result. If not specified, all fields are included.
  * `sorts` (`Array<{field: Field | string, direction: 'asc' | 'desc'}>`): Sorting options
  * `recordIds` (`Array<string>`): Specific record IDs to retrieve
  * `pageSize` (`number`): Maximum number of records to return per page (default: 50)
  * `page` (`number`): Page number for pagination (default: 1)
  * `where` (`string`): Where filter condition which adds to existing view filters

**Returns:** `Promise<RecordQueryResult>` - A promise that resolves to a RecordQueryResult object with pagination support

**Example:**

```javascript
// Get the Projects table and Active Projects view
const projectsTable = base.getTable('Projects');
const activeProjectsView = projectsTable.getView('Active Projects');

// Query records from the view
const queryResult = await activeProjectsView.selectRecordsAsync({
  fields: ['Project Name', 'Status', 'Deadline', 'Assigned To'],
  sorts: [
    { field: 'Deadline', direction: 'asc' }
  ],
  pageSize: 50
});

while(queryResult.hasMoreRecords) {
  await queryResult.loadMoreRecords()
}

output.text(`Found ${queryResult.records.length} active projects.`);

// Process the records
for (const record of queryResult.records) {
  const projectName = record.getCellValue('Project Name');
  const deadline = record.getCellValue('Deadline');
  const assignedTo = record.getCellValue('Assigned To');
  
  const assigneeName = assignedTo ? assignedTo.name : 'Unassigned';
  
  output.text(`- ${projectName} due on ${deadline} - Assigned to: ${assigneeName}`);
}
```

### selectRecordAsync

Retrieves a single record from the view by its ID, applying the view's filters and permissions.

**Parameters:**

* `recordId` (`string`): The ID of the record to retrieve
* `options` (optional): Object with the following properties:
  * `fields` (`Array<Field | string>`): Specific fields to include in the result. Primary key and primary value fields are automatically included.

**Returns:** `Promise<NocoDBRecord | null>` - A promise that resolves to the NocoDBRecord object or null if not found, filtered out by the view, or if an AxiosError occurs

**Example:**

```javascript
// Get a specific record through a view
const tasksTable = base.getTable('Tasks');
const myTasksView = tasksTable.getView('My Tasks');

const recordId = '123';
const task = await myTasksView.selectRecordAsync(recordId, {
  fields: ['Task Name', 'Status', 'Due Date', 'Notes']
});

if (task) {
  output.text(`Task: ${task.getCellValue('Task Name')}`);
  output.text(`Status: ${task.getCellValue('Status')}`);
  output.text(`Due Date: ${task.getCellValue('Due Date')}`);
  output.text(`Notes: ${task.getCellValue('Notes')}`);
} else {
  output.text(`Record with ID ${recordId} not found in this view.`);
  // Note: The record might exist in the table but be filtered out by the view
}
```

## Using Views for Filtering

One of the primary benefits of views is using them for filtering data instead of implementing complex filtering logic in your scripts.

```javascript
// Example: Processing overdue tasks
const tasksTable = base.getTable('Tasks');
const overdueTasksView = tasksTable.getView('Overdue Tasks');

// This view already has filters for tasks where Due Date < Today and Status != Completed
const overdueTasks = await overdueTasksView.selectRecordsAsync({
  fields: ['Task Name', 'Due Date', 'Assigned To', 'Status']
});

while(overdueTasks.hasMoreRecords) {
  await overdueTasks.loadMoreRecords()
}

// Create a notification summary
output.markdown('# Overdue Tasks Summary');
output.text(`There are ${overdueTasks.records.length} overdue tasks.`);

// Group tasks by assignee
const tasksByAssignee = {} as Record<string, {
  name: string,
  tasks: Array<{name: string, dueDate: string}>
}>;
for (const task of overdueTasks.records) {
  const assignee = task.getCellValue('Assigned To');
  const assigneeId = assignee ? assignee.id : 'unassigned';
  const assigneeName = assignee ? assignee.name : 'Unassigned';
  
  if (!tasksByAssignee[assigneeId]) {
    tasksByAssignee[assigneeId] = {
      name: assigneeName,
      tasks: []
    };
  }
  
  tasksByAssignee[assigneeId].tasks.push({
    name: task.getCellValue('Task Name'),
    dueDate: task.getCellValue('Due Date')
  });
}

// Output summary by assignee
for (const [assigneeId, assigneeData] of Object.entries(tasksByAssignee)) {
  output.markdown(`## ${assigneeData.name}`);
  for (const task of assigneeData.tasks) {
    const daysOverdue = Math.floor((new Date() - new Date(task.dueDate)) / (1000 * 60 * 60 * 24));
    output.text(`- ${task.name} (${daysOverdue} days overdue)`);
  }
}
```

## Creating Interactive Reports Using Views

Views can be used to create interactive reports based on different data segments.

```javascript
// Let the user choose a view from the Sales table
const salesTable = base.getTable('Sales');
const viewOptions = salesTable.views.map(view => view.name);

const selectedViewName = await input.selectAsync(
  'Select a sales report view to analyze:',
  viewOptions
);

const selectedView = salesTable.getView(selectedViewName);
const sales = await selectedView.selectRecordsAsync({
  fields: ['Date', 'Amount', 'Product', 'Sales Rep', 'Region']
});

while(sales.hasMoreRecords) {
  await sales.loadMoreRecords()
}

// Calculate summary statistics
let totalSales = 0;
const salesByRep = {};
const salesByProduct = {};
const salesByRegion = {};

for (const record of sales.records) {
  const amount = record.getCellValue('Amount') || 0;
  const rep = record.getCellValue('Sales Rep');
  const product = record.getCellValue('Product');
  const region = record.getCellValue('Region');
  
  totalSales += amount;
  
  // Sales by rep
  if (rep) {
    const repName = rep.name;
    if (!salesByRep[repName]) {
      salesByRep[repName] = 0;
    }
    salesByRep[repName] += amount;
  }
  
  // Sales by product
  if (product) {
    if (!salesByProduct[product]) {
      salesByProduct[product] = 0;
    }
    salesByProduct[product] += amount;
  }
  
  // Sales by region
  if (region) {
    if (!salesByRegion[region]) {
      salesByRegion[region] = 0;
    }
    salesByRegion[region] += amount;
  }
}

// Output the report
output.markdown(`# Sales Report: ${selectedViewName}`);
output.text(`Total Sales: $${totalSales.toFixed(2)}`);
output.text(`Number of Transactions: ${sales.records.length}`);
output.text(`Average Transaction: $${(totalSales / sales.records.length).toFixed(2)}`);

// Display sales by rep
output.markdown('## Sales by Representative');
const salesByRepData = Object.entries(salesByRep)
  .map(([rep, amount]) => ({ Rep: rep, Amount: amount }))
  .sort((a, b) => b.Amount - a.Amount);
output.table(salesByRepData);

// Display sales by product
output.markdown('## Sales by Product');
const salesByProductData = Object.entries(salesByProduct)
  .map(([product, amount]) => ({ Product: product, Amount: amount }))
  .sort((a, b) => b.Amount - a.Amount);
output.table(salesByProductData);

// Display sales by region
output.markdown('## Sales by Region');
const salesByRegionData = Object.entries(salesByRegion)
  .map(([region, amount]) => ({ Region: region, Amount: amount }))
  .sort((a, b) => b.Amount - a.Amount);
output.table(salesByRegionData);
```

## Best Practices

1. **Use views for filtering** - Take advantage of views to apply complex filters rather than implementing filtering logic in your script.

2. **Remember views are read-only** - View objects provide query capabilities but any record creation or updates happen at the table level.

3. **Combine with Table operations** - Use views for reading/filtering and table methods for writing data.

4. **Await async operations** - Always use `await` when calling async methods to ensure proper execution flow.

## Related Resources

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


# API Reference Manual Examples
URL: /docs/scripts/examples/api-ref-manual-examples

Browse categorized examples from the NocoDB API reference documentation to quickly access common scripting tasks and operations.

The following examples are discussed in API reference documentation and are indexed here for quick access.

### 🗃️ Base Operations

* [Getting All Tables](/docs/scripts/api-reference/base#getting-all-tables)
* [Checking for a Specific Table](/docs/scripts/api-reference/base#checking-for-a-specific-table)
* [Working with Collaborators](/docs/scripts/api-reference/base#working-with-collaborators)

## 📌 Cursor

* [Checking the Context](/docs/scripts/api-reference/cursor#checking-the-context)
* [Bulk Update Script](/docs/scripts/api-reference/cursor#bulk-update-script)

## 📄 Table & Records

### ➕ Creating & Updating Records

* [Creating and Updating Records](/docs/scripts/api-reference/table#creating-and-updating-records)

### 🔍 Querying & Filtering

* [Querying and Filtering Records](/docs/scripts/api-reference/table#querying-and-filtering-records)

### 📦 Bulk Processing

* [Bulk Processing with Pagination](/docs/scripts/api-reference/table#bulk-processing-with-pagination)

## 👁️ Views

* [Using Views for Filtering](/docs/scripts/api-reference/view#using-views-for-filtering)
* [Creating Interactive Reports Using Views](/docs/scripts/api-reference/view#creating-interactive-reports-using-views)

## 🏷️ Fields

* [Getting a Field from a Table](/docs/scripts/api-reference/field#getting-a-field-from-a-table)
* [Creating a New Field](/docs/scripts/api-reference/field#creating-a-new-field)
* [Updating Field Options](/docs/scripts/api-reference/field#updating-field-options)
* [Working with Select Field Choices](/docs/scripts/api-reference/field#working-with-select-field-choices)

## 📊 Record Query Results

* [Paginated Processing](/docs/scripts/api-reference/record-query-result#paginated-processing)
* [Finding Records in the Result](/docs/scripts/api-reference/record-query-result#finding-records-in-the-result)
* [Grouping Records](/docs/scripts/api-reference/record-query-result#grouping-records)

## 📌 Record Operations

* [Reading Record Data](/docs/scripts/api-reference/record#reading-record-data)
* [Comparing Records](/docs/scripts/api-reference/record#comparing-records)
* [Working with Linked Records](/docs/scripts/api-reference/record#working-with-linked-records)
* [Using Record Values in Calculations](/docs/scripts/api-reference/record#using-record-values-in-calculations)
* [Complex Record Processing](/docs/scripts/api-reference/record#complex-record-processing)

## 👤 Session

* [Getting Current User Information](/docs/scripts/api-reference/session#getting-current-user-information)

## 👥 Collaborator

* [Finding a Specific Collaborator](/docs/scripts/api-reference/collaborator#finding-a-specific-collaborator)
* [Checking if Current User Matches a Specific Collaborator](/docs/scripts/api-reference/collaborator#checking-if-current-user-matches-a-specific-collaborator)

## ✏️ Input

* [Form-Based Data Entry](/docs/scripts/api-reference/input#form-based-data-entry)
* [File Upload and Processing](/docs/scripts/api-reference/input#file-upload-and-processing)
* [Interactive Record Selection and Update](/docs/scripts/api-reference/input#interactive-record-selection-and-update)

## 📤 Output

* [Creating a Structured Report](/docs/scripts/api-reference/output#creating-a-structured-report)

## 🌐 Fetch & External APIs

### 🔄 Fetching & Sending Data

* [Fetching Data from a Public API](/docs/scripts/api-reference/fetch#fetching-data-from-a-public-api)
* [Sending Data to a Webhook](/docs/scripts/api-reference/fetch#sending-data-to-a-webhook)
* [Integrating with Google Sheets API](/docs/scripts/api-reference/fetch#integrating-with-google-sheets-api)

### 🧾 Data Formats

* [JSON Data](/docs/scripts/api-reference/fetch#json-data)
* [Form Data](/docs/scripts/api-reference/fetch#form-data)


# Convert Attachments to URLs
URL: /docs/scripts/examples/convert-attachments-to-urls

Convert attachment fields into comma-separated URL lists for integration with external services

### Overview

This script processes attachment fields in your table and converts them into comma-separated URL strings. This is particularly useful when you need to send attachment URLs to third-party integration services that expect URL strings rather than attachment objects.

```javascript
/**
 * Convert attachments to URLs
 *
 * Outputs comma-separated URLs for all attachments and writes them to another field for each record.
 * Can be used for sending URLs to third-party integration services.
 */

// Script configuration - allows users to select table, view, and fields
const config = input.config({
  title: '📎 Convert attachments to URLs',
  description: 'Output comma-separated URLs for all attachments and write to another field for each record. Can be used for sending URLs to third-party integration services.',
  items: [
    input.config.table('selectedTable', {
      label: 'Table',
      description: 'Select a table with records that have attachments you want URLs for',
    }),
    input.config.field('selectedField', {
      label: 'Attachment field from the selected table',
      parentTable: 'selectedTable',
      description: 'Select the attachment field from the table above you want URLs for'
    }),
    input.config.view('selectedView', {
      label: 'View from the selected table',
      parentTable: 'selectedTable',
    }),
    input.config.field('fieldToEdit', {
      label: 'Field to output the attachment URLs to',
      parentTable: 'selectedTable',
      description: 'A long text field is recommended. A comma-separated list of URLs will be generated here'
    })
  ]
});

// Assign selections to variables for the script
const selectedTable = config.selectedTable;
const selectedField = config.selectedField;
const selectedView = config.selectedView;
const fieldToEdit = config.fieldToEdit;

/**
 * Main function to convert attachments to URLs
 */
async function convertAttachmentsToUrls() {
  // Verify the selected field is an attachment field
  if (selectedField.type !== UITypes.Attachment) {
    output.text(`"${selectedField.name}" is not an attachment field. Run the script again with an attachment field.`, 'error');
    return;
  }

  // Load records from the selected view
  const query = await selectedView.selectRecordsAsync({
    fields: [selectedField]
  });

  // Get all records
  const records = query.records;

  // Array for records with attachments and their URLs
  const recordsToUpdate = [];

  // Process each record
  for (let i = 0; i < records.length; i++) {
    const record = records[i];
    const attachments = record.getCellValue(selectedField);

    // Only process records with attachments
    if (attachments && attachments.length > 0) {
      // Extract URLs from attachments
      const attachmentUrls = attachments.map(attachment => attachment.url);
      const urlString = attachmentUrls.join(', ');

      // Add to update array
      recordsToUpdate.push({
        id: record.id,
        fields: {
          [fieldToEdit.name]: urlString
        }
      });
    }
  }

  // Update records in batches of 50
  while (recordsToUpdate.length > 0) {
    const batch = recordsToUpdate.slice(0, 50);
    await selectedTable.updateRecordsAsync(batch);
    recordsToUpdate.splice(0, 50);

    // Show progress
    output.text(`Updated ${Math.min(50, batch.length)} records...`);
  }
}

// Run the script
await convertAttachmentsToUrls();

// Output message to indicate when the script is done
output.text('Records have been updated with attachment URLs', 'success');
```

### How it Works

1. **Select Source Field**: Choose an attachment field containing the files you want to convert
2. **Choose Target Field**: Select a text field where the comma-separated URLs will be written
3. **Process Records**: The script processes each record, extracting URLs from attachments
4. **Output Format**: URLs are joined with commas: `url1,url2,url3`

### Requirements

* An **Attachment field** with uploaded files
* A **Text field** to store the comma-separated URL output

### Example

**Before:**

* Attachment Field: `[file1.pdf, image2.jpg, document3.docx]`
* URL Field: `(empty)`

**After:**

* Attachment Field: `[file1.pdf, image2.jpg, document3.docx]` *(unchanged)*
* URL Field: `https://example.com/file1.pdf,https://example.com/image2.jpg,https://example.com/document3.docx`


# Find and Replace
URL: /docs/scripts/examples/find-and-replace

Search and replace text patterns across records in any text-based field with preview and confirmation

This script provides a powerful find and replace functionality for text fields in your table. It allows you to search for specific text patterns and replace them with new values across multiple records, with the ability to preview matches before making changes.

```javascript
const config = input.config({
  title: 'Find and replace',
  description: `This script will find and replace all text matches for a text-based field you pick.
    You will be able to see all matches before replacing them.`,
  items: [input.config.table('table', { label: 'Table' }), input.config.field('field', { parentTable: 'table', label: 'Field' })],
})

const { table, field } = config
output.text(`Finding and replacing in the ${field.name} field of ${table.name}.`)

const findText = await input.textAsync('Enter text to find:')
const replaceText = await input.textAsync('Enter to replace matches with:')

// Load all of the records in the table
let result = await table.selectRecordsAsync()

// Fetch all records using a while loop
while (result.hasMoreRecords) {
  await result.loadMoreRecords()
}

// Find every record we need to update
const replacements = []
for (const record of result.records) {
  const originalValue = record.getCellValue(field)

  // Skip non-string records
  if (typeof originalValue !== 'string') {
    continue
  }

  // Skip records which don't have the value set, so the value is null
  if (!originalValue) {
    continue
  }

  const newValue = originalValue.replace(findText, replaceText)

  if (originalValue !== newValue) {
    replacements.push({
      record,
      before: originalValue,
      after: newValue,
    })
  }
}
if (!replacements.length) {
  output.text('No replacements found')
} else {
  output.markdown('## Replacements')
  output.table(replacements)

  const shouldReplace = await input.buttonsAsync('Are you sure you want to save these changes?', [
    { label: 'Save', variant: 'danger' },
    { label: 'Cancel' },
  ])

  if (shouldReplace === 'Save') {
    // Update the records
    let updates = replacements.map((replacement) => ({
      id: replacement.record.id,
      fields: {
        [field.id]: replacement.after,
      },
    }))

    // Only up to 10 updates are allowed at one time, so do it in batches
    while (updates.length > 0) {
      await table.updateRecordsAsync(updates.slice(0, 10))
      updates = updates.slice(10)
    }
  }
}
```

### Use Cases

* **Data Cleanup**: Fix typos, standardize formatting, or correct inconsistent data
* **URL Updates**: Update domain names or path structures across multiple records
* **Content Migration**: Replace old terminology with new branding or naming conventions
* **Bulk Corrections**: Fix systematic errors across large datasets

### How it Works

1. **Select Field**: Choose any text-based field (Single Line Text, Long Text, Email, URL, etc.)
2. **Enter Search Pattern**: Specify the text you want to find
3. **Enter Replacement**: Define what the found text should be replaced with
4. **Preview Matches**: Review all matches before applying changes
5. **Confirm Changes**: Apply replacements to all matching records

### Requirements

* A **text-based field** containing the data you want to modify
* **Find pattern**: The text string you want to search for
* **Replace pattern**: The text string you want to use as replacement

### Supported Field Types

* Single Line Text
* Long Text
* Email
* URL
* Phone Number
* Any other text-based field

### Example

**Scenario**: Update company domain across all email addresses

**Before:**

```
john@oldcompany.com
jane@oldcompany.com
admin@oldcompany.com
```

**Find**: `oldcompany.com`
**Replace**: `newcompany.com`

**After:**

```
john@newcompany.com
jane@newcompany.com
admin@newcompany.com
```

### Features

* **Safe Preview**: See all matches before making any changes
* **Exact Matching**: Finds only the exact text pattern specified
* **Batch Processing**: Updates all matching records in one operation
* **Case Sensitive**: Matches respect letter casing
* **Non-Destructive**: Only replaces the specified pattern, leaving other text unchanged

### Best Practices

* Always use the preview feature to verify matches before applying changes
* Test with a small dataset first when working with large tables
* Consider case sensitivity when defining your search pattern
* Make sure your replacement text won't create unintended formatting issues


# Import CSV Data
URL: /docs/scripts/examples/import-csv

This script allows users to import data from a CSV file into a selected table in NocoDB, with options for handling duplicates and mapping CSV columns to table fields.

```javascript
// Example of using file upload to import data
async function importCSVData(): Promise<void> {
  try {
    // Step 1: Select destination table
    const table: Table = await input.tableAsync('Select a table to import data into:');

    // Step 2: Upload CSV file
    const result: any = await input.fileAsync('Upload CSV file:', {
      allowedFileTypes: ['.csv'],
      hasHeaderRow: true,
      useRawValues: false
    });

    if (!result || !result.parsedContents) {
      output.text('No file uploaded or file could not be parsed.');
      return;
    }

    const csvData: Record<string, any>[] = result.parsedContents;

    if (csvData.length === 0) {
      output.text('CSV file is empty.');
      return;
    }

    // Step 3: Show file preview
    output.markdown('### CSV Import Preview');
    output.text(`File contains ${csvData.length} rows and ${Object.keys(csvData[0] || {}).length} columns.`);

    if (csvData.length > 0) {
      output.text('Sample data (first 3 rows):');
      output.table(csvData.slice(0, 3));
    }

    // Step 4: Configure duplicate handling
    const duplicateHandling: 'skip' | 'update' | 'allow' | 'cancel' = await input.selectAsync(
      'How should duplicate records be handled?',
      [
        { label: 'Skip duplicates', value: 'skip' },
        { label: 'Update existing records', value: 'update' },
        { label: 'Allow duplicates', value: 'allow' },
        { label: '-- Cancel Import --', value: 'cancel' }
      ]
    );

    if (duplicateHandling === 'cancel') {
      output.text('Import cancelled by user.');
      return;
    }

    // Step 5: Select unique field if handling duplicates
    let uniqueField: Field | undefined;
    let uniqueColumnName: string | null = null;

    if (duplicateHandling !== 'allow') {
      // Create field options with cancel option
      const fieldOptions = [
        { label: '-- Cancel Import --', value: 'cancel' },
        ...table.fields
          .filter(field => !field.isComputed && !field.is_system_field)
          .map(field => ({
            label: `${field.name} (${field.type})`,
            value: field.name
          }))
      ];

      const selectedFieldName: string = await input.selectAsync(
        'Select a field to use for identifying duplicates:',
        fieldOptions
      );

      if (selectedFieldName === 'cancel') {
        output.text('Import cancelled by user.');
        return;
      }
      uniqueField = table.getField(selectedFieldName);

      if(uniqueField) {
      const csvColumns: string[] = Object.keys(csvData[0] || {});
      uniqueColumnName = csvColumns.find(col =>
        col.toLowerCase().trim() === uniqueField!.name.toLowerCase().trim()
      ) || null;

      if (!uniqueColumnName) {
        const availableColumns = [
          { label: '-- Cancel Import --', value: 'cancel' },
          ...csvColumns.map(col => ({ label: col, value: col }))
        ];

        uniqueColumnName = await input.selectAsync(
          `No CSV column matches "${uniqueField.name}". Select the CSV column to use:`,
          availableColumns
        );

        if (uniqueColumnName === 'cancel') {
          output.text('Import cancelled by user.');
          return;
        }
      }

      }
    }

    // Step 6: Map CSV columns to table fields
    output.markdown('### Field Mapping');
    output.text('Map each CSV column to a field in the table:');

    const csvColumns: string[] = Object.keys(csvData[0] || {});
    const fieldMap: Record<string, string> = {};

    // Get available fields (exclude computed and system fields)
    const availableFields: Field[] = table.fields.filter(field =>
      !field.isComputed &&
      !field.primary_key &&
      !field.is_system_field
    );

    for (const column of csvColumns) {
      // Find best match for auto-suggestion
      const bestMatchField: Field | undefined = availableFields.find(field =>
        field.name.toLowerCase().trim() === column.toLowerCase().trim()
      );

      const fieldOptions: Array<{ label: string; value: string }> = [
        { label: '-- Skip this column --', value: 'skip' },
        { label: '-- Cancel Import --', value: 'cancel' },
        ...availableFields.map(field => ({
          label: `${field.name} (${field.type})`,
          value: field.name
        }))
      ];

      let selectedField: string;
      if (bestMatchField) {
        // Auto-confirm perfect matches, but give option to change
        const autoConfirm: string = await input.buttonsAsync(
          `Auto-mapped: "${column}" → "${bestMatchField.name}". Accept this mapping?`,
          [
            { label: 'Accept', value: 'accept', variant: 'primary' },
            { label: 'Change Mapping', value: 'change', variant: 'secondary' },
            { label: 'Skip Column', value: 'skip', variant: 'secondary' },
            { label: 'Cancel Import', value: 'cancel', variant: 'danger' }
          ]
        );

        if (autoConfirm === 'cancel') {
          output.text('Import cancelled by user.');
          return;
        } else if (autoConfirm === 'accept') {
          selectedField = bestMatchField.name;
          output.text(`✓ Mapped: "${column}" → "${bestMatchField.name}"`);
        } else if (autoConfirm === 'skip') {
          selectedField = 'skip';
        } else {
          selectedField = await input.selectAsync(
            `Map CSV column "${column}" to:`,
            fieldOptions
          );
        }
      } else {
        selectedField = await input.selectAsync(
          `Map CSV column "${column}" to:`,
          fieldOptions
        );
      }

      if (selectedField === 'cancel') {
        output.text('Import cancelled by user.');
        return;
      } else if (selectedField && selectedField !== 'skip') {
        fieldMap[column] = selectedField;
      }
    }

    // Ensure at least one field is mapped
    if (Object.keys(fieldMap).length === 0) {
      output.text('No fields mapped. Import cancelled.');
      return;
    }

    // Step 7: Show mapping preview
    output.markdown('### Import Configuration');
    output.text('The following columns will be imported:');

    const mappingTable = Object.entries(fieldMap).map(([csvCol, fieldName]) => {
      const field = table.getField(fieldName);
      return {
        'CSV Column': csvCol,
        'Table Field': fieldName,
        'Field Type': field?.type || 'Unknown'
      };
    });

    output.table(mappingTable);

    // Step 8: Final confirmation
    const confirmation: boolean = await input.buttonsAsync(
      `Ready to import ${csvData.length} records with ${duplicateHandling} duplicate handling. Continue?`,
      [
        { label: 'Import Data', value: true, variant: 'primary' },
        { label: 'Cancel', value: false, variant: 'secondary' }
      ]
    );

    if (!confirmation) {
      output.text('Import cancelled.');
      return;
    }

    // Step 9: Begin import process
    output.markdown('### Importing Data');

    // Initialize counters
    let created: number = 0;
    let updated: number = 0;
    let skipped: number = 0;
    let failed: number = 0;
    let processed: number = 0;
    const failedRows: Array<{ Row: number | string; Error: string; 'Data Sample': string }> = [];

    const batchSize: number = 10;
    const totalBatches: number = Math.ceil(csvData.length / batchSize);

    // Process data in batches
    for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
      const startIndex: number = batchIndex * batchSize;
      const endIndex: number = Math.min(startIndex + batchSize, csvData.length);
      const batch: Record<string, any>[] = csvData.slice(startIndex, endIndex);

      // Prepare records for this batch
      const recordsToCreate: Record<string, any>[] = [];
      const recordsToUpdate: Array<{ id: string; fields: Record<string, any> }> = [];

      for (let rowIndex = 0; rowIndex < batch.length; rowIndex++) {
        const row: Record<string, any> = batch[rowIndex];
        const actualRowIndex: number = startIndex + rowIndex;

        try {
          // Transform CSV data according to field mapping and types
          const recordData: Record<string, any> = {};

          for (const [csvColumn, fieldName] of Object.entries(fieldMap)) {
            const rawValue: any = row[csvColumn];

            if (rawValue !== undefined && rawValue !== null && rawValue !== '') {
              const field: Field | undefined = table.getField(fieldName);
              if (field) {
                recordData[fieldName] = transformValue(rawValue, field);
              }
            }
          }

          // Skip empty records
          if (Object.keys(recordData).length === 0) {
            skipped++;
          } else {
            // Handle duplicates
            let shouldCreateRecord = true;

            if (duplicateHandling !== 'allow' && uniqueField && uniqueColumnName) {
              const uniqueValue: any = row[uniqueColumnName];

              if (uniqueValue !== undefined && uniqueValue !== null && uniqueValue !== '') {
                // Check for existing record using efficient server-side filtering
                const existingRecords: RecordQueryResult = await table.selectRecordsAsync({
                  fields: [uniqueField.name],
                  where: `(${uniqueField.name},eq,${uniqueValue})`,
                  pageSize: 1
                });

                if (existingRecords.records.length > 0) {
                  const existingRecord: NocoDBRecord = existingRecords.records[0];

                  if (duplicateHandling === 'update') {
                    recordsToUpdate.push({
                      id: existingRecord.id,
                      fields: recordData
                    });
                    shouldCreateRecord = false;
                  } else if (duplicateHandling === 'skip') {
                    skipped++;
                    shouldCreateRecord = false;
                  }
                }
              }
            }

            // Add to creation queue if not handled as duplicate
            if (shouldCreateRecord) {
              recordsToCreate.push({fields: recordData});
            }
          }

        } catch (error: any) {
          console.error(`Error processing row ${actualRowIndex + 1}:`, error);
          failedRows.push({
            'Row': actualRowIndex + 1,
            'Error': error.message || String(error),
            'Data Sample': JSON.stringify(row).substring(0, 100) + '...'
          });
          failed++;
        }
      }

      // Execute batch operations
      try {
        // Bulk create new records
        if (recordsToCreate.length > 0) {
          const createdIds: string[] = await table.createRecordsAsync(recordsToCreate);
          created += createdIds.length;
        }

        // Bulk update existing records
        if (recordsToUpdate.length > 0) {
          await table.updateRecordsAsync(recordsToUpdate);
          updated += recordsToUpdate.length;
        }

      } catch (batchError: any) {
        console.error(`Error in batch ${batchIndex + 1}:`, batchError);
        failed += recordsToCreate.length + recordsToUpdate.length;

        // Log batch failure
        failedRows.push({
          'Row': `Batch ${batchIndex + 1}`,
          'Error': `Batch operation failed: ${batchError.message || String(batchError)}`,
          'Data Sample': `${recordsToCreate.length} creates, ${recordsToUpdate.length} updates`
        });
      }

      processed = endIndex;
    }

    // Step 10: Show final results
    output.markdown('### Import Complete! 🎉');

    const resultsTable: Array<{ Metric: string; Count: number }> = [
      { 'Metric': 'Total Records Processed', 'Count': csvData.length },
      { 'Metric': 'Records Created', 'Count': created },
      { 'Metric': 'Records Updated', 'Count': updated },
      { 'Metric': 'Records Skipped', 'Count': skipped },
      { 'Metric': 'Failed Records', 'Count': failed }
    ];

    output.table(resultsTable);

    // Show failed records if any
    if (failedRows.length > 0) {
      output.markdown('### Failed Records');
      output.text(`${failedRows.length} records failed to import. First 10 failures:`);
      output.table(failedRows.slice(0, 10));
    }

    // Success summary
    const successRate: number = Math.round(((created + updated + skipped) / csvData.length) * 100);
    output.text(`Import completed with ${successRate}% success rate.`);

  } catch (error: any) {
    console.error('Import failed:', error);
    output.text(`Import failed: ${error.message || String(error)}`);
  }
}

/**
 * Transform CSV value to appropriate type based on field definition
 * @param {any} value - Raw CSV value
 * @param {Field} field - NocoDB field definition
 * @returns {any} Transformed value
 */
function transformValue(value: unknown, field: Field) {
  if (value === null || value === undefined || value === '') {
    return null;
  }

  const stringValue = String(value).trim();

  switch (field.type) {
    case UITypes.Number:
    case UITypes.Decimal:
    case UITypes.Currency:
    case UITypes.Percent:
    case UITypes.Rating:
      const numValue = parseFloat(stringValue.replace(/[^\d.-]/g, ''));
      return isNaN(numValue) ? null : numValue;

    case UITypes.Checkbox:
      return ['true', '1', 'yes', 'on', 'checked'].includes(stringValue.toLowerCase());

    case UITypes.Time:
      // Try to parse time format
      const timeMatch = stringValue.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
      if (timeMatch) {
        const [, hours, minutes, seconds = '00'] = timeMatch;
        return `${hours.padStart(2, '0')}:${minutes}:${seconds}`;
      }
      return stringValue;

    case UITypes.Year:
      const yearValue = parseInt(stringValue);
      return (yearValue >= 1900 && yearValue <= 2100) ? yearValue : null;

    case UITypes.Duration:
      // Try to parse duration format (h:mm:ss or seconds)
      if (stringValue.includes(':')) {
        const parts = stringValue.split(':');
        if (parts.length >= 2) {
          const hours = parseInt(parts[0]) || 0;
          const minutes = parseInt(parts[1]) || 0;
          const seconds = parseInt(parts[2]) || 0;
          return hours * 3600 + minutes * 60 + seconds; // Convert to seconds
        }
      }
      // Try parsing as seconds
      const durationSeconds = parseFloat(stringValue);
      return isNaN(durationSeconds) ? null : durationSeconds;

    case UITypes.MultiSelect:
      // Split on common delimiters
      if (stringValue.includes(',')) {
        return stringValue.split(',').map(s => s.trim()).filter(s => s);
      } else if (stringValue.includes(';')) {
        return stringValue.split(';').map(s => s.trim()).filter(s => s);
      } else if (stringValue.includes('|')) {
        return stringValue.split('|').map(s => s.trim()).filter(s => s);
      }
      return [stringValue];

    case UITypes.SingleSelect:
      return stringValue;

    case UITypes.JSON:
      try {
        return JSON.parse(stringValue);
      } catch {
        return stringValue; // Keep as string if not valid JSON
      }

    case UITypes.Email:
      // Basic email validation
      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
      return emailRegex.test(stringValue) ? stringValue : null;

    case UITypes.URL:
      // Basic URL validation
      try {
        new URL(stringValue);
        return stringValue;
      } catch {
        // Try adding https:// if it looks like a domain
        if (stringValue.includes('.') && !stringValue.includes(' ')) {
          try {
            new URL(`https://${stringValue}`);
            return `https://${stringValue}`;
          } catch {
            return null;
          }
        }
        return null;
      }

    case UITypes.PhoneNumber:
      // Clean phone number - keep digits, +, parentheses, hyphens, spaces
      return stringValue.replace(/[^\d+()-\s]/g, '');

    case UITypes.GeoData:
      // Try to parse as lat,lng or JSON
      if (stringValue.includes(',')) {
        const [lat, lng] = stringValue.split(',').map(s => parseFloat(s.trim()));
        if (!isNaN(lat) && !isNaN(lng)) {
          return { latitude: lat, longitude: lng };
        }
      }
      try {
        const geoData = JSON.parse(stringValue);
        if (geoData.latitude !== undefined && geoData.longitude !== undefined) {
          return geoData;
        }
      } catch {
        // Not valid JSON
      }
      return null;

    case UITypes.Attachment:
      // For attachments, we can only handle URLs
      try {
        new URL(stringValue);
        return [{
          url: stringValue,
          title: stringValue.split('/').pop() || 'attachment'
        }];
      } catch {
        return null;
      }

    case UITypes.User:
      // Try to find user by email
      const collaborator = base.getCollaborator(stringValue);
      if (collaborator) {
        return [collaborator.id]; // Users are stored as arrays of IDs
      }
      return null;
    case UITypes.Barcode:
    case UITypes.QrCode:
      return { value: stringValue };

    case UITypes.SingleLineText:
    case UITypes.LongText:
    case UITypes.SpecificDBType:
    default:
      return stringValue;
  }
}

// Execute the import
await importCSVData();
```

### Use Cases

* **Bulk Data Import**: Import structured data from CSV files into a selected table
* **Data Migration**: Move data from spreadsheets or legacy systems into NocoDB
* **Mass Updates**: Update existing records using values from a CSV file
* **Onboarding**: Quickly populate tables with user, product, or customer information

### How it Works

1. **Select Table**: Choose the destination table for importing data
2. **Upload CSV File**: Upload a CSV with or without headers
3. **Preview File**: View row and column counts with a sample of the uploaded data
4. **Handle Duplicates**: Choose whether to skip, update, or allow duplicates
5. **Select Unique Field** (if applicable): Specify the field to identify duplicate records
6. **Map Columns**: Match CSV columns to table fields with auto-suggestions and manual mapping
7. **Review Mappings**: Confirm which columns will be imported and how they’re mapped
8. **Import Records**: Data is processed in batches with support for create and update operations
9. **See Results**: Get a detailed report of created, updated, skipped, and failed records

### Requirements

* A **CSV file** with structured rows and columns
* A **destination table** with relevant fields configured
* Optional: A **unique field** in the table to detect and manage duplicate records

### Supported Field Types

* Single Line Text
* Long Text
* Number
* Decimal
* Currency
* Percent
* Rating
* Checkbox
* Select (Single & Multi)
* Date/Time
* Email
* URL
* Phone Number
* Attachment (URLs only)
* User (by email)
* JSON
* Barcode / QR Code
* Geo Location

### Features

* **Interactive Mapping**: Automatically detect and map matching fields
* **Duplicate Handling**: Choose how duplicates are treated—skip, update, or allow
* **Batch Processing**: Imports data in small chunks for reliability
* **Field Type Transformation**: Automatically transforms values to match field types
* **Import Summary**: See a complete report with success rates and failed row details
* **Cancel Anytime**: Option to cancel at every major step

### Best Practices

* Always review field mappings before confirming the import
* Clean up CSV headers to closely match table field names for better auto-mapping
* Use a unique field (e.g., email, ID) for accurate duplicate detection and updates
* Check the sample preview to catch formatting issues early
* Prefer smaller files for better performance and easier troubleshooting


# Examples
URL: /docs/scripts/examples

Browse a collection of useful script examples to automate and enhance your workflows in NocoDB.

Explore ready-to-use scripts to automate repetitive tasks, clean up data, and extend the power of your NocoDB workspace.

### [Find and Replace](/docs/scripts/examples/find-and-replace)

Search for a specific value in a field and replace it with another. Useful for correcting data inconsistencies or renaming entries in bulk.

### [Convert Attachments to URLs](/docs/scripts/examples/convert-attachments-to-urls)

Convert attachment fields into comma-separated URL lists for integration with external services.

### [Randomize Values](/docs/scripts/examples/randomize-values)

Generate random data for empty fields across multiple data types with customizable ranges and constraints.

### [Validate Emails](/docs/scripts/examples/validate-emails)

Identify and list all invalid email addresses in email fields for data quality assurance.

### [Select Options](/docs/scripts/examples/select-options)

List all options used in a single or multi-select field across your records. Useful for analyzing select field usage or cleaning up unused options.

### [Save View Ordering](/docs/scripts/examples/save-view-ordering)

Capture the current record ordering of a view and save it into a numeric field. Perfect for preserving manual sorting or creating custom rankings.

### [Link Records by Field](/docs/scripts/examples/link-records-by-field)

Link records between two tables by matching values in selected fields. Supports pagination and displays a summary of results.

### [Unique Field Values Summary](/docs/scripts/examples/unique-field-values-summary)

Scan a field and output a summary of all unique values along with their frequency. Great for audits, cleanup, or analyzing field usage.

### [Import CSV](/docs/scripts/examples/import-csv)

Import data from a CSV file into a specified table, allowing you to quickly populate your database with external data.


# Link Records by Field
URL: /docs/scripts/examples/link-records-by-field

Link records between two tables using matching field values, with pagination and summary reporting.

This script links records between two NocoDB tables by matching values in selected fields. It allows users to:

1. Select a **source table** and a **target table**
2. Choose a **matching field** from each table
3. Choose a **linked record field** in the source table that connects to the target

For each record in the source table, the script searches for a record in the target table with a **matching value**. If a match is found, the linked record field in the source table is updated to point to that record in the target table.

It also handles large datasets using pagination and prints a clear summary of results at the end.

```javascript
// Prompt user to pick Source & Target table
const sourceTable = await input.tableAsync("Select Source table");
const targetTable = await input.tableAsync("Select Target table");

// Prompt for matching field in Source
const fieldInSource = await input.fieldAsync("Select matching field in Source table", sourceTable);

// Prompt for matching field in Target
const fieldInTarget = await input.fieldAsync("Select matching field in Target table", targetTable);

// Prompt for linked record field in Source (should link to Target)
const linkFieldInSource = await input.fieldAsync("Select linked record field in Source table", sourceTable);

// Fetch all records from Target with pagination
let targetQuery = await targetTable.selectRecordsAsync({
    fields: [fieldInTarget],
    pageSize: 100
});

const mapTarget = new Map();
function indexTargetRecords(records) {
    for (let record of records) {
        const key = record.getCellValueAsString(fieldInTarget)?.trim();
        if (key) {
            mapTarget.set(key, record);
        }
    }
}
indexTargetRecords(targetQuery.records);

while (targetQuery.hasMoreRecords) {
    await targetQuery.loadMoreRecords();
    indexTargetRecords(targetQuery.records.slice(-100));
}

// Fetch all records from Source with pagination
let sourceQuery = await sourceTable.selectRecordsAsync({
    fields: [fieldInSource, linkFieldInSource],
    pageSize: 100
});

let totalProcessed = 0;
let totalLinked = 0;
let totalUnmatched = 0;

async function linkSourceRecords(records) {
    for (let record of records) {
        const valueSource = record.getCellValueAsString(fieldInSource)?.trim();
        const matchingTargetRecord = mapTarget.get(valueSource);

        if (matchingTargetRecord) {
            await sourceTable.updateRecordAsync(record.id, {
                [linkFieldInSource.id]: [{ id: matchingTargetRecord.id }]
            });
            totalLinked++;
        } else {
            totalUnmatched++;
        }

        totalProcessed++;
        output.clear();
        output.text(`Processed ${totalProcessed} records...`);
    }
}

// Process first page
await linkSourceRecords(sourceQuery.records);

// Process remaining pages
while (sourceQuery.hasMoreRecords) {
    await sourceQuery.loadMoreRecords();
    const newRecords = sourceQuery.records.slice(-100);
    await linkSourceRecords(newRecords);
}

// Output final summary (vertical format)
output.markdown(`### ✅ Summary`);
output.table({
    "Total Records Processed": totalProcessed,
    "Records Linked": totalLinked,
    "Unmatched Records": totalUnmatched
});
```

### Use Cases

* **CRM Linking**: Connect customers to orders or support tickets using customer IDs or names
* **Product Mapping**: Link SKUs from an imported dataset to master product records
* **Inventory Management**: Associate stock movement entries with corresponding items
* **Data Consolidation**: Normalize records across multiple sources based on shared identifiers

### How It Works

1. **Select Tables & Fields**: Choose a source and target table, and matching fields in both
2. **Run the Script**: It looks up the target for every matching value in the source
3. **Link Records**: When a match is found, the source record’s linked field is updated
4. **View Summary**: A final summary shows how many records were processed, linked, or skipped

### Behavior in Edge Cases

* **Missing in Target**: If no matching target is found, the source record is skipped
* **Missing in Source**: Target records with no source match are ignored
* **Duplicate Values in Source**: All matching source records link to the same target record
* **Duplicate Values in Target**: The first match is used; others are ignored
* **Blank or Null Values**: Records with empty matching values are skipped

***


# Randomize Values
URL: /docs/scripts/examples/randomize-values

Generate random data for empty fields across multiple data types with customizable ranges and constraints

This script allows you to populate empty fields in your NocoDB tables with random values based on the field type. It supports various data types including numbers, dates, selections, and more, ensuring that the generated data is appropriate for each field's requirements.

```javascript
let settings = input.config({
    title: "Randomize Field Values",
    description: `This script will randomize values for a selected field. The following field types are supported:
- Number
- Currency
- Percent
- Rating
- Date
- User
- Single/Multiple Select`,
    items: [
        input.config.table("selectedTable", { label: "Select Table" }),
        input.config.field("selectedField", {
            parentTable: "selectedTable",
            label: "Field to Randomize",
        }),
    ],
});

let { selectedTable, selectedField } = settings as {
    selectedTable: Table,
    selectedField: Field
};

output.text(`Starting randomization of '${selectedField.name}' field in '${selectedTable.name}' table...`);

let valueRange: Record<string, any>;

switch (selectedField.type) {
    case UITypes.Currency: {
        valueRange = await getValueRange(async () => {
            let minValue = await promptForNumber("Enter the minimum currency value:");
            let maxValue = await promptForNumber("Enter the maximum currency value:");
            return await confirmValueRange(minValue, maxValue);
        });
        await updateSelectedField((record) => randomBetween(valueRange.min, valueRange.max, identity));
        break;
    }
    case UITypes.Date: {
        valueRange = await getValueRange(async () => {
            let earliestDate = await promptForDate("Enter the earliest date:");
            let latestDate = await promptForDate("Enter the latest date:");
            return await confirmValueRange(earliestDate, latestDate);
        });
        await updateSelectedField((record) => randomDateBetween(valueRange.min, valueRange.max));
        break;
    }
    case UITypes.DateTime: {
        valueRange = await getValueRange(async () => {
            let earliestDateTime = await promptForDate("Enter the earliest date/time:");
            let latestDateTime = await promptForDate("Enter the latest date/time:");
            return await confirmValueRange(earliestDateTime, latestDateTime);
        });
        await updateSelectedField((record) => randomDateBetween(valueRange.min, valueRange.max));
        break;
    }
    case UITypes.MultiSelect: {
        valueRange = await getValueRange(async () => {
            let minSelections = await promptForNumber("Enter minimum number of selections:");
            let maxSelections = await promptForNumber("Enter maximum number of selections:");
            return await confirmValueRange(minSelections, maxSelections);
        });

        if (!selectedField.options) {
            throw new Error('Multi-select field is missing options configuration');
        }

        const fieldOptions = selectedField.options;
        if (fieldOptions.choices.length < valueRange.min) {
            output.text(`❌ Error: Field only has ${fieldOptions.choices.length} choices, but minimum requirement is ${valueRange.min}.`);
            break;
        }

        await updateSelectedField((record) => {
            const availableChoices = fieldOptions.choices.map((choice) => choice.title);
            let numberOfSelections = randomBetween(valueRange.min, Math.min(valueRange.max, availableChoices.length), Math.ceil);
            let shuffledChoices = shuffleArray(availableChoices);
            return shuffledChoices.slice(0, numberOfSelections);
        });
        break;
    }
    case UITypes.Number: {
        valueRange = await getValueRange(async () => {
            let minNumber = await promptForNumber("Enter the minimum number:");
            let maxNumber = await promptForNumber("Enter the maximum number:");
            return await confirmValueRange(minNumber, maxNumber);
        });
        await updateSelectedField((record) => randomBetween(valueRange.min, valueRange.max));
        break;
    }
    case UITypes.Percent: {
        valueRange = await getValueRange(async () => {
            let minPercent = await promptForNumber("Enter the minimum percentage:");
            let maxPercent = await promptForNumber("Enter the maximum percentage:");
            return await confirmValueRange(minPercent, maxPercent);
        });
        await updateSelectedField((record) => randomBetween(valueRange.min, valueRange.max));
        break;
    }
    case UITypes.Rating: {
        if (!selectedField.options) {
            throw new Error('Rating field is missing options configuration');
        }
        const ratingOptions = selectedField.options;
        await updateSelectedField((record) => randomBetween(1, ratingOptions.max_value));
        break;
    }
    case UITypes.User: {
        await updateSelectedField(
            (record) =>
                base.activeCollaborators[
                    randomBetween(0, base.activeCollaborators.length, Math.floor)
                ]
        );
        break;
    }
    case UITypes.SingleSelect: {
        if (!selectedField.options) {
            throw new Error('Single-select field is missing options configuration');
        }
        const selectOptions = selectedField.options;
        await updateSelectedField(
            (record) =>
                selectOptions.choices[randomBetween(0, selectOptions.choices.length, Math.floor)].title
        );
        break;
    }
    default: {
        output.text(
            `❌ Field '${selectedField.name}' (type: ${selectedField.type}) cannot be randomized with this script. Please select a supported field type or customize the script to handle this field type.`
        );
        break;
    }
}

output.text("✅ Randomization complete! Run the script again to randomize another field.");

// Utility Functions

function identity(value) {
    return value;
}

function randomBetween(min, max, roundingFunction = Math.round) {
    return roundingFunction((max - min) * Math.random()) + min;
}

function shuffleArray(originalArray) {
    let shuffledArray = originalArray.slice(0);
    for (let i = shuffledArray.length - 1; i > 0; i--) {
        const randomIndex = Math.floor(Math.random() * (i + 1));
        [shuffledArray[i], shuffledArray[randomIndex]] = [shuffledArray[randomIndex], shuffledArray[i]];
    }
    return shuffledArray;
}

/**
 * Generate a random date between two dates
 * @param {Date} startDate - The earliest possible date
 * @param {Date} endDate - The latest possible date
 */
function randomDateBetween(startDate, endDate) {
    return new Date(Math.round(randomBetween(startDate.getTime(), endDate.getTime())));
}

async function promptForNumber(promptText) {
    return Number(await input.textAsync(promptText));
}

async function promptForDate(promptText) {
    return new Date(await input.textAsync(promptText));
}

async function confirmValueRange(minValue, maxValue) {
    const confirmed = await input.buttonsAsync(
        `Confirm randomization range: ${minValue} to ${maxValue}`,
        [
            { label: "✅ Confirm", value: true },
            { label: "❌ Cancel", value: false },
        ]
    );

    if (confirmed) {
        return { min: minValue, max: maxValue };
    }
    return null;
}

async function getValueRange(rangeInputFunction) {
    let range;
    do {
        range = await rangeInputFunction();
    } while (!range);
    return range;
}

/**
 * Update the selected field for all records that have empty values
 * @param {(record: Record) => any} valueGeneratorFunction - Function to generate new values
 */
async function updateSelectedField(valueGeneratorFunction) {
    let recordUpdates = [];
    let processedCount = 0;

    const recordQuery = await selectedTable.selectRecordsAsync({ fields: [selectedField] });

    // Load all records
    while (recordQuery.hasMoreRecords) {
        await recordQuery.loadMoreRecords();
    }

    output.text(`📊 Processing ${recordQuery.records.length} records...`);

    // Process records that have empty values
    for (let record of recordQuery.records) {
        const currentValue = record.getCellValue(selectedField);
        if (!currentValue || (Array.isArray(currentValue) && currentValue.length === 0)) {
            const newValue = valueGeneratorFunction(record);
            recordUpdates.push({
                id: record.id,
                fields: { [selectedField.id]: newValue }
            });
            processedCount++;
        }
    }

    if (recordUpdates.length === 0) {
        output.text("ℹ️  No empty records found to update.");
        return;
    }

    output.text(`🔄 Updating ${recordUpdates.length} records with empty values...`);

    // Update records in batches of 10
    for (let batchStart = 0; batchStart < recordUpdates.length; batchStart += 10) {
        const batchEnd = Math.min(batchStart + 10, recordUpdates.length);
        const currentBatch = recordUpdates.slice(batchStart, batchEnd);

        output.text(`📝 Updating batch ${Math.floor(batchStart / 10) + 1}/${Math.ceil(recordUpdates.length / 10)} (records ${batchStart + 1}-${batchEnd})`);

        await selectedTable.updateRecordsAsync(currentBatch);
    }

    output.text(`✅ Successfully updated ${recordUpdates.length} records.`);
}
```

### Use Cases

* **Demo Data**: Create realistic sample data for presentations and testing
* **Test Scenarios**: Generate varied data sets for application testing
* **Placeholder Content**: Fill empty fields with appropriate dummy data
* **Data Modeling**: Create diverse datasets for analysis and development

### Supported Field Types

#### Numeric Fields

* **Number**: Generate random integers or decimals within specified ranges
* **Currency**: Create random monetary values with proper decimal precision
* **Percent**: Generate percentage values between defined minimum and maximum
* **Rating**: Random ratings within the field's configured scale

#### Date Fields

* **Date**: Random dates within a specified date range
* **DateTime**: Random date and time combinations within defined boundaries

#### Selection Fields

* **SingleSelect**: Randomly choose from available options
* **MultiSelect**: Generate random combinations of available options
* **User**: Randomly assign from available collaborators

### How it Works

1. **Select Field**: Choose the field you want to populate with random values
2. **Configure Ranges**: Set minimum and maximum values or date ranges as applicable
3. **Set Constraints**: Define any specific parameters for the field type
4. **Preview Settings**: Review your configuration before applying
5. **Generate Values**: The script fills only empty cells, preserving existing data

### Requirements

* Fields with **empty values** (existing data will not be overwritten)
* **Appropriate field types** from the supported list above
* **Valid ranges** or constraints for the selected field type

### Configuration Examples

#### Number Field

* **Minimum**: 1
* **Maximum**: 1000

#### Date Field

* **Start Date**: January 1, 2024
* **End Date**: December 31, 2024

#### Currency Field

* **Minimum**: $10.00
* **Maximum**: $500.00

#### Rating Field

* **Scale**: 1-5 stars (uses field's configured rating scale)

#### SingleSelect Field

* **Options**: Randomly selects from all available options in the field

### Features

* **Preserves Existing Data**: Only fills empty cells, never overwrites existing values
* **Type-Appropriate**: Generates data that matches each field's specific requirements
* **Customizable Ranges**: Set meaningful boundaries for numeric and date fields
* **Realistic Values**: Creates data that looks natural and appropriate
* **Batch Processing**: Efficiently handles large numbers of records

### Best Practices

* Set realistic ranges that match your data requirements
* Test with a small sample before applying to large datasets
* Consider your field validation rules when setting ranges
* Use meaningful date ranges for time-based data
* Review the generated data to ensure it meets your needs

### Safety Features

* **Non-Destructive**: Existing data is completely preserved
* **Empty Cells Only**: Only populates fields that are currently empty
* **Type Validation**: Ensures generated values match field type requirements
* **Range Compliance**: All values respect the specified minimum and maximum bounds


# Save View Ordering to Field
URL: /docs/scripts/examples/save-view-ordering

Preserve manual record ordering from any view by saving it as sequential numbers in a numeric field

This script captures the current ordering of records in a selected view and saves it as sequential numbers (1, 2, 3...) to a numeric field of your choice. This allows you to preserve manually arranged record sequences and apply the same ordering to other views.

```javascript
const config = input.config({
    title: 'Save view ordering to field',
    description: `A script to save the record ordering of a particular view to a specified field in the table.

This ordering can then be applied to other views by sorting on that field.

Useful when you want to apply the order from one view to another view after manually reordering records.`,
    items: [
        input.config.table('sourceTable', {
            label: 'Table',
            description: 'The table containing the view you want to save the ordering from'
        }),
        input.config.view('sourceView', {
            label: 'Source View',
            description: 'The view whose ordering you want to save to a field',
            parentTable: 'sourceTable'
        }),
        input.config.field('orderingField', {
            label: 'Order field',
            description: 'The field you want to save the ordering to, this must be a number field.',
            parentTable: 'sourceTable'
        })
    ]
});

if (config.orderingField.type !== UITypes.Number) {
    output.markdown(`**Error**: Order field must be of type number.`);
    return;
}

const { sourceTable, sourceView, orderingField } = config;

output.markdown(`#### Assigning ordering from view "${sourceView.name}" to field "${orderingField.name}"`);

// Process records in chunks to avoid loading everything into memory
const queryResult = await sourceView.selectRecordsAsync();
const UPDATE_BATCH_SIZE = 10;
let orderNumber = 1;
let totalProcessed = 0;

while (true) {
    // Get only the new records from this chunk (not already processed)
    const newRecords = queryResult.records.slice(totalProcessed);

    // If no new records to process, we're done
    if (newRecords.length === 0) {
        break;
    }

    output.markdown(`Processing chunk of ${newRecords.length} new records (starting from order ${orderNumber})`);

    // Prepare updates for current chunk
    const recordUpdates = [];
    for (const record of newRecords) {
        recordUpdates.push({
            id: record.id,
            fields: { [orderingField.name]: orderNumber }
        });
        orderNumber++;
    }

    // Update records in batches of 10 within this chunk
    let chunkProcessed = 0;
    while (chunkProcessed < recordUpdates.length) {
        const batchStart = chunkProcessed;
        const batchEnd = Math.min(chunkProcessed + UPDATE_BATCH_SIZE, recordUpdates.length);
        const currentBatch = recordUpdates.slice(batchStart, batchEnd);

        output.markdown(`  → Updating records ${totalProcessed + batchStart + 1} to ${totalProcessed + batchEnd}`);

        await sourceTable.updateRecordsAsync(currentBatch);
        chunkProcessed = batchEnd;
    }

    totalProcessed += recordUpdates.length;

    // Try to load more records if available
    if (queryResult.hasMoreRecords) {
        await queryResult.loadMoreRecords();
    }
}

output.markdown(`**Done!** Successfully assigned ordering numbers to ${totalProcessed} records.`);
```

### Use Cases

* **Preserve Manual Ordering**: Save custom record arrangements that took time to organize
* **Cross-View Consistency**: Apply the same ordering logic to multiple views
* **Priority Systems**: Create numbered priority sequences for tasks or items
* **Reference Ordering**: Maintain canonical record sequences for reporting
* **Backup Arrangements**: Preserve ordering before applying filters or sorts

### How it Works

1. **Select Source View**: Choose the view with the desired record ordering
2. **Choose Numeric Field**: Select a number field to store the sequence values
3. **Capture Ordering**: The script reads the current record order from the view
4. **Assign Numbers**: Sequential numbers (1, 2, 3...) are written to the chosen field
5. **Apply Elsewhere**: Sort other views by this numeric field to reproduce the ordering

### Requirements

* A **Number field** in your table (preferably configured as an integer)
* A **view** with the desired record ordering already arranged
* **Write permissions** to modify the selected numeric field

### Workflow Example

**Step 1: Arrange Records**

```
View: "Priority Tasks"
Current Order:
- Complete project proposal
- Review budget requirements  
- Schedule team meeting
- Update documentation
```

**Step 2: Run Script**

* Select "Priority Tasks" view
* Choose "Sort Order" number field
* Execute script

**Step 3: Result**

```
Records with new Sort Order values:
- Complete project proposal → Sort Order: 1
- Review budget requirements → Sort Order: 2
- Schedule team meeting → Sort Order: 3
- Update documentation → Sort Order: 4
```

**Step 4: Reproduce Ordering**

* In any other view, sort by "Sort Order" field
* Records appear in the exact same sequence

### Benefits

* **Persistent Ordering**: Manual arrangements survive view changes and filters
* **Reusable Sequences**: Apply the same ordering logic across multiple views
* **Reference Standard**: Create a canonical ordering for your data
* **Time Saving**: Avoid re-arranging records manually in different views
* **Flexible Application**: Sort by the numeric field whenever you need the preserved order

### Best Practices

* Use an **integer Number field** for clean sequential values
* **Name the field clearly** (e.g., "Priority Order", "Display Sequence", "Sort Index")
* **Document the source view** so team members understand the ordering logic
* **Update periodically** if the preferred ordering changes
* **Combine with filters** to create ordered subsets of your data


# Script Steps Example
URL: /docs/scripts/examples/script-steps

Example demonstrating how to use script steps to create visual progress tracking in scripts

This example demonstrates how to use the script API to create visual progress tracking for a data processing script. The script steps provide users with clear feedback about what the script is doing at each stage.

```javascript
// Data Processing Script with Script Steps
// This script processes customer data and generates a summary report

// Step 1: Initialize the script step
script.step({
  title: 'Initializing Data Processing',
  description: 'Setting up the data processing pipeline',
  icon: 'database',
  color: 'blue'
});

// Get user input for which table to process
const customerTable = await input.tableAsync('Select the customer table to process:');
const orderTable = await input.tableAsync('Select the orders table:');

// Step 2: Data validation
script.step({
  title: 'Validating Data Structure',
  description: 'Checking table structure and field compatibility',
  icon: 'checkCircle',
  color: 'yellow'
});

// Validate required fields exist
const requiredCustomerFields = ['Name', 'Email', 'Status'];
const requiredOrderFields = ['Customer ID', 'Order Date', 'Total'];

const customerFields = customerTable.fields.map(f => f.name);
const orderFields = orderTable.fields.map(f => f.name);

const missingCustomerFields = requiredCustomerFields.filter(field => 
  !customerFields.includes(field)
);
const missingOrderFields = requiredOrderFields.filter(field => 
  !orderFields.includes(field)
);

if (missingCustomerFields.length > 0 || missingOrderFields.length > 0) {
  script.step({
    title: 'Validation Failed',
    description: 'Required fields are missing from the selected tables',
    icon: 'xCircle',
    color: 'red'
  });
  
  output.text('❌ Validation failed!');
  if (missingCustomerFields.length > 0) {
    output.text(`Missing customer fields: ${missingCustomerFields.join(', ')}`);
  }
  if (missingOrderFields.length > 0) {
    output.text(`Missing order fields: ${missingOrderFields.join(', ')}`);
  }
  return;
}

// Step 3: Fetch customer data
script.step({
  title: 'Loading Customer Data',
  description: 'Retrieving all customer records from the database',
  icon: 'users',
  color: 'blue'
});

const customers = await customerTable.selectRecordsAsync({
  fields: ['Name', 'Email', 'Status', 'Created Date'],
  sorts: [{ field: 'Created Date', direction: 'desc' }]
});

output.text(`📊 Loaded ${customers.records.length} customer records`);

// Step 4: Fetch order data
script.step({
  title: 'Loading Order Data',
  description: 'Retrieving order history for analysis',
  icon: 'package',
  color: 'blue'
});

const orders = await orderTable.selectRecordsAsync({
  fields: ['Customer ID', 'Order Date', 'Total', 'Status'],
  sorts: [{ field: 'Order Date', direction: 'desc' }]
});

output.text(`📦 Loaded ${orders.records.length} order records`);

// Step 5: Process and analyze data
script.step({
  title: 'Analyzing Customer Data',
  description: 'Calculating customer metrics and order statistics',
  icon: 'analytics',
  color: 'purple'
});

// Create customer analysis
const customerAnalysis = customers.records.map(customer => {
  const customerOrders = orders.records.filter(order => 
    order.getCellValue('Customer ID') === customer.id
  );
  
  const totalSpent = customerOrders.reduce((sum, order) => 
    sum + (order.getCellValue('Total') || 0), 0
  );
  
  const orderCount = customerOrders.length;
  const avgOrderValue = orderCount > 0 ? totalSpent / orderCount : 0;
  
  return {
    name: customer.getCellValue('Name'),
    email: customer.getCellValue('Email'),
    status: customer.getCellValue('Status'),
    orderCount,
    totalSpent,
    avgOrderValue,
    lastOrderDate: customerOrders.length > 0 ? 
      customerOrders[0].getCellValue('Order Date') : null
  };
});

// Step 6: Generate insights
script.step({
  title: 'Generating Insights',
  description: 'Creating summary statistics and identifying trends',
  icon: 'lightbulb',
  color: 'orange'
});

// Calculate summary statistics
const totalCustomers = customerAnalysis.length;
const activeCustomers = customerAnalysis.filter(c => c.status === 'Active').length;
const totalRevenue = customerAnalysis.reduce((sum, c) => sum + c.totalSpent, 0);
const avgCustomerValue = totalRevenue / totalCustomers;

// Find top customers
const topCustomers = customerAnalysis
  .sort((a, b) => b.totalSpent - a.totalSpent)
  .slice(0, 5);

// Step 7: Generate report
script.step({
  title: 'Generating Report',
  description: 'Creating formatted summary report',
  icon: 'fileText',
  color: 'green'
});

// Display summary statistics
output.markdown(`
# Customer Analysis Report

## Summary Statistics
- **Total Customers**: ${totalCustomers}
- **Active Customers**: ${activeCustomers} (${Math.round(activeCustomers/totalCustomers*100)}%)
- **Total Revenue**: $${totalRevenue.toLocaleString()}
- **Average Customer Value**: $${avgCustomerValue.toFixed(2)}

## Top 5 Customers by Revenue
`);

// Display top customers table
output.table(topCustomers.map(customer => ({
  'Customer Name': customer.name,
  'Email': customer.email,
  'Orders': customer.orderCount,
  'Total Spent': `$${customer.totalSpent.toLocaleString()}`,
  'Avg Order': `$${customer.avgOrderValue.toFixed(2)}`,
  'Status': customer.status
})));

// Step 8: Completion
script.step({
  title: 'Analysis Complete',
  description: 'Customer data analysis has been successfully completed',
  icon: 'checkCircle',
  color: 'green'
});

// Optional: Ask user if they want to export the data
const shouldExport = await input.buttonsAsync(
  'Would you like to export the detailed analysis?',
  [
    { label: 'Yes, export to CSV', value: true, variant: 'primary' },
    { label: 'No, just view results', value: false, variant: 'secondary' }
  ]
);

if (shouldExport) {
  script.step({
    title: 'Exporting Data',
    description: 'Preparing CSV export of customer analysis',
    icon: 'download',
    color: 'blue'
  });
  
  // Here you would typically create and download a CSV file
  // For this example, we'll just show the data structure
  output.text('📄 Export data structure:');
  output.code(JSON.stringify(customerAnalysis.slice(0, 3), null, 2), 'json');
}

// Clear the script steps 
script.clear();

output.markdown(`
---
✅ **Analysis completed successfully!**

The customer data has been processed and analyzed. You can use these insights to:
- Identify high-value customers for special promotions
- Reach out to inactive customers with re-engagement campaigns  
- Optimize your product offerings based on order patterns
- Set customer service priorities based on customer value
`);
```


# Get Select Options
URL: /docs/scripts/examples/select-options

Extract and display all available options from Single Select or Multiple Select fields in various formats

This script allows you to extract and display all available options from Single Select or Multiple Select fields in your NocoDB database. You can choose to output the options in a simple list, a table format, or as a comma-separated string, making it easy to reference or export the data.

```javascript
const config = input.config({
  title: 'Get Single or Multiple Select Options',
  description: 'This script outputs all options for a single or multiple select field.',
  items: [
    input.config.table('sourceTable', {
      label: 'Table with the single or multiple select field'
    }),
    input.config.field('selectField', {
      label: 'Single or Multiple Select Field',
      parentTable: 'sourceTable'
    }),
    input.config.select('outputFormat', {
      label: 'Output Format',
      description: 'Choose how you want each option to be displayed.',
      options: [
        { label: 'List', value: 'list' },
        { label: 'Table', value: 'table' },
        { label: 'Comma Separated', value: 'commaSeparated' }
      ]
    })
  ]
});

// Extract configuration values
const table = config.sourceTable;
const field = config.selectField as Field;
const format = config.outputFormat;


if (![UITypes.SingleSelect, UITypes.MultiSelect].includes(field.type)) {
    throw new Error("Please select a Select Field")
}

// Get all available choices from the select field
const choices = field.options.choices;

// Output the choices based on the selected format
switch (format) {
  case 'list':
    choices.forEach(choice => {
      output.markdown(choice.title);
    });
    break;

  case 'table':
    const tableData = choices.map(choice => ({
      'Option Name': choice.title
    }));
    output.table(tableData);
    break;

  case 'commaSeparated':
    const optionNames = choices.map(choice => choice.title);
    const commaSeparatedList = optionNames.join(', ');
    output.markdown(commaSeparatedList);
    break;
}
```

### Use Cases

* **Documentation**: Create lists of all available options for field references
* **Data Analysis**: Export option lists for external analysis or reporting
* **Field Auditing**: Review all configured options in selection fields
* **Integration Setup**: Get option lists for API integrations or data mapping
* **User Training**: Generate option references for user guides and training materials

### Output Formats

The script offers three different output formats to suit your needs:

#### 1. List Format

```
Option 1
Option 2
Option 3
```

#### 2. Table Format

```
| Option |
|--------|
| Option 1 |
| Option 2 |
| Option 3 |
```

#### 3. Comma-Separated Format

```
Option 1, Option 2, Option 3
```

### How it Works

1. **Select Field**: Choose a Single Select or Multiple Select field
2. **Choose Format**: Pick your preferred output format (List, Table, or Comma-separated)
3. **Generate Output**: The script displays all available options in the selected format
4. **Copy/Export**: Use the formatted output for your intended purpose

### Requirements

* A **Single Select** or **Multiple Select** field with configured options
* The field must have at least one available option defined

### Supported Field Types

* **Single Select**: Fields where users can choose one option from a predefined list
* **Multiple Select**: Fields where users can choose multiple options from a predefined list

### Example Scenarios

#### Single Select Field: "Status"

**Available Options**: `Active`, `Inactive`, `Pending`, `Archived`

**List Output:**

```
Active
Inactive
Pending
Archived
```

**Table Output:**

```
| Status |
|--------|
| Active |
| Inactive |
| Pending |
| Archived |
```

**Comma-Separated Output:**

```
Active, Inactive, Pending, Archived
```

### Benefits

* **Quick Reference**: Instantly see all available options for any selection field
* **Multiple Formats**: Choose the output format that best fits your needs
* **Documentation Ready**: Generate properly formatted lists for documentation
* **Integration Friendly**: Export options in formats suitable for external tools
* **No Manual Copying**: Avoid manually transcribing long option lists


# Convert Date Text to ISO Format (Interactive Bulk Version)
URL: /docs/scripts/examples/text-to-date

This script converts date-time text fields in the format "MM/DD/YYYY HH:MM AM/PM" to ISO 8601 format across multiple records in a selected table.

## Convert Date Text to ISO Format (Interactive Bulk Version)

This script allows you to convert date-time text fields in the format "MM/DD/YYYY HH:MM AM/PM" to ISO 8601 format across multiple records in a selected table. You will be prompted to select the table and fields for processing.

```javascript
// ------------------------------------------------------------
// Script: Convert Date Text to ISO Format (Interactive Bulk Version)
// ------------------------------------------------------------

// Step 1: Initialization
script.step({
    title: 'Initializing Script',
    description: 'Preparing to convert date-time text fields to ISO format',
    icon: 'clock',
    color: 'blue'
});

// Step 2: Collect user input
script.step({
    title: 'Collecting Inputs',
    description: 'Please select table and fields for processing',
    icon: 'input',
    color: 'yellow'
});

// Ask user to select table and fields
const table = await input.tableAsync('Select a table to process:');
const inputField = await input.fieldAsync('Select the input field (MM/DD/YYYY HH:MM AM/PM):', table);
const outputField = await input.fieldAsync('Select the output field (for ISO format):', table);

// Confirm configuration
output.markdown(`
### ⚙️ Configuration
- **Table:** ${table.name}
- **Input Field:** ${inputField.name}
- **Output Field:** ${outputField.name}
`);

// Step 3: Load records
script.step({
    title: 'Loading Records',
    description: `Fetching all records from "${table.name}"`,
    icon: 'download',
    color: 'blue'
});

const result = await table.selectRecordsAsync({ pageSize: 50 });
while (result.hasMoreRecords) {
    await result.loadMoreRecords();
    output.text(`📥 Loaded ${result.records.length} records...`);
}
output.text(`✅ Total records loaded: ${result.records.length}`);

// Step 4: Process records
script.step({
    title: 'Processing Records',
    description: 'Parsing input values and preparing ISO formatted timestamps',
    icon: 'code',
    color: 'purple'
});

const BATCH_SIZE = 10;
let updates = [];
let processed = 0;
let updatedCount = 0;
let skippedCount = 0;

for (const record of result.records) {
    processed++;

    const inputValue = record.getCellValue(inputField);
    if (!inputValue) {
        skippedCount++;
        continue;
    }

    const match = inputValue.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4}) (\d{1,2}):(\d{2}) (AM|PM)$/);
    if (!match) {
        skippedCount++;
        continue;
    }

    let [, month, day, year, hour, minute, period] = match.map(v => v.trim());
    hour = parseInt(hour, 10);
    if (period === "PM" && hour !== 12) hour += 12;
    if (period === "AM" && hour === 12) hour = 0;

    const iso = `${year}-${month.padStart(2, "0")}-${day.padStart(2, "0")}T${String(hour).padStart(2, "0")}:${minute}:00`;

    updates.push({
        id: record.id,
        fields: { [outputField.id]: iso }
    });

    if (updates.length === BATCH_SIZE) {
        await table.updateRecordsAsync(updates);
        updatedCount += updates.length;
        updates = [];
        output.text(`💾 Committed ${updatedCount}/${result.records.length} records...`);
    }

    if (processed % 100 === 0) {
        output.text(`🔄 Processed ${processed}/${result.records.length} records...`);
    }
}

// Step 5: Commit remaining updates
if (updates.length > 0) {
    await table.updateRecordsAsync(updates);
    updatedCount += updates.length;
}

// Step 6: Completion summary
script.step({
    title: 'Conversion Complete',
    description: 'All applicable records have been processed and updated',
    icon: 'checkCircle',
    color: 'green'
});

output.markdown(`
✅ **Conversion Summary**
- **Table:** ${table.name}
- **Total Records Loaded:** ${result.records.length}
- **Records Updated:** ${updatedCount}
- **Skipped (No / Invalid Data):** ${skippedCount}

All valid date values from **${inputField.name}** are now converted to ISO format in **${outputField.name}**.
`);

```


# Unique Field Values Summary
URL: /docs/scripts/examples/unique-field-values-summary

View unique values and their frequencies in any field, with summary and table output

This script scans any field in your NocoDB table and displays all **unique values** along with how many times each value appears. It's helpful for identifying duplicates, auditing data, or quickly understanding the distribution of field content.

```javascript
// Prompt user to select a table and a field
let table = await input.tableAsync("Select a table");
let field = await input.fieldAsync("Select a field", table);

// Start query with pageSize
let queryResult = await table.selectRecordsAsync({
    fields: [field],
    pageSize: 100,
});

// Create a Map to store value -> count
let valueCounts = new Map();
let totalRecordsProcessed = 0;

// Helper function to process a batch of records
function processRecords(records) {
    totalRecordsProcessed += records.length;

    for (let record of records) {
        let value = record.getCellValue(field);

        // Normalize the value
        let normalizedValues = [];
        if (Array.isArray(value)) {
            normalizedValues = value.map(v => v?.name ?? v);
        } else if (value && typeof value === 'object') {
            normalizedValues = [value.name ?? JSON.stringify(value)];
        } else {
            normalizedValues = [value];
        }

        for (let val of normalizedValues) {
            let key = val === null ? "null" : String(val);
            valueCounts.set(key, (valueCounts.get(key) || 0) + 1);
        }
    }
}

// Process first page
processRecords(queryResult.records);

// Keep loading more pages if available
while (queryResult.hasMoreRecords) {
    await queryResult.loadMoreRecords();
    processRecords(queryResult.records.slice(-100)); // Only process newly loaded records
}

// Convert to array of objects for output.table()
let resultTable = Array.from(valueCounts.entries())
    .sort((a, b) => b[1] - a[1])
    .map(([value, count]) => ({
        Value: value,
        Count: count
    }));

output.markdown("### Unique Values with Counts");
output.table(resultTable);

// Output total number of records processed
output.markdown(`**Total records processed:** ${totalRecordsProcessed}`);
```

### Use Cases

* **Data Cleanup**: Identify unexpected or duplicate values
* **Analytics & Auditing**: Understand the frequency of values in any field
* **Form Design**: Spot commonly used values for building selects or filters
* **Debugging**: Review field behavior during imports or syncs

### How It Works

1. **Select a Table and Field**
2. **Script Scans All Records** using pagination
3. **Normalizes All Values** (including arrays, objects, linked/selects)
4. **Counts Frequency** of each unique value
5. **Displays a Table** of values and their counts
6. **Prints Total Records Processed** at the bottom

### Benefits

* ✅ Works with any field type (text, select, linked, etc.)
* ⚡ Fast and scalable (handles thousands of records with pagination)
* 📊 Output is clean, sortable, and copyable
* 🔍 Instantly highlights common or inconsistent entries
* 🧹 Helps with cleanup, analysis, or automation planning

***


# Validate Emails
URL: /docs/scripts/examples/validate-emails

Identify and list all invalid email addresses in email fields for data quality assurance

The script validates email addresses in your NocoDB database, ensuring they conform to standard email formatting rules. It scans through specified email fields and generates a report of all records with invalid email addresses, helping you maintain data quality and improve communication deliverability.

```javascript
let settings = input.config({
    title: "Validate emails",
    description: "This script will list all invalid emails for a field you pick.",
    items: [
        input.config.table("table", { label: "Table" }),
        input.config.field("field", {
            parentTable: "table",
            label: "Email field",
        }),
    ],
});

let { table, field } = settings as {
    table: Table,
    field: Field
};

let emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;

// Function to validate a single email
function validateEmail(email: string) {
    if (!email || typeof email !== 'string') {
        return { isValid: false, error: 'Empty or invalid data type' };
    }

    // Trim whitespace
    email = email.trim();

    if (email === '') {
        return { isValid: false, error: 'Empty after trimming whitespace' };
    }

    // Check length (email addresses shouldn't be longer than 254 characters)
    if (email.length > 254) {
        return { isValid: false, error: 'Email too long (>254 characters)' };
    }

    // Check for multiple @ symbols
    if ((email.match(/@/g) || []).length !== 1) {
        return { isValid: false, error: 'Invalid number of @ symbols' };
    }

    // Validate against regex
    if (!emailRegex.test(email)) {
        return { isValid: false, error: 'Invalid email format' };
    }

    // Check for consecutive dots
    if (email.includes('..')) {
        return { isValid: false, error: 'Consecutive dots not allowed' };
    }

    // Check if starts or ends with dot
    let [localPart, domain] = email.split('@');
    if (localPart.startsWith('.') || localPart.endsWith('.')) {
        return { isValid: false, error: 'Local part cannot start or end with dot' };
    }

    if (domain.startsWith('.') || domain.endsWith('.')) {
        return { isValid: false, error: 'Domain cannot start or end with dot' };
    }

    return { isValid: true, error: null };
}

// Function to handle multiple emails in one cell
function validateMultipleEmails(cellValue) {
    if (!cellValue || typeof cellValue !== 'string') {
        return [{ email: cellValue, isValid: false, error: 'Empty or invalid data type' }];
    }

    // Check if multiple emails are present (separated by common delimiters)
    let emails = [];
    let delimiters = /[,;|\n\r]/;

    if (delimiters.test(cellValue)) {
        // Multiple emails detected
        emails = cellValue.split(delimiters).map(email => email.trim()).filter(email => email !== '');
    } else {
        // Single email
        emails = [cellValue.trim()];
    }

    return emails.map(email => {
        let validation = validateEmail(email);
        return {
            email: email,
            isValid: validation.isValid,
            error: validation.error
        };
    });
}

// Fetch records from the selected table
let queryResult = await table.selectRecordsAsync({
    fields: [field],
});

// Handle pagination - load all records if there are more pages
while (queryResult.hasMoreRecords) {
    await queryResult.loadMoreRecords();
}

// Array to store validation results
let results = [];
let totalEmailsChecked = 0;
let totalInvalidEmails = 0;

// Process each record
for (let record of queryResult.records) {
    let recordName = record.name || record.id;
    let cellValue = record.getCellValue(field);

    // Validate emails in this cell
    let emailValidations = validateMultipleEmails(cellValue);

    for (let validation of emailValidations) {
        totalEmailsChecked++;

        if (!validation.isValid) {
            totalInvalidEmails++;
            results.push({
                Record: recordName,
                Email: validation.email || '(empty)',
                Error: validation.error,
                'Original Cell Value': cellValue || '(empty)'
            });
        }
    }
}

// Display results
if (results.length === 0) {
    output.text(
        `✅ All emails are valid! (${totalEmailsChecked} emails in ${queryResult.records.length} records validated)`
    );
} else {
    output.text(
        `❌ ${totalInvalidEmails} invalid emails found in ${results.length} entries. (${totalEmailsChecked} total emails in ${queryResult.records.length} records validated)`
    );

    // Group results by error type for better readability
    let errorGroups = {};
    for (let result of results) {
        if (!errorGroups[result.Error]) {
            errorGroups[result.Error] = [];
        }
        errorGroups[result.Error].push(result);
    }

    // Display grouped results
    for (let [errorType, items] of Object.entries(errorGroups)) {
        output.markdown(`\n**${errorType}** (${items.length} ${items.length === 1 ? 'email' : 'emails'}):`);
        output.table(items.map(item => ({
            Record: item.Record,
            Email: item.Email,
            'Original Cell Value': item['Original Cell Value']
        })));
    }
}
```

### Use Cases

* **Data Quality Assurance**: Ensure all email addresses in your database are properly formatted
* **Marketing Campaign Prep**: Clean email lists before sending campaigns to improve deliverability
* **Contact Management**: Identify and fix invalid email addresses in customer databases
* **Import Validation**: Check imported data for email formatting issues
* **Compliance Auditing**: Verify email data quality for regulatory compliance requirements

### How it Works

1. **Select Email Field**: Choose the email field you want to validate
2. **Run Validation**: The script checks each email address against standard email format rules
3. **Generate Report**: View a list of all records with invalid email addresses
4. **Review Results**: Examine the invalid emails and their associated records

### Requirements

* An **Email field** or **Text field** containing email addresses
* Records with email data to validate

### Validation Rules

The script checks for common email format issues:

* **Missing @ symbol**: `userexample.com`
* **Invalid domain format**: `user@domain`
* **Multiple @ symbols**: `us@er@example.com`
* **Invalid characters**: `user@exam<ple.com`
* **Missing local part**: `@example.com`
* **Missing domain**: `user@`
* **Improper spacing**: `user @example.com`

### Example Output

**Invalid Email Report:**

```
Record ID | Email Address | Issue
----------|---------------|--------
123       | user.example.com | Missing @ symbol
145       | admin@domain | Invalid domain format
167       | test@@example.com | Multiple @ symbols
189       | contact@exam ple.com | Invalid spacing
201       | @example.com | Missing local part
```

### Common Invalid Formats

#### Missing @ Symbol

```
❌ Invalid: johndoeexample.com
✅ Valid: johndoe@example.com
```

#### Incomplete Domain

```
❌ Invalid: admin@company
✅ Valid: admin@company.com
```

#### Extra Characters

```
❌ Invalid: user@exam<ple.com
✅ Valid: user@example.com
```

#### Spacing Issues

```
❌ Invalid: contact @example.com
✅ Valid: contact@example.com
```

### Benefits

* **Data Quality**: Maintain high-quality email data for better communication
* **Deliverability**: Improve email campaign success rates by removing invalid addresses
* **Error Prevention**: Catch email formatting issues before they cause problems
* **Compliance**: Meet data quality standards for email marketing and communication
* **Efficiency**: Quickly identify problematic emails across large datasets

### Field Types

This script works with:

* **Email fields**: Purpose-built email fields in NocoDB
* **Text fields**: Any text field containing email addresses
* **Single Line Text**: Standard text fields with email content


# Fields: Date & Time
URL: /docs/scripts/examples/demo/field-date-time

Create fields to capture dates, times, and durations.

This script demonstrates how to create & work with following fields in NocoDB
`Date` `Time` `DateTime` `Duration`

Detailed descriptions of each field type & associated configuration options are available in the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Date & Time Fields

const tableName = 'DateTime Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

// Date field
//
await createField('Start Date', {
  type: "Date",
  default_value: "2025-01-01", // ISO date format
  description: "The starting date of the event or task",
  options: {
      date_format: "YYYY-MM-DD"
  }
});

// Time field
//
await createField('Start Time', {
  type: "Time",
  default_value: "09:00", // 24-hr format
  description: "The starting time of the event or task",
  options: {
      "12hr_format": true // Use 12-hour format with AM/PM
  }
});

// DateTime field
//
await createField('Due DateTime', {
  type: "DateTime",
  default_value: "2025-01-01T17:00", // ISO datetime format
  description: "Deadline including both date and time"
});

// Duration field
//
await createField('Duration (mins)', {
  type: "Duration",
  default_value: "300", // in seconds
  description: "Expected duration of the event or task in minutes",
  options: {
      duration_format: "h:mm"
  }
});

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);

```


# Fields: Miscellaneous
URL: /docs/scripts/examples/demo/field-miscellaneous

Additional field types for attachments, checkboxes, ratings, and structured data.

This script demonstrates how to create & work with following fields in NocoDB
`Attachment` `Checkbox` `Rating` `JSON` `Geometry`

Detailed descriptions of each field type & associated configuration options are available in the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Miscellaneous Fields

const tableName = 'Misc Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

// Attachment Field
//
await createField('Attachment', { type: "Attachment" });

// Checkbox Field
//
await createField('Is Published', {
  type: "Checkbox",
  options: { icon: "square" }
});

// Rating Field
//
await createField('Priority', {
  type: "Rating",
  options: { icon: 'star', max_value: 5, color: '#F4B400' }
});

// JSON Field
//
await createField('Extra Info', { type: "JSON" });

// Geometry Field
//
await createField('Geometry Data', { type: "Geometry" });

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: Numerical
URL: /docs/scripts/examples/demo/field-number-based

Learn how to create numerical fields for storing quantities, percentages, currency, and more.

This script demonstrates how to create & work with the following numerical fields in NocoDB:
`Number`, `Currency`, `Decimal`, `Percent`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Numerical Fields

const tableName = 'Numeric Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

await createField('Amount', { type: "Number" });
await createField('Budget', { type: "Currency" });
await createField('Conversion Rate', { type: "Decimal" });
await createField('Progress %', { type: "Percent" });

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: Relational
URL: /docs/scripts/examples/demo/field-relational

Learn how to create and manage relational fields in NocoDB.

This script demonstrates how to create & work with the following relational fields in NocoDB:
`LinkToAnotherRecord`, `Lookup`, `Rollup`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Relational Fields Demo (LinkToAnotherRecord, Lookup, Rollup)

const projectsTableName = 'Projects';
const tasksTableName = 'Tasks';

// ---------------------
// Ensure Projects Table
// ---------------------
let projectsTable = base.getTable(projectsTableName);
if (!projectsTable) {
    projectsTable = await base.createTableAsync(projectsTableName, [
        { name: 'Project Name', type: "SingleLineText" },
        { name: 'Client', type: "SingleLineText" }
    ]);
    output.text(`✅ Created table "${projectsTableName}"`);
}

// ---------------------
// Ensure Tasks Table
// ---------------------
let tasksTable = base.getTable(tasksTableName);
if (!tasksTable) {
    tasksTable = await base.createTableAsync(tasksTableName, [
        { name: 'Task Name', type: "SingleLineText" },
        { name: 'Status', type: "SingleSelect", options: {
                choices: [
                    { title: 'To Do', color: '#6c757d' },
                    { title: 'In Progress', color: '#007bff' },
                    { title: 'Done', color: '#28a745' }
                ]
            }},
        { name: 'Hours', type: "Number" }
    ]);
    output.text(`✅ Created table "${tasksTableName}"`);
}

// ---------------------
// Create LinkToAnotherRecord: Tasks → Projects
// ---------------------
if (!tasksTable.getField('Project')) {
    await tasksTable.createFieldAsync({
        name: 'Project',
        type: "LinkToAnotherRecord",
        options: {
            relation_type: 'mm',
            related_table_id: projectsTable.id
        }
    });
    output.text(`🔗 Created "Project" field in "Tasks" as LinkToAnotherRecord to "Projects"`);
}

// ---------------------
// Create Lookup: Client info in Tasks from linked Project
// ---------------------
if (!tasksTable.getField('Project Client')) {
    await tasksTable.createFieldAsync({
        name: 'Project Client',
        type: "Lookup",
        options: {
            related_field_id: tasksTable.getField('Project').id,
            related_table_lookup_field_id: projectsTable.getField('Client').id
        }
    });
    output.text(`🔎 Created Lookup field "Project Client" in "Tasks"`);
}

// ---------------------
// Create Rollup: Total task hours per project
// ---------------------
if (!projectsTable.getField('Total Task Hours')) {
    await projectsTable.createFieldAsync({
        name: 'Total Task Hours',
        type: "Rollup",
        options: {
            related_field_id: projectsTable.getField('Tasks').id,
            related_table_rollup_field_id: tasksTable.getField('Hours').id,
            rollup_function: 'sum'
        }
    });
    output.text(`📊 Created Rollup field "Total Task Hours" in "Projects"`);
}

// ---------------------
// Summary Output
// ---------------------
output.markdown(`### 🧾 Fields in "${tasksTableName}"`);
output.table(tasksTable.fields.map(f => ({
    'Field Name': f.name,
    'Type': f.type
})));

output.markdown(`### 🧾 Fields in "${projectsTableName}"`);
output.table(projectsTable.fields.map(f => ({
    'Field Name': f.name,
    'Type': f.type
})));
```


# Fields: Select
URL: /docs/scripts/examples/demo/field-select-based

Create single select and multi select fields for categorizing data.

This script demonstrates how to create & work with the following select fields in NocoDB:
`SingleSelect`, `MultiSelect`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Select Fields

const tableName = 'Select Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

await createField('Tags', {
  type: "MultiSelect",
  options: {
    choices: [
      { title: 'UI', color: '#FFC107' },
      { title: 'API', color: '#28A745' }
    ]
  }
});

await createField('Status', {
  type: "SingleSelect",
  options: {
    choices: [
      { title: 'Draft', color: '#6c757d' },
      { title: 'Published', color: '#007BFF' }
    ]
  }
});

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: System
URL: /docs/scripts/examples/demo/field-system

Capture automatic audit information with system fields in NocoDB.

This script demonstrates how to create & work with the following system fields in NocoDB:
`CreatedBy`, `LastModifiedBy`, `CreatedTime`, `LastModifiedTime`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create System Fields

const tableName = 'System Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

await createField('Created By',   { type: "CreatedBy" });
await createField('Last Modified By', { type: "LastModifiedBy" });
await createField('Created Time', { type: "CreatedTime" });
await createField('Last Modified Time', { type: "LastModifiedTime" });

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: Text-Based
URL: /docs/scripts/examples/demo/field-text-based

Learn how to create and manage text-based fields in NocoDB.

This script demonstrates how to create & work with the following text-based fields in NocoDB:
`SingleLineText`, `LongText`, `PhoneNumber`, `Email`, `URL`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Text-Based Fields

const tableName = 'Text Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

await createField('Name', { type: "SingleLineText" });
await createField('Description', { type: "LongText" });
await createField('Phone', { type: "PhoneNumber" });
await createField('Email', { type: "Email" });
await createField('Website', { type: "URL" });

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: User & Collaborator
URL: /docs/scripts/examples/demo/field-user

Assign or reference users directly within records.

This script demonstrates how to create & work with the following fields in NocoDB:
`User`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create User Fields

const tableName = 'User Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

// Single user picker
await createField('Owner', { type: "User" });

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Fields: Virtual & Formula
URL: /docs/scripts/examples/demo/field-virtual

Add calculated or derivative data with virtual fields in NocoDB.

This script demonstrates how to create and work with the following virtual fields in NocoDB:
`Barcode`, `Formula`

For detailed descriptions of each field type and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Fields).

```javascript
// NocoDB Script: Create Virtual & Formula Fields

const tableName = 'Virtual Fields Demo';
let table = base.getTable(tableName);

if (!table) {
  table = await base.createTableAsync(tableName, []);
  output.text(`✅ Created table: "${tableName}"`);
}

// helper
async function createField(name, config) {
  if (!table.getField(name)) {
    await table.createFieldAsync({ name, ...config });
    output.text(`✅ Created: ${name}`);
  }
}

// Base text field required for virtual examples
await createField('Name', { type: "SingleLineText" });

// Create Barcode linked to “Name”
const nameField = table.getField('Name');
await createField('Barcode', {
  type: "Barcode",
  options: { barcode_value_field_id: nameField.id }
});

// Formula combining text
await createField('Greeting', {
  type: "Formula",
  options: { formula: 'CONCAT("Hello, ", {Name}, "!")' }
});

output.table(table.fields.map(f => ({ 'Field Name': f.name, 'Type': f.type })));
output.text(`ℹ️ Total fields created: ${table.fields.length}`);
```


# Generic Examples
URL: /docs/scripts/examples/demo

Browse categorized examples for working with fields, records, and tables in NocoDB scripting.

## 🏷️ Field Examples

* [Text-Based Fields](/docs/scripts/examples/demo/field-text-based) – Create fields like Single Line Text, Long Text, Email, and URL.
* [Number-Based Fields](/docs/scripts/examples/demo/field-number-based) – Add number, decimal, currency, rating, and percent fields.
* [Select-Based Fields](/docs/scripts/examples/demo/field-select-based) – Set up Single Select and Multi Select field types.
* [Date & Time Fields](/docs/scripts/examples/demo/field-date-time) – Add Date, Time, DateTime, and Year fields.
* [Relational Fields](/docs/scripts/examples/demo/field-relational) – Work with LinkToAnotherRecord, Lookup, and Rollup fields.
* [Virtual Fields](/docs/scripts/examples/demo/field-virtual) – Define computed fields like Formula and Aggregation.
* [System Fields](/docs/scripts/examples/demo/field-system) – Access and configure system-generated fields.
* [User Fields](/docs/scripts/examples/demo/field-user) – Add Collaborator and CreatedBy/UpdatedBy fields.
* [Miscellaneous Fields](/docs/scripts/examples/demo/field-miscellaneous) – Set up Barcode, QR Code, Geo, Attachment, and JSON fields.

## 📄 Record Operations

* [CRUD Operations](/docs/scripts/examples/demo/records-CRUD) – Create, read, update, and delete records via script.
* [Link Records](/docs/scripts/examples/demo/records-link) – Link records using field values or matching logic.
* [List Records](/docs/scripts/examples/demo/records-list) – Query, filter, and paginate records in a table.

## 🗃️ Table Operations

* [Working with Tables](/docs/scripts/examples/demo/table-operations) – Create tables and manage their structure programmatically.


# Records: CRUD Operations
URL: /docs/scripts/examples/demo/records-CRUD

This script demonstrates how to create, read, update, and delete records in a NocoDB table.

This script demonstrates how to perform basic CRUD (Create, Read, Update, Delete) operations on records in a NocoDB table. It includes creating a table if it doesn't exist, adding fields, creating demo records, updating those records, and finally deleting them.

More information about the NocoDB API can be found in the [NocoDB data API documentation](https://nocodb.com/apis/v3/data).

```javascript
const tableName = 'Contacts';
const fields = [
  { name: 'Name', type: 'SingleLineText' },
  { name: 'Email', type: 'Email' },
  {
    name: 'Status',
    type: 'SingleSelect',
    options: {
      choices: [
        { title: 'Active' },
        { title: 'Pending' },
        { title: 'Inactive' }
      ]
    }
  }
];

// Step 1: Create table if it doesn’t exist
let table = base.getTable(tableName);
if (!table) {
  table = await base.createTableAsync(tableName, []);
}

// Step 2: Create any missing fields
const existingFieldNames = table.fields.map(f => f.name);
for (let field of fields) {
  if (!existingFieldNames.includes(field.name)) {
    await table.createFieldAsync({ name: field.name, type: field.type, options: field.options });
  }
}

// Step 3: Create demo records
const recordsToCreate = [
  { fields: {
    'Name': 'John Doe',
    'Email': 'john.doe@example.com',
    'Status': 'Active'
  }},
  { fields: {
    'Name': 'Jane Smith',
    'Email': 'jane.smith@example.com',
    'Status': 'Pending'
  }},
  { fields: {
    'Name': 'Bob Johnson',
    'Email': 'bob.johnson@example.com',
    'Status': 'Active'
  }}
];

const createdRecords = await table.createRecordsAsync(recordsToCreate);
output.text(`✅ Created ${createdRecords.length} new records.`);

// Step 4: Read the created records
const records = await table.selectRecordsAsync();
const created = records.records.filter(r => createdRecords.includes(r.id));

const displayBeforeUpdate = created.map(r => ({
  Name: r.getCellValue('Name'),
  Email: r.getCellValue('Email'),
  Status: r.getCellValue('Status')
}));

output.text('📖 Records after creation:');
output.table(displayBeforeUpdate);

// Step 5: Update status of each record to "Inactive"
const updates = created.map(r => ({
  id: r.id,
  fields: {
    Status: 'Inactive'
  }
}));

await table.updateRecordsAsync(updates);

const updated = await table.selectRecordsAsync();
const updatedDisplay = updated.records.filter(r => createdRecords.includes(r.id)).map(r => ({
  Name: r.getCellValue('Name'),
  Email: r.getCellValue('Email'),
  Status: r.getCellValue('Status')
}));

output.text('🔁 Records after status update:');
output.table(updatedDisplay);

// Step 6: Delete the created records
await table.deleteRecordsAsync(createdRecords);
output.text(`🗑️ Deleted ${createdRecords.length} records.`);

```


# Records: Link & Unlink
URL: /docs/scripts/examples/demo/records-link

This script demonstrates how to create and manage relational fields in NocoDB, including linking & unlinking records between tables

This script demonstrates how to create and manage relational fields in NocoDB, specifically focusing on linking and unlinking records between two tables using the `LinkToAnotherRecord` field type.

```javascript
// NocoDB Script: Relational Fields Demo (LinkToAnotherRecord, Lookup, Rollup)

const projectsTableName = 'Projects';
const tasksTableName = 'Tasks';

// ---------------------
// Ensure Projects Table
// ---------------------
let projectsTable = base.getTable(projectsTableName);
if (!projectsTable) {
  projectsTable = await base.createTableAsync(projectsTableName, [
    { name: 'Project Name', type: "SingleLineText" },
    { name: 'Client', type: "SingleLineText" }
  ]);
  output.text(`✅ Created table "${projectsTableName}"`);
}

// ---------------------
// Ensure Tasks Table
// ---------------------
let tasksTable = base.getTable(tasksTableName);
if (!tasksTable) {
  tasksTable = await base.createTableAsync(tasksTableName, [
    { name: 'Task Name', type: "SingleLineText" },
    {
      name: 'Status',
      type: "SingleSelect",
      options: {
        choices: [
          { title: 'To Do', color: '#6c757d' },
          { title: 'In Progress', color: '#007bff' },
          { title: 'Done', color: '#28a745' }
        ]
      }
    },
    { name: 'Hours', type: "Number" }
  ]);
  output.text(`✅ Created table "${tasksTableName}"`);
}

// ---------------------
// Create LinkToAnotherRecord: Tasks → Projects
// ---------------------
if (!tasksTable.getField('Project')) {
  await tasksTable.createFieldAsync({
    name: 'Project',
    type: "LinkToAnotherRecord",
    options: {
      relation_type: 'mm',
      related_table_id: projectsTable.id
    }
  });
  output.text(`🔗 Created "Project" field in "Tasks" as LinkToAnotherRecord to "Projects"`);
}

// ---------------------
// Demo: Insert records, link, unlink
// ---------------------

// Step 1: Insert sample projects if empty
const projectRecords = await projectsTable.selectRecordsAsync();
if (projectRecords.records.length === 0) {
  await projectsTable.createRecordsAsync([
    { fields: { 'Project Name': 'Website Redesign', 'Client': 'Acme Corp' }},
    { fields: { 'Project Name': 'Mobile App Launch', 'Client': 'Globex Inc' }}
  ]);
  output.text(`➕ Inserted sample records in "${projectsTableName}"`);
}

// Step 2: Insert sample tasks if empty
const taskRecords = await tasksTable.selectRecordsAsync();
if (taskRecords.records.length === 0) {
  await tasksTable.createRecordsAsync([
    { fields: { 'Task Name': 'Design UI', 'Status': 'To Do', 'Hours': 10 }},
    { fields: { 'Task Name': 'Build Backend', 'Status': 'In Progress', 'Hours': 20 }},
    { fields: { 'Task Name': 'Write Docs', 'Status': 'Done', 'Hours': 5 }}
  ]);
  output.text(`➕ Inserted sample records in "${tasksTableName}"`);
}

// Refresh records
const projects = await projectsTable.selectRecordsAsync();
const tasks = await tasksTable.selectRecordsAsync();

const projectIds = projects.records.map(r => r.id);
const taskIds = tasks.records.map(r => r.id);
const projectField = tasksTable.getField('Project');

// Step 3: Link tasks to projects
const linkUpdates = tasks.records.map((task, i) => ({
  id: task.id,
  fields: {
    [projectField.id]: [{ id: projectIds[i % projectIds.length] }]
  }
}));

await tasksTable.updateRecordsAsync(linkUpdates);
output.text('🔗 Linked each task to a project');

// Step 4: Display linked state
const linkedTasks = await tasksTable.selectRecordsAsync();
output.text('📌 Tasks after linking to projects:');
output.table(linkedTasks.records.map(r => ({
  Task: r.getCellValue('Task Name'),
  Project: r.getCellValue('Project')?.records[0]?.name || ''
})));

// Step 5: Unlink all tasks
const unlinkUpdates = linkedTasks.records.map(r => ({
  id: r.id,
  fields: {
    [projectField.id]: [] // remove link
  }
}));

await tasksTable.updateRecordsAsync(unlinkUpdates);
output.text('❌ Unlinked all tasks from projects');

// Step 6: Display unlinked state
const finalTasks = await tasksTable.selectRecordsAsync();
output.text('📌 Tasks after unlinking:');
output.table(finalTasks.records.map(r => ({
  Task: r.getCellValue('Task Name'),
  Project: r.getCellValue('Project')?.records[0]?.name || '(none)'
})));

```


# Records: Pagination
URL: /docs/scripts/examples/demo/records-list

This script demonstrates how to load and display records from a selected table in NocoDB, with pagination support for large datasets.

```javascript
// Ask user to select a table
const table = await input.tableAsync('Select a table to load records from');

// Initial query with small page size
const result = await table.selectRecordsAsync({ pageSize: 50 });

// Initial log
output.text(`Loading records from "${table.name}"...`);

// Track total loaded so far
let previouslyLoaded = result.records.length;
output.text(`Loaded ${previouslyLoaded} records so far...`);

// Load all records using pagination, with progress updates
while (result.hasMoreRecords) {
  await result.loadMoreRecords();
  const newlyLoaded = result.records.length;
  const batchSize = newlyLoaded - previouslyLoaded;
  previouslyLoaded = newlyLoaded;
  output.text(`→ Loaded ${batchSize} more. Total so far: ${newlyLoaded}`);
}

// Final count
output.text(`✅ Done. Total records loaded from "${table.name}": ${result.records.length}`);
```


# Table Operations
URL: /docs/scripts/examples/demo/table-operations

Demonstrates how to check for table existence, create a table, and list all tables in the base.

This script demonstrates how to check for the existence of a table, create a new table if it doesn't exist, and list all tables in the current base in NocoDB.

For detailed descriptions of each table operation and associated configuration options, refer to the [NocoDB meta API documentation](https://nocodb.com/apis/v3/meta#tag/Tables).

```javascript
// NocoDB Script: Table Operations
// Demonstrates how to check for table existence, create a table, and list all tables in the base.

const tableName = 'Inventory';

// ------------------------------
// Check if table exists
// ------------------------------
let table = base.getTable(tableName);

if (!table) {
  output.text(`🔍 Table "${tableName}" not found. Creating it now...`);

  try {
    // ------------------------------
    // CREATE TABLE
    // ------------------------------
    table = await base.createTableAsync(tableName, [
      { name: 'Item ID', type: "SingleLineText" },
      { name: 'Item Name', type: "SingleLineText" },
      { name: 'Quantity', type: "Number" },
      {
        name: 'Category',
        type: "SingleSelect",
        options: {
          choices: [
            { title: 'Electronics', color: '#FFC107' },
            { title: 'Clothing', color: '#007BFF' },
            { title: 'Home & Garden', color: '#28A745' },
            { title: 'Books', color: '#6F42C1' },
            { title: 'Sports', color: '#DC3545' }
          ]
        }
      }
    ]);

    output.text(`✅ Table "${tableName}" created successfully!`);
  } catch (error) {
    output.text(`❌ Error creating table: ${error.message}`);
  }
} else {
  output.text(`ℹ️ Table "${tableName}" already exists.`);
}

// ------------------------------
// READ: List all tables in base
// ------------------------------
output.markdown('### 📋 Tables in this base');

const tableSummary = base.tables.map(t => ({
  'Table Name': t.name,
  'Table ID': t.id,
  'Fields': t.fields.length,
  'Views': t.views.length
}));

output.table(tableSummary);

```


# Environment variables
URL: /docs/self-hosting/environment-variables

Environment Variables for NocoDB!

For production use cases, it is crucial to set all environment variables marked as **"Mandatory"** to ensure optimal
performance, security, and functionality of NocoDB.

## Database

| Variable                    | Mandatory | Description                                                                                                                                                                                                                                                                     | If Not Set                                                                              |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `NC_DB`                     | Yes       | The primary database where all NocoDB metadata and data are stored. Example format: `pg://host.docker.internal:5432?u=username&p=password&d=database_name`.                                                                                                                     | A local SQLite database will be created in the root folder if `NC_DB` is not specified. |
| `NC_DB_JSON`                | No        | Allows setting the database connection using a valid [knex connection JSON string](https://knexjs.org/guide/#configuration-options) instead of `NC_DB`.                                                                                                                         |                                                                                         |
| `NC_DB_JSON_FILE`           | No        | A path to a knex connection JSON file can be used to specify the database connection, as an alternative to `NC_DB`.                                                                                                                                                             |                                                                                         |
| `DATABASE_URL`              | No        | A [JDBC URL string](https://jdbc.postgresql.org/documentation/use/#connecting-to-the-database) can be used for the database connection instead of `NC_DB`.                                                                                                                      |                                                                                         |
| `DATABASE_URL_FILE`         | No        | A path to a file containing a JDBC URL can be specified for the database connection as an alternative to `NC_DB`.                                                                                                                                                               |                                                                                         |
| `NC_CONNECTION_ENCRYPT_KEY` | No        | The key used to encrypt the credentials of external databases. <br /> **Warning:** Changing this variable may break the application. If you must change it, use the CLI as described in the [NocoDB Secret CLI documentation](/docs/product-docs/data-sources/updating-secret). | Keep connection credentials as plain text in the database if not set.                   |

## Authentication

| Variable                  | Mandatory | Description                                                                                                                                                                                                                                                                     | If Not Set                                                                                     |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `NC_AUTH_JWT_SECRET`      | Yes       | This JWT secret is utilized for generating authentication tokens.                                                                                                                                                                                                               | A random secret will be generated automatically.                                               |
| `NC_JWT_EXPIRES_IN`       | No        | Specifies the expiration time for JWT tokens.                                                                                                                                                                                                                                   | Defaults to `10h`.                                                                             |
| `NC_GOOGLE_CLIENT_ID`     | No        | Google client ID required to activate Google authentication.                                                                                                                                                                                                                    |                                                                                                |
| `NC_GOOGLE_CLIENT_SECRET` | No        | Google client secret required to activate Google authentication.                                                                                                                                                                                                                |                                                                                                |
| `NC_ADMIN_EMAIL`          | No        | Super admin email address. This is useful in case you need to recover your username and password. [See update requirements](#updating-super-admin-credentials).                                                                                                                 | An initial prompt for email and password is required when accessing the UI for the first time. |
| `NC_ADMIN_PASSWORD`       | No        | Super admin password. Must be at least 8 characters long, including one uppercase letter, one number, and one special character from `$&+,:;=?@#'.^*()%!_-\"`. This is useful for username and password recovery. [See update requirements](#updating-super-admin-credentials). |                                                                                                |
| `NC_DISABLE_EMAIL_AUTH`   | No        | Disables email and password-based authentication, intended for use when Google authentication variables are configured.                                                                                                                                                         |                                                                                                |

### **Updating Super Admin Credentials**

To update **either** `NC_ADMIN_EMAIL` or `NC_ADMIN_PASSWORD`, you must set **both** variables together.

## Storage

| Variable                       | Mandatory | Description                                                                                                                                                                                                                                                                                                                             | If Not Set                                                        |
| ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `NC_S3_BUCKET_NAME`            | No        | The name of the AWS S3 bucket used for the S3 storage plugin.                                                                                                                                                                                                                                                                           |                                                                   |
| `NC_S3_REGION`                 | No        | The AWS S3 region where the S3 storage plugin bucket is located. Note that `NC_S3_ENDPOINT` takes precedence if set (the endpoint URL includes the region).                                                                                                                                                                             |                                                                   |
| `NC_S3_ENDPOINT`               | No        | S3 endpoint for S3 storage plugin.                                                                                                                                                                                                                                                                                                      | Defaults to `s3.<region>.amazonaws.com`                           |
| `NC_S3_ACCESS_KEY`             | No        | The AWS access key ID for the S3 storage plugin. Required if no role access in use.                                                                                                                                                                                                                                                     |                                                                   |
| `NC_S3_ACCESS_SECRET`          | No        | The AWS access secret associated with the S3 storage plugin. Required if no role access in use.                                                                                                                                                                                                                                         |                                                                   |
| `NC_S3_FORCE_PATH_STYLE`       | No        | Whether to force [path-style requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access) for the S3 storage plugin.                                                                                                                                                                          |                                                                   |
| `NC_S3_ACL`                    | No        | The [ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) for the objects in S3                                                                                                                                                                                                                                |                                                                   |
| `NC_ATTACHMENT_FIELD_SIZE`     | No        | Maximum file size allowed for [attachments](/docs/product-docs/fields/field-types/custom-types/attachment) in bytes.                                                                                                                                                                                                                    | Defaults to `20971520` (20 MiB).                                  |
| `NC_NON_ATTACHMENT_FIELD_SIZE` | No        | Sets the maximum size in bytes for individual non-attachment form fields during multipart uploads in [shared form views](/docs/product-docs/views/share-view). Useful for increasing limit for large text or JSON fields to prevent 'Field value too long' errors when form data is submitted by individuals outside your organization. | Defaults to `1MB` (based on `multer`'s default field size limit). |
|                                |           |                                                                                                                                                                                                                                                                                                                                         |                                                                   |
| `NC_MAX_ATTACHMENTS_ALLOWED`   | No        | Maximum number of attachments allowed per cell.                                                                                                                                                                                                                                                                                         | Defaults to `10`.                                                 |
| `NC_ATTACHMENT_RETENTION_DAYS` | No        | Number of days to retain attachment on storage after all references deleted. (Set 0 to keep forever)                                                                                                                                                                                                                                    | Defaults to `10`.                                                 |
| `NC_SECURE_ATTACHMENTS`        | No        | Enables access to attachments only through pre-signed URLs. Set to `true` to activate; all other values are treated as `false`. ⚠ Note: Enabling this will make existing links inaccessible.                                                                                                                                            | Defaults to `false`.                                              |
| `NC_ATTACHMENT_EXPIRE_SECONDS` | No        | Time in seconds after which pre-signed URLs for attachments start to expire. The actual expiration will occur after this time plus an additional 10 minutes. Only applicable if `NC_SECURE_ATTACHMENTS` is enabled.                                                                                                                     | Defaults to `7200` (2 hours).                                     |

## Email Notifications

* The following SMTP variables are used to send email notifications to users, e.g., invites.

| Variable                      | Mandatory | Description                                                                                                                                                                                                                                                                                                                                 | If Not Set           |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `NC_SMTP_FROM`                | Yes       | The email address used as the sender for the SMTP plugin.                                                                                                                                                                                                                                                                                   |                      |
| `NC_SMTP_HOST`                | Yes       | The hostname of the email server for the SMTP plugin.                                                                                                                                                                                                                                                                                       |                      |
| `NC_SMTP_PORT`                | Yes       | The network port of the email server for the SMTP plugin.                                                                                                                                                                                                                                                                                   |                      |
| `NC_SMTP_USERNAME`            | Yes       | The username for authentication with the SMTP plugin.                                                                                                                                                                                                                                                                                       |                      |
| `NC_SMTP_PASSWORD`            | Yes       | The password for authentication with the SMTP plugin.                                                                                                                                                                                                                                                                                       |                      |
| `NC_SMTP_SECURE`              | No        | Enables secure authentication for the SMTP plugin. Set to `true` to enable; all other values are considered `false`.                                                                                                                                                                                                                        | Defaults to `false`. |
| `NC_SMTP_IGNORE_TLS`          | No        | Ignores TLS for the SMTP plugin (disables STARTTLS even if SMTP servers support it). Set to `true` to ignore; all other values are considered `false`. Enabling this may compromise security. For more details, see [Nodemailer's SMTP documentation](https://nodemailer.com/smtp/).                                                        | Defaults to `false`. |
| `NC_SMTP_REJECT_UNAUTHORIZED` | No        | Rejects connections to SMTP servers with invalid (self-signed) TLS certificates. Set to `true` to reject; all other values are considered `false`. Enabling this hardens security against man-in-the-middle attacks. For more details, see [Nodemailer's SMTP documentation](https://nodemailer.com/smtp/#3-allow-selfsigned-certificates). | Defaults to `false`. |

## Backend

| Variable       | Mandatory | Description                                                                                     | If Not Set          |
| -------------- | --------- | ----------------------------------------------------------------------------------------------- | ------------------- |
| `PORT`         | No        | Specifies the network port on which NocoDB will run.                                            | Defaults to `8080`. |
| `NODE_OPTIONS` | No        | Node.js [options](https://nodejs.org/api/cli.html#node_optionsoptions) to pass to the instance. |                     |

## Frontend

| Variable                     | Mandatory | Description                                                                                                                                                                                                                                          | If Not Set                                                                                                                                  |
| ---------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `NC_PUBLIC_URL`              | No        | This is the base URL used for constructing URLs in email templates, generating the Swagger documentation URL, and handling backend URL requirements. It should be set to your public-facing NocoDB URL to ensure consistency across the application. | By default, it infers the URL from the incoming request on the backend. If the server is behind a proxy, this may result in incorrect URLs. |
| `NC_DASHBOARD_URL`           | No        | Defines a custom dashboard URL path.                                                                                                                                                                                                                 | Defaults to `/dashboard`.                                                                                                                   |
| `NUXT_PUBLIC_NC_BACKEND_URL` | No        | Specifies a custom backend URL.                                                                                                                                                                                                                      | Defaults to `http://localhost:8080`.                                                                                                        |

## Cache

| Variable       | Mandatory | Description                                                                                   | If Not Set               |
| -------------- | --------- | --------------------------------------------------------------------------------------------- | ------------------------ |
| `NC_REDIS_URL` | Yes       | Specifies the Redis URL used for caching. <br /> Eg: `redis://:authpassword@127.0.0.1:6380/4` | Caching layer of backend |

## Product Configuration

| Variable                             | Mandatory | Description                                                                                                                                                                                                             | If Not Set                                 |
| ------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `DB_QUERY_LIMIT_DEFAULT`             | No        | Default pagination limit for data tables.                                                                                                                                                                               | Defaults to `25`. Maximum is `100`         |
| `DB_QUERY_LIMIT_GROUP_BY_GROUP`      | No        | Number of groups per page.                                                                                                                                                                                              | Defaults to `10`.                          |
| `DB_QUERY_LIMIT_GROUP_BY_RECORD`     | No        | Number of records per group.                                                                                                                                                                                            | Defaults to `10`.                          |
| `DB_QUERY_LIMIT_MAX`                 | No        | Maximum allowable pagination limit.                                                                                                                                                                                     | Defaults to `1000`.                        |
| `DB_QUERY_LIMIT_MIN`                 | No        | Minimum allowable pagination limit.                                                                                                                                                                                     | Defaults to `10`                           |
| `NC_CONNECT_TO_EXTERNAL_DB_DISABLED` | No        | Disables the ability to create bases on external databases.                                                                                                                                                             |                                            |
| `NC_INVITE_ONLY_SIGNUP`              | No        | Disables public signup; signup is possible only via invitations. Integrated into the [super admin settings menu](/docs/product-docs/account-settings/oss-specific-details#enable--disable-signup) as of version 0.99.0. |                                            |
| `NC_REQUEST_BODY_SIZE`               | No        | Maximum bytes allowed in the request body, based on [ExpressJS limits](https://expressjs.com/en/resources/middleware/body-parser.html#limit).                                                                           | Defaults to `1048576` (1 MB).              |
| `NC_ALLOW_LOCAL_HOOKS`               | No        | Allows webhooks to call local network links, posing potential security risks. Set to `true` to enable; all other values are considered `false`.                                                                         | Defaults to `false`.                       |
| `NC_ALLOW_LOCAL_EXTERNAL_DBS`        | No        | Allows connections to external databases on local network addresses, posing potential security risks. Set to `true` to enable; all other values are considered `false`.                                                 | Defaults to `false`.                       |
| `NC_SANITIZE_COLUMN_NAME`            | No        | Enables sanitization of column names during their creation to prevent SQL injection and other security issues.                                                                                                          | Defaults to `true`.                        |
| `NC_TOOL_DIR`                        | No        | Specifies the directory to store metadata and app-related files. In Docker setups, this maps to `/usr/app/data/` for mounting volumes.                                                                                  | Defaults to the current working directory. |
| `NC_DISABLE_PG_DATA_REFLECTION`      | No        | Disables the creation of a schema for each base in PostgreSQL.  [Click here for more detail](#postgres-data-reflection)                                                                                                 | Defaults to `false`.                       |
| `NC_MIGRATIONS_DISABLED`             | No        | Disables NocoDB migrations.                                                                                                                                                                                             |                                            |
| `NC_DISABLE_AUDIT`                   | No        | Disables the audit log feature.                                                                                                                                                                                         | Defaults to `false`.                       |
| `NC_AUTOMATION_LOG_LEVEL`            | No        | Configures logging levels for automation features. Possible values: `OFF`, `ERROR`, `ALL`. More details can be found under [Webhooks](/docs/product-docs/automation/webhook/create-webhook).                            | Defaults to `OFF`.                         |
| `NC_IFRAME_WHITELIST_DOMAINS`        | No        | Comma-separated list of domains allowed to be embedded in iframes. (Only available in NocoDB On-premise) eg: `*.nocodb.com,*.mycompany.com`                                                                             |                                            |

### Postgres Data Reflection

NocoDB UI is exactly what's in your Postgres database schema. Same tables, same columns—everything is perfectly
mirrored. This is done by creating a schema for each base in PostgreSQL. This feature is enabled by default if the user
has the required permissions. To disable it, set the `NC_DISABLE_PG_DATA_REFLECTION` environment variable to `true`.

## E2B (Script Execution)

> [E2B](https://e2b.dev/) provides sandboxed cloud environments for executing scripts. These variables are required to enable the [Webhook Run Script](/docs/product-docs/automation/webhook/create-webhook#run-script-action-) and [Workflow Run Script](/docs/workflows/nodes/action-nodes/run-script) node features.

| Variable          | Mandatory | Description                                                                                                    | If Not Set                              |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `E2B_API_KEY`     | No        | API key for authenticating with the E2B service. Required to enable script execution features.                 | Script execution features are disabled. |
| `E2B_TEMPLATE_ID` | No        | The E2B sandbox template ID that defines the execution environment for scripts. Set to `yah8ggzfy44fpdop51ai`. | Script execution features are disabled. |

## Logging & Monitoring

| Variable                 | Mandatory | Description                                                                           | If Not Set |
| ------------------------ | --------- | ------------------------------------------------------------------------------------- | ---------- |
| `NC_SENTRY_DSN`          | No        | Data Source Name (DSN) for integrating with Sentry for monitoring and error tracking. |            |
| `NC_DISABLE_ERR_REPORTS` | No        | Disable default Sentry error reporting.                                               | TRUE       |

## Debugging Only

| Variable                          | Mandatory | Description                                                                                                                                                                                                | If Not Set           |
| --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `DEBUG`                           | No        | Allows to enable various levels of debug logging. Set to `nc:*` to enable all NocoDB debug logging. Set to `nc:*,knex:*` to additionally enable database query logging. Recommended only during debugging. | Unset by default.    |
| `NC_ENABLE_ALL_API_ERROR_LOGGING` | No        | Enables more verbose API error logging. Recommended only during debugging.                                                                                                                                 | Defaults to `false`. |
| `NC_DISABLE_CACHE`                | No        | Disables caching to force metadata fetching directly from the database instead of Redis/cache. Recommended only during debugging.                                                                          | Defaults to `false`. |

## Telemetry

| Variable          | Mandatory | Description                                                                                                                                                                                  | If Not Set |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `NC_DISABLE_TELE` | No        | Disables the telemetry to prevent sending anonymous usage data. Please keep it enabled to help us understand the usage of the product and the impact that any new breaking change can cause. |            |

## Support Chat

| Variable                  | Mandatory | Description                                                                                           | If Not Set |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `NC_DISABLE_SUPPORT_CHAT` | No        | Disables the support chat within the product. We use Chatwoot which is an open source support system. | FALSE      |

## Litestream

> Litestream is used **only** when `NC_DB` is set to SQLite. It backs up the SQLite database and stores it in S3.

| Variable                              | Mandatory | Description                                                                                                                                                                                                                                                                                                        | If Not Set                                                                                                                       |
| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `LITESTREAM_S3_ENDPOINT`              | No        | URL of an S3-compatible object storage service endpoint for [Litestream](https://litestream.io/) replication of NocoDB's default SQLite database. Example: `s3.eu-central-1.amazonaws.com`.                                                                                                                        | Defaults to [AWS S3](https://aws.amazon.com/s3/).                                                                                |
| `LITESTREAM_S3_REGION`                | No        | AWS region of the Litestream replication object storage bucket. Note that `LITESTREAM_S3_ENDPOINT` takes precedence if configured (the endpoint URL includes the region).                                                                                                                                          | Defaults to the [default region configured in AWS](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-plan-region.html). |
| `LITESTREAM_S3_BUCKET`                | No        | Name of the object storage bucket to store the Litestream replication in.                                                                                                                                                                                                                                          | *Litestream replication is disabled if this variable is not set.*                                                                |
| `LITESTREAM_S3_PATH`                  | No        | Directory path to use within the Litestream replication object storage bucket.                                                                                                                                                                                                                                     | Defaults to `nocodb`.                                                                                                            |
| `LITESTREAM_S3_ACCESS_KEY_ID`         | No        | Authentication key ID for the Litestream replication object storage bucket.                                                                                                                                                                                                                                        | *Litestream replication is disabled if this variable is not set.*                                                                |
| `LITESTREAM_S3_SECRET_ACCESS_KEY`     | No        | Authentication secret for the Litestream replication object storage bucket.                                                                                                                                                                                                                                        | *Litestream replication is disabled if this variable is not set.*                                                                |
| `LITESTREAM_S3_SKIP_VERIFY`           | No        | Whether to disable TLS verification for the Litestream replication object storage service. Useful when testing against a local node such as MinIO and you are using self-signed certificates.                                                                                                                      | Defaults to `false`.                                                                                                             |
| `LITESTREAM_RETENTION`                | No        | Amount of time Litestream snapshot and WAL files are kept. After the retention period, a new snapshot is created and the old one is removed. WAL files that exist before the oldest snapshot will also be removed.                                                                                                 | Defaults to `1440h` (60 days).                                                                                                   |
| `LITESTREAM_RETENTION_CHECK_INTERVAL` | No        | Frequency in which Litestream will check if retention needs to be enforced.                                                                                                                                                                                                                                        | Defaults to `72h` (3 days).                                                                                                      |
| `LITESTREAM_SNAPSHOT_INTERVAL`        | No        | Frequency in which new Litestream snapshots are created. A higher frequency reduces the time to restore since newer snapshots will have fewer WAL frames to apply. Retention still applies to these snapshots.                                                                                                     | Defaults to `24h` (1 day).                                                                                                       |
| `LITESTREAM_SYNC_INTERVAL`            | No        | Frequency in which frames are pushed to the Litestream replica. Increasing this frequency can increase object storage costs significantly.                                                                                                                                                                         | Defaults to `60s` (1 minute).                                                                                                    |
| `LITESTREAM_AGE_PUBLIC_KEY`           | No        | [age](https://age-encryption.org/) public key generated by `age-keygen` (`age1...`) or SSH public key (`ssh-ed25519 AAAA...`, `ssh-rsa AAAA...`) used to encrypt the Litestream replication for. Refer to the relevant [Litestream documentation](https://litestream.io/reference/config/#encryption) for details. | *Litestream replication is unencrypted if this variable is not set.*                                                             |
| `LITESTREAM_AGE_SECRET_KEY`           | No        | [age](https://age-encryption.org/) secret key (`AGE-SECRET-KEY-1...`) used to encrypt the Litestream replication with. Refer to the relevant [Litestream documentation](https://litestream.io/reference/config/#encryption) for details.                                                                           | *Litestream replication is unencrypted if this variable is not set.*                                                             |
| `AWS_ACCESS_KEY_ID`                   | No        | ***Deprecated***. Please use `LITESTREAM_S3_ACCESS_KEY_ID` instead.                                                                                                                                                                                                                                                |                                                                                                                                  |
| `AWS_SECRET_ACCESS_KEY`               | No        | ***Deprecated***. Please use `LITESTREAM_S3_SECRET_ACCESS_KEY` instead.                                                                                                                                                                                                                                            |                                                                                                                                  |
| `AWS_BUCKET`                          | No        | ***Deprecated***. Please use `LITESTREAM_S3_BUCKET` instead.                                                                                                                                                                                                                                                       |                                                                                                                                  |
| `AWS_BUCKET_PATH`                     | No        | ***Deprecated***. Please use `LITESTREAM_S3_PATH` instead.                                                                                                                                                                                                                                                         |                                                                                                                                  |


# Self-hosting
URL: /docs/self-hosting

NocoDB Self-hosting Documentation

## Overview

Self-hosting NocoDB allows you to run NocoDB on your own server, giving you full control over your data and infrastructure.

## Key Features

* **Full Control**: Run NocoDB on your own server
* **Customization**: Customize NocoDB to fit your specific needs
* **Security**: Run NocoDB on your own server

## Getting Started

To self-host NocoDB, follow these steps:

1. Install NocoDB on your server
2. Configure NocoDB to fit your specific needs
3. Run NocoDB on your server

## License

NocoDB is distributed under the **Fair Code Sustainable Use License**.

You are free to self-host, evaluate, and use NocoDB for internal purposes, including building and running applications for your own organization. However, offering NocoDB as a hosted or managed service to third parties, or embedding it within a commercial SaaS offering, may require a commercial license.

For full details on permitted and restricted use, refer to the [official license text](https://github.com/nocodb/nocodb?tab=License-1-ov-file#readme) or contact the NocoDB team for commercial licensing options.

Learn more about the [Fair Code Sustainable Use License here](/docs/product-docs/getting-started/license).

***


# License Activation
URL: /docs/self-hosting/license-activation

Activate your NocoDB Enterprise license — standard, airgapped, and fully offline activation methods.

NocoDB Enterprise requires a valid license key to enable enterprise features. The activation method depends on whether your server has internet access.

## Which method should I use?

| Method                                  | When to use                                   | Internet needed |
| --------------------------------------- | --------------------------------------------- | --------------- |
| [Standard](#standard-license)           | Your server can reach the internet            | Yes — ongoing   |
| [Airgapped](#airgapped-license)         | Your server has limited or no internet access | One-time only   |
| [Offline (manual)](#offline-activation) | Your server has no internet access at all     | Never           |

Most self-hosted customers use **Standard**. If your environment restricts outbound connections, use **Airgapped**. If your server can never connect to the internet, [reach out to us](#offline-activation) and we will set it up for you.

<Callout type="info">
  Airgapped and offline activation are available exclusively on **Enterprise plans**. [Contact us](mailto:cs@nocodb.com) to learn more.
</Callout>

***

## Standard license

Best for cloud VMs, typical data centers, and any environment with internet access.

### How to activate

1. Open the NocoDB UI and go to **Admin Panel** > **License**.
2. Paste your license key and click **Save**.
3. NocoDB activates the license immediately — no restart needed.

### How it stays active

NocoDB periodically checks in with the license server (a lightweight call — no application data leaves your server). If your server temporarily loses internet, there is a **7-day grace period** before enterprise features are paused. Connectivity restored? Everything resumes automatically.

***

## Airgapped license

<Callout type="warn">
  Available on **Enterprise plans** only. [Contact sales](mailto:cs@nocodb.com) to get an airgapped license key.
</Callout>

Best for firewalled environments, restricted networks, or anywhere ongoing internet access is not possible.

With an airgapped license, NocoDB connects to the internet **once** during setup. After that single activation, it runs **fully offline** for the lifetime of the license — no check-ins, no callbacks.

### How to activate

1. You will receive a license key starting with `nc_ag_` from NocoDB.

2. Make sure your server has **temporary** outbound internet access (just for the initial activation).

3. Open the NocoDB UI and go to **Admin Panel** > **License**.

4. Paste your `nc_ag_` license key and click **Save**.

5. NocoDB activates the license with a single outbound call. Once confirmed, you can **remove internet access** — NocoDB will continue running with full enterprise features.

### Good to know

* After activation, no internet connection is needed until the license expires.
* The license is tied to your installation. If your Instance ID changes, contact us to re-activate.

***

## Offline activation

<Callout type="warn">
  Available on **Enterprise plans** only. [Contact sales](mailto:cs@nocodb.com) to set up offline activation.
</Callout>

For environments that can **never** connect to the internet — classified networks, isolated infrastructure, or strict compliance setups.

We handle this for you. Here's what to do:

1. **Start NocoDB.** During startup, it prints an **Instance ID** in the logs:

   ```bash
   docker compose logs nocodb | grep "Instance ID"
   ```

   You will see something like:

   ```
   Instance ID: a1b2c3d4e5f6789...
   ```

2. **Send us your Instance ID** along with your license key. You can reach us at:
   * Email: [cs@nocodb.com](mailto:cs@nocodb.com)
   * In-product chat (from any machine with access)
   * Your account manager

3. **We will send you back a license token.** Open the NocoDB UI, go to **Admin Panel** > **License**, paste the token, and click **Save**.

<Callout type="info">
  The license token is unique to your installation and cannot be transferred to another server.
</Callout>

***

## What is the Instance ID?

The Instance ID uniquely identifies your NocoDB deployment. It is printed in the server logs every time NocoDB starts and remains stable across restarts, updates, and reboots. If it ever changes, reach out to us for a new activation.

***

## Renewing your license

| Method        | What to do                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------- |
| **Standard**  | Nothing — renewal is automatic once your subscription is renewed.                                  |
| **Airgapped** | Temporarily restore internet access and restart NocoDB. The new expiry is picked up automatically. |
| **Offline**   | Contact us for a new license token and update it in **Admin Panel** > **License**.                 |

***

## Troubleshooting

| Problem                             | What to do                                                                                                 |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Activation fails                    | Make sure your server can reach `app.nocodb.com` over HTTPS. Check firewalls, proxies, and DNS.            |
| "Bound to a different installation" | Your installation environment changed. Contact us at [cs@nocodb.com](mailto:cs@nocodb.com) for a re-issue. |
| Enterprise features stopped working | For standard licenses, restore internet access and restart. For expired licenses, renew your subscription. |
| Can't find the Instance ID          | Check the NocoDB container logs — the Instance ID is printed during startup.                               |


# Upgrading
URL: /docs/self-hosting/upgrading

Upgrading NocoDB : Docker, Node and Homebrew!

By default, if `NC_DB` is not specified upon [installation](/docs/self-hosting/installation/auto-upstall), then SQLite will be used to store metadata. We suggest users to separate the metadata and user data in different databases as pictured in our [architecture](/docs/product-docs/engineering/architecture).

## Docker

### Find, Stop & Delete NocoDB Docker Container

```bash
# find NocoDB container ID
docker ps
# stop NocoDB container
docker stop <YOUR_CONTAINER_ID>
# delete NocoDB container
docker rm <YOUR_CONTAINER_ID>
```

Note: Deleting your docker container without setting `NC_DB` or mounting to a persistent volume for a default SQLite database will result in losing your data. See examples below.

### Find & Remove NocoDB Docker Image

```bash
# find NocoDB image
docker images
# delete NocoDB image
docker rmi <YOUR_IMAGE_ID>
```

### Pull the latest NocoDB image with same environment variables

```bash
docker run -d -p 8080:8080 \
    -e NC_DB="<YOUR_NC_DB_URL>" \
    -e NC_AUTH_JWT_SECRET="<YOUR_NC_AUTH_JWT_SECRET_IF_GIVEN>" \
    nocodb/nocodb:latest
```

Updating NocoDB docker container is similar to updating [any other docker containers](https://www.whitesourcesoftware.com/free-developer-tools/blog/update-docker-images/).

### Example: Docker Upgrade

```bash
# Previous docker run
#
terminal % docker run -d --name myNocoDB \
-v "$(pwd)"/nocodb:/usr/app/data/ \
-p 8080:8080 \
-e NC_DB="pg://host.docker.internal:5432?u=postgres&p=password&d=d1" \
-e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
nocodb/nocodb:0.111.0
Unable to find image 'nocodb/nocodb:0.111.0' locally
0.111.0: Pulling from nocodb/nocodb
ad3fa0ea069c: Pull complete 
e43b9156e769: Pull complete 
c1bee0da1504: Pull complete 
adf78ab024d9: Pull complete 
cd8000d2c16a: Pull complete 
Digest: sha256:93b6e1ba2c0b90a26b205f9c7d44053aa6d8fa037eff9eb4155ca017f6c9bed4
Status: Downloaded newer image for nocodb/nocodb:0.111.0
afdc8edd1005c93e1df8f90d02e46430ea7b5c5610a2bf9ba105238d6c4d927b


# Find, stop and delete NocoDB docker container
#
terminal % docker ps
CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS                 PORTS                    NAMES
afdc8edd1005   nocodb/nocodb:0.111.0   "/usr/bin/dumb-init …"   18 seconds ago   Up 18 seconds          0.0.0.0:8080->8080/tcp   myNocoDB
0202041b3607   postgres:14.7           "docker-entrypoint.s…"   2 days ago       Up 8 hours (healthy)   0.0.0.0:5432->5432/tcp   scripts_pg147_1

terminal % docker stop afdc8edd1005
afdc8edd1005

terminal % docker rm afdc8edd1005
afdc8edd1005


# Find and remove NocoDB docker image
#
terminal % docker images
REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
nocodb/nocodb   0.111.0   34609411e87c   5 weeks ago    132MB
mysql           8.0       6a0560a40914   7 weeks ago    599MB
postgres        14.7      2075a95c7b3b   4 months ago   358MB

terminal % docker rmi 34609411e87c
Untagged: nocodb/nocodb:0.111.0
Untagged: nocodb/nocodb@sha256:93b6e1ba2c0b90a26b205f9c7d44053aa6d8fa037eff9eb4155ca017f6c9bed4
Deleted: sha256:3bfxxxx38e682742cbxxxx535b3503af45e931fb9bd15f46eca7d33cf4c54d72
Deleted: sha256:952152b5da42ae057c6688a04xxxx72e1a2f91825956f5c7e35f91d5b285d4d8
Deleted: sha256:3155197577xxxx673675ed1bce761714a24d7803f70a905740f7d4c248cxxxxx


# Pull & run the latest NocoDB image with same environment variables as before
#
terminal % docker run -d --name myNocoDB \
-v "$(pwd)"/nocodb:/usr/app/data/ \
-p 8080:8080 \
-e NC_DB="pg://host.docker.internal:5432?u=postgres&p=password&d=d1" \
-e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
nocodb/nocodb:latest
Unable to find image 'nocodb/nocodb:latest' locally
latest: Pulling from nocodb/nocodb
ad3fa0ea069c: Pull complete 
e43b9156e769: Pull complete 
c1bee0da1504: Pull complete 
adf78ab024d9: Pull complete 
28ce4fc94e48: Pull complete 
Digest: sha256:5c6df5ff0eb1278e1dbfe684af630a743ca73dfec8c30cab3bae9c1d0d640287
Status: Downloaded newer image for nocodb/nocodb:latest
ae793a04b75f2f3ee78abbaef09891396a884ec83320151a266326195649a058


```

## Node

Updating docker container is similar to updating a npm package.

From your root folder

#### Uninstall NocoDB package

```bash
npm uninstall nocodb
```

#### Install NocoDB package

```bash
npm install --save nocodb
```

## Homebrew

Run following commands to upgrade Homebrew Nocodb version.

```bash
# Update the local homebrew formulas
brew update
# Upgrade nocodb package
brew upgrade nocodb
```


# Auto-Upstall
URL: /docs/self-hosting/installation/auto-upstall

Automatically install NocoDB with SSL in under 2 Minutes — The Ultimate Guide.

Auto-upstall is the fastest way to install NocoDB with SSL, auto-upgrades with every release, and auto-renews your SSL — all within just 2 minutes!

```bash
bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)
```

## Notes on Auto-Upstall

Auto-upstall is a single command that:

* 🐳 First Automatically installs all pre-requisites on your linux based server (docker, docker-compose)
* 🚀 Then automatically installs
  * 🇳 NocoDB,
  * 🐘 PostgreSQL,
  * ⚡ Redis,
  * 🗄 Minio,
  * 🌐 Traefik gateway.
* 🔄 Also automatically upgrades NocoDB when new versions are available.
* 🔒 And finally automatically sets up SSL that auto-renews!

## Installation Video

<center>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/AkOWLk7e_hk?si=5A1BMLlQHBtj_pHH" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</center>

## Quick installation guide

This is quick walkthrough of how to install NocoDB using auto-upstall script.

* **Step 1** :  🔐 SSH into your server (Linux-based system - Ubuntu, Debian, CentOS etc.)
* **Step 2** :  🚀 Run the below command  :
  ```bash
  bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)
  ```
* **Step 3** :  🌐 Open your browser and go to URL
  * For 🌍 HTTP: `http://<your-domain-or-ip>`
  * For 🔒 HTTPS: `https://<your-domain-or-ip>`
* **Step 4** :  🐦 Don't keep the command a secret. Tweet how easy it is. This step is a must!

<br />

<Callout type="info">
  You can find the install.nocodb.com/noco.sh script [on our GitHub here.](https://raw.githubusercontent.com/nocodb/nocodb/develop/docker-compose/1_Auto_Upstall/noco.sh)
</Callout>

## Detailed installation guide

1. Run the following command in your terminal:

   ```bash
   bash <(curl -sSL http://install.nocodb.com/noco.sh) <(mktemp)
   ```

2. Follow the installation prompts
   * **Domain name**: Enter the IP address or domain name for your NocoDB instance.
   * **SSL configuration**: If you entered a valid domain name, you'll be asked if you want to configure SSL.
   * **Advanced options**: You can choose to show advanced options or use default settings.

3. Advanced options (if chosen):
   * Choose between community (CE) or enterprise edition (EE)
   * Enter license key (for EE)
   * Enable/disable Redis for caching
   * Enable/disable Minio for file storage
   * Configure Minio domain and SSL
   * Enable/disable Watchtower for automatic updates
   * Set the number of NocoDB instances to run

4. Wait for installation to complete  - takes about 2-5 minutes.
   Once done, you'll see a success message with the URL to access your NocoDB instance.

5. Access NocoDB
   Open the URL provided in your browser to access NocoDB.

6. Congratulations! You should now have a working installation of NocoDB. Enjoy using your new no-code database platform!

## Installation management menu

After installation, you'll be asked if you want to start the management menu. This menu allows you to:

* Start NocoDB
* Stop NocoDB
* View logs
* Restart NocoDB
* Upgrade NocoDB
* Scale NocoDB (change the number of running instances)
* Monitor NocoDB (view Docker stats)

<img src="/img/v2/engineering/service-mgmt-menu.png" alt="Service Management Menu" width="600" />

## Additional Notes

* The script creates an update.sh file in the installation directory. You can use this to update NocoDB in the future.
* If you encounter any issues during installation, check the logs for error messages.


# AWS ECS (Fargate)
URL: /docs/self-hosting/installation/aws-ecs

Deploy NocoDB on AWS ECS using Fargate

This guide will walk you through deploying NocoDB on Amazon ECS using Fargate.

### Prerequisites

* AWS CLI configured with appropriate permissions
* Basic understanding of AWS ECS and Fargate

### Deployment Steps

1. Create ECS Cluster

   ```bash
     aws ecs create-cluster --cluster-name <YOUR_ECS_CLUSTER>
   ```

2. Create a Log Group:

   ```bash
   aws logs create-log-group --log-group-name /ecs/<YOUR_APP_NAME>/<YOUR_CONTAINER_NAME>
   ```

3. Create an ECS Task Definition:

   Every time you create it, it will add a new version. If it is not existing, the version will be 1.

   ```bash
   aws ecs register-task-definition --cli-input-json file://task-definition.json
   ```

   :::tip
   This json file defines the container specification. You can define secrets such as NC\_DB and environment variables here.
   :::

   Example `task-definition.json`:

   ```json
       {
           "family": "nocodb-sample-task-def",
           "networkMode": "awsvpc",
           "containerDefinitions": [
           {
               "name": "<YOUR_CONTAINER_NAME>",
               "image": "nocodb/nocodb:latest",
               "essential": true,
               "logConfiguration": {
               "logDriver": "awslogs",
               "options": {
                   "awslogs-group": "/ecs/<YOUR_APP_NAME>/<YOUR_CONTAINER_NAME>",
                   "awslogs-region": "<YOUR_AWS_REGION>",
                   "awslogs-stream-prefix": "ecs"
               }
           },
            "secrets": [
           {
               "name": "<YOUR_SECRETS_NAME>",
               "valueFrom": "<YOUR_SECRET_ARN>"
           }
           ],
           "environment": [
               {
                   "name": "<YOUR_ENV_VARIABLE_NAME>",
                   "value": "<YOUR_ENV_VARIABLE_VALUE>"
               }
           ],
           "portMappings": [
               {
                   "containerPort": 8080,
                   "hostPort": 8080,
                   "protocol": "tcp"
               }
           ]
       }
   ],
   "requiresCompatibilities": [
       "FARGATE"
   ],
   "cpu": "256",
   "memory": "512",
   "executionRoleArn": "<YOUR_ECS_EXECUTION_ROLE_ARN>",
   "taskRoleArn": "<YOUR_ECS_TASK_ROLE_ARN>"
   }
   ```

4. Create an ECS Service:

   ```bash
   aws ecs create-service \
       --cluster <YOUR_ECS_CLUSTER> \
       --service-name  <YOUR_SERVICE_NAME> \
       --task-definition <YOUR_TASK_DEF>:<YOUR_TASK_DEF_VERSION> \
       --desired-count <DESIRED_COUNT> \
       --launch-type "FARGATE" \
       --platform-version <VERSION> \
       --health-check-grace-period-seconds <GRACE_PERIOD_IN_SECOND> \
       --network-configuration "awsvpcConfiguration={subnets=["<YOUR_SUBSETS>"], securityGroups=["<YOUR_SECURITY_GROUPS>"], assignPublicIp=ENABLED}" \
       --load-balancer targetGroupArn=<TARGET_GROUP_ARN>,containerName=<CONTAINER_NAME>,containerPort=<YOUR_CONTAINER_PORT>
   ```

<Callout type="info">
  If your service fails to start, you may check the logs in ECS console or in Cloudwatch. Generally it fails due to the connection between ECS container and NC\_DB. Make sure the security groups have the correct inbound and outbound rules.
</Callout>

### Important Notes

* Ensure that your security groups have the correct inbound and outbound rules.
* The NC\_DB environment variable should be properly set to connect to your database.
* Monitor the ECS console and CloudWatch logs for any deployment issues.
* You can customize the task definition and service configuration based on your requirements.


# DigitalOcean
URL: /docs/self-hosting/installation/digital-ocean















Follow these steps to deploy NocoDB on DigitalOcean using their App Platform.

### Deployment Steps

1. On the DigitalOcean homepage, click on the Create icon and select "Apps (Deploy your code)".

   <img alt="DigitalOcean Create App" src={__img0} placeholder="blur" />

2. Choose "Docker Hub" as the source.

   <img alt="DigitalOcean Docker Hub" src={__img1} placeholder="blur" />

3. Set the source repository as nocodb/nocodb. You can optionally specify a release tag if you want a specific NocoDB version.

   <img alt="DigitalOcean Set Repository" src={__img2} placeholder="blur" />

4. Configure any additional settings as needed.

   <img alt="DigitalOcean Configure Settings" src={__img3} placeholder="blur" />

5. Name your web service and select the nearest region for cloud hosting.

   <img alt="DigitalOcean Name Service" src={__img4} placeholder="blur" />

6. Choose your preferred hosting plan and click on "Launch Basic App".

   <img alt="DigitalOcean Hosting Plan" src={__img5} placeholder="blur" />

   Your application will be built, and the URL will be live shortly. The URL will look something like [https://your-app-name.ondigitalocean.app/](https://your-app-name.ondigitalocean.app/).

### Important Notes

* Ensure you configure environment variables for database connections if needed.
* Set up persistent storage for your NocoDB data.
* You can scale your app as needed using DigitalOcean's App Platform.
* Consider enabling automatic deployments for easier updates.


# Docker Compose
URL: /docs/self-hosting/installation/docker-compose

Install NocoDB using Docker Compose

Docker Compose allows you to define and run multi-container Docker applications. It's a great way to set up NocoDB along with its database in a single configuration file.

### Prerequisites

* [Docker](https://www.docker.com/get-started)
* [Docker Compose](https://docs.docker.com/compose/install/)

### Installation Steps

1. Clone the NocoDB repository from GitHub.

   ```bash
   git clone https://github.com/nocodb/nocodb
   ```

2. Navigate to the docker-compose directory

   ```bash
   cd nocodb/docker-compose/2_pg
   ```

3. Start the services using Docker Compose:

   ```bash
   docker-compose up -d
   ```

   This will start NocoDB along with a PostgreSQL database.

4. Access NocoDB in your browser by visiting `http://localhost:8080`.

### Important Notes

* The provided `docker-compose.yml` files are configured to persist data. Make sure the volumes are properly mounted.
* You can customize the `docker-compose.yml` file to change ports, environment variables, or add additional services.

### Troubleshooting

* If you encounter any issues, check the logs using the following command:

  ```bash
  docker-compose logs
  ```

* If you need to stop the services, use the following command:

  ```bash
  docker-compose down
  ```

* Ensure all required ports are available on your host machine.

* For database connection issues, verify the database service is running:

  ```bash
  docker-compose ps
  ```


# Docker
URL: /docs/self-hosting/installation/docker

Docker installation - takes about three minutes!

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Docker installation - takes about three minutes!

Docker provides an easy way to install and run NocoDB. Follow these steps to get NocoDB up and running using Docker.

## Prerequisites

* [Docker](https://www.docker.com/get-started)

## Installation Steps

1. Choose your preferred database:

<Tabs items={['SQLite', 'Postgres']}>
  <Tab value="SQLite">
    ```
    docker run -d --name nocodb \
    -v "$(pwd)"/nocodb:/usr/app/data/ \
    -p 8080:8080 \
    nocodb/nocodb:latest
    ```
  </Tab>

  <Tab value="Postgres">
    ```
    docker run -d --name nocodb-postgres \
    -v "$(pwd)"/nocodb:/usr/app/data/ \
    -p 8080:8080 \
    -e NC_DB="pg://host.docker.internal:5432?u=root&p=password&d=d1" \
    -e NC_AUTH_JWT_SECRET="569a1821-0a93-45e8-87ab-eb857f20a010" \
    nocodb/nocodb:latest
    ```
  </Tab>
</Tabs>

2. Once the container is running, you can access NocoDB by opening [http://localhost:8080](http://localhost:8080) in your web browser.

<Callout type="info">
  For versions prior to 0.10.6, mount the volume at /usr/src/app.
</Callout>

## Troubleshooting

* If you can't access NocoDB after installation, check if the Docker container is running:

```bash
docker ps
```

* If the container is not running, check the logs for any errors:

```bash
docker logs nocodb
```

## Installation Video

<iframe width="100%" height="500" src="https://www.youtube.com/embed/K-UEecQyiOk" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />


# GCP Cloud Run
URL: /docs/self-hosting/installation/gcp-cloud-run

Installing NocoDB on Google Cloud Run

This guide will help you deploy NocoDB on Google Cloud Platform using Cloud Run.

### Prerequisites

* Google Cloud SDK installed and configured
* [Docker](https://docs.docker.com/get-docker/)

### Deployment Steps

1. Pull the NocoDB Docker image:

   ```bash
   docker pull nocodb/nocodb:latest
   ```
2. Tag the image for Google Container Registry (GCR):

   ```bash
   docker tag nocodb/nocodb:latest gcr.io/<MY_PROJECT_ID>/nocodb/nocodb:latest
   ```
3. Push the image to GCR:

   ```bash
   docker push gcr.io/<MY_PROJECT_ID>/nocodb/nocodb:latest
   ```
4. Deploy NocoDB on Cloud Run:

   ```bash
   gcloud run deploy --image=gcr.io/<MY_PROJECT_ID>/nocodb/nocodb:latest \
             --region=us-central1 \
             --allow-unauthenticated \
             --platform=managed 
   ```

### Important Notes

* Cloud Run only supports images from Google Container Registry (GCR) or Artifact registry. Hence we pull the image from Docker Hub and push it to GCR.
* Ensure that your GCP project has the necessary APIs enabled (Cloud Run, Container Registry).
* The `--allow-unauthenticated` flag is used to allow unauthenticated access to the service. You can remove this flag if you want to restrict access.


# Homebrew
URL: /docs/self-hosting/installation/home-brew

Install NocoDB using Homebrew

Homebrew provides a simple way to install NocoDB on macOS and Linux systems. Follow these steps to install NocoDB using Homebrew.

### Prerequisites

* [Homebrew](https://brew.sh/)

### Installation Steps

1. Add the NocoDB tap to Homebrew:

   ```bash
   brew tap nocodb/nocodb
   ```

2. Install NocoDB:

   ```bash
   brew install nocodb
   ```

3. Start NocoDB:

   ```bash
   nocodb
   ```

4. Access NocoDB in your browser by visiting `http://localhost:8080`.

## Updating NocoDB

To update NocoDB to the latest version, use the following command:

```bash
brew upgrade nocodb
```

### Troubleshooting

* If you encounter permission issues, make sure you have the necessary rights to install packages with Homebrew.

* If NocoDB doesn't start, check if the default port (8080) is already in use. You can specify a different port using environment variables.


# Nix/NixOS
URL: /docs/self-hosting/installation/nix

Install NocoDB on NixOS.

<Callout type="warning">
   Not supported since v0.264.6 / Sep 2025 
</Callout>

### Basic Setup

The NixOS module is the recommended method for installing and configuring NocoDB on NixOS. We advise using Flakes for this process. The NixOS module will install NocoDB and create a corresponding systemd service

```
{
  description = "Bane's NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    nocodb.url = "github:nocodb/nocodb";
  };

  outputs = inputs@{ nixpkgs, nocodb, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          nocodb.nixosModules.nocodb

          {
            # Enable NocoDB
            services.nocodb.enable = true;
          }
        ];
      };
    };
  };
}
```

### Secrets

We recommend using the `services.nocodb.environmentFile` option to securely pass secrets, such as `NC_AUTH_JWT_SECRET`, to the NixOS NocoDB instance. This approach prevents sensitive information from being committed to the NixOS repository. While it is not required, we strongly suggest using [sops-nix](https://github.com/Mic92/sops-nix) for managing secrets in a more secure and structured manner.

Example configuration:

```
services.nocodb.environmentFile = "/var/lib/secrets/nocodb.env"
```

### SSL

It is recommended to use the NixOS Nginx module with ACME for SSL certificate management. This approach ensures secure and automated handling of SSL certificates.

```
networking.firewall.allowedTCPPorts = [ 80 443 ];

services.nginx = {
    enable = true;

    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedGzipSettings = true;
    recommendedProxySettings = true;
    recommendedBrotliSettings = true;

    virtualHosts."example.com" =  {
      enableACME = true;
      forceSSL = true;
      locations."/" = {
        proxyPass = "http://127.0.0.1:8080";
        proxyWebsockets = true;
      };
    };
};
```

### PostgreSQL

For production use recommend PostgreSQL instead of SQLite

```
  services.nocodb.environments = {
    DB_URL="postgres:///nocodb?host=/run/postgresql";
  };

  services.postgresql = {
    enable = true;

    ensureDatabases = [ "nocodb" ];
    ensureUsers = [{
      name = "nocodb";
      ensureDBOwnership = true;
    }];

    package = with pkgs; postgresql_15;
    authentication = lib.mkForce ''
        #type database DBuser  origin-address auth-method
        # unix socket
        local all      all                    trust
        # ipv4
        host  all      all     127.0.0.1/32   trust
        # ipv6
        host  all      all     ::1/128        trust
    '';

    settings.log_timezone = config.time.timeZone;
  };
```

### On Other GNU/Linux Distributions and MacOS

If Nix is not already installed on your system, we recommend using the Determinate Systems Nix installer to install Nix. If Nix is already installed, you can skip this step.

To install Nix, run the following command:

```
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```

Once Nix is installed, you can run NocoDB using the following command:

```
nix run github:nocodb/nocodb
```


# Other Installation Methods
URL: /docs/self-hosting/installation/other-installations

Installing NocoDB on other platforms



























This guide covers installation methods for NocoDB on various platforms including Cloudron, CapRover, Railway, FreeBSD/FreeNAS/TrueNAS Jail, and SealOs.

### Cloudron

Cloudron provides an easy way to install and manage NocoDB.

#### Installation Steps

1. Log in to your Cloudron dashboard.
2. Navigate to the App Store.

   <img alt="Cloudron App Store" src={__img0} placeholder="blur" />
3. Search for NocoDB

   <img alt="Cloudron Search NocoDB" src={__img1} placeholder="blur" />
4. Click on the NocoDB app, then click "Install".

   <img alt="Cloudron Install" src={__img2} placeholder="blur" />
5. Configure NocoDB settings as needed.

   <img alt="Cloudron Configure" src={__img3} placeholder="blur" />
6. Once installed, go to "My Apps" and launch NocoDB.

   <img alt="Cloudron My Apps" src={__img4} placeholder="blur" />

#### Important Notes

* Ensure your Cloudron server meets the minimum requirements for running NocoDB.
* Configure backups for your NocoDB instance through Cloudron's backup system.
* Keep your Cloudron and NocoDB app up to date for the latest features and security patches.

### CapRover

#### Deployment Steps

1. Log in to your CapRover dashboard.
2. Go to "Apps" and click on "One-Click Apps/Databases".

   <img alt="CapRover One-Click Apps" src={__img5} placeholder="blur" />
3. Search for NocoDB and click on it.

   <img alt="CapRover Search NocoDB" src={__img6} placeholder="blur" />
4. Click on NocoDB to start the configuration process.
5. Configure NocoDB settings as needed and click "Deploy".

   <img alt="CapRover Deploy" src={__img7} placeholder="blur" />
6. Once deployed, you can access NocoDB from the provided URL.

#### Important Notes

* Ensure your CapRover server has sufficient resources to run NocoDB.
* Configure persistent storage for your NocoDB data.
* Set up SSL for secure access to your NocoDB instance.
* Regularly update your CapRover server and NocoDB app for the latest features and security patches.

### Railway

#### Deployment Steps

1. Go to Railway Templates.
2. Search for "NocoDB" in the templates list.

   <img alt="Railway Templates" src={__img8} placeholder="blur" />
3. Click on the NocoDB template, then click "Deploy".
4. Configure your NocoDB settings as needed.

   <img alt="Railway Configure" src={__img9} placeholder="blur" />
5. Railway will automatically deploy your NocoDB instance.

#### Important Notes

* Make sure to configure environment variables for database connections if needed.
* Set up persistent storage for your NocoDB data.
* Regularly update your NocoDB instance for the latest features and security patches.

### FreeBSD/FreeNAS/TrueNAS Jail Installation

For detailed instructions on installing NocoDB on FreeBSD, FreeNAS, or TrueNAS Jail, please refer to the [guide](https://gist.github.com/Zamana/e9281d736f9e9ce5882c6f4b140a590e) provided by [C. R. Zamana.](https://github.com/Zamana)

### Sealos

[<img alt="Deploy on Sealos" src={__img10} />](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dnocodb)

### Elestio

[<img alt="Deploy on Elestio" src={__img11} placeholder="blur" />](https://elest.io/open-source/nocodb)

### RepoCloud

[<img alt="Deploy on RepoCloud" src={__img12} placeholder="blur" />](https://repocloud.io/details/?app_id=100)