NocoDB Connector

A straightforward Actor for interacting with NocoDB databases via the v3 API. Supports full CRUD operations: read records with filtering and pagination, create new records, update existing ones, and delete by ID.

Built in Rust for performance. No browser overhead, no unnecessary dependencies.

What This Does

Connects to any NocoDB instance (self-hosted or cloud) and performs database operations. You provide credentials and specify what you want to do. The Actor handles pagination automatically for large datasets and batches write operations appropriately.

Authentication

You need an API token from your NocoDB instance:

1. Log into NocoDB
2. Go to Settings > API Tokens
3. Create a new token
4. Copy it into the apiToken field

The token is sent as the xc-token header on all requests.

Finding Your Base ID and Table ID

Both IDs are visible in the NocoDB URL when you're viewing a table:

https://app.nocodb.com/dashboard/#/nc/<BASE_ID>/table/<TABLE_ID>

You can also find them in the API documentation panel within NocoDB.

Input Reference

Field	Required	Description
baseUrl	Yes	Your NocoDB instance URL (e.g., https://app.nocodb.com)
apiToken	Yes	API token with appropriate permissions
baseId	Yes	The Base (Project) identifier
tableId	Yes	The Table identifier
mode	Yes	One of: READ, CREATE, UPDATE, DELETE

READ-specific Options

Field	Default	Description
where	—	Filter condition using NocoDB syntax
viewId	—	Fetch from a specific view instead of the base table
fields	—	Array of field names to include in response
sort	—	Array of sort specifications
limit	1000	Maximum records to fetch. Set to 0 for unlimited
pageSize	100	Records per API call. Maximum is 100

WRITE-specific Options

Field	Description
data	JSON object (single record) or array (multiple records)
recordId	For DELETE: single record ID to remove

Usage Examples

Read All Records (with limit)

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "READ",
  "limit": 100
}

Read with Filter

The where parameter uses NocoDB's filter syntax: (FieldName,operator,value)

Common operators: eq (equals), neq (not equals), gt (greater than), lt (less than), like (contains)

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "READ",
  "where": "(Status,eq,Active)",
  "limit": 0
}

Multiple conditions:

{
  "where": "(Status,eq,Active)~and(Price,gt,100)"
}

Read Specific Fields with Sorting

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "READ",
  "fields": ["Name", "Email", "CreatedAt"],
  "sort": ["-CreatedAt", "Name"],
  "limit": 50
}

Prefix field names with - for descending order.

Create Single Record

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "CREATE",
  "data": {
    "Name": "John Smith",
    "Email": "john@example.com",
    "Status": "Active"
  }
}

Create Multiple Records

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "CREATE",
  "data": [
    { "Name": "John Smith", "Email": "john@example.com" },
    { "Name": "Jane Doe", "Email": "jane@example.com" }
  ]
}

Records are created in batches of 25 to respect API limits.

Update Records

Each record must include its Id field:

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "UPDATE",
  "data": [
    { "Id": 1, "Status": "Inactive" },
    { "Id": 2, "Status": "Inactive", "Notes": "Closed account" }
  ]
}

Only fields you include will be modified. Omitted fields remain unchanged.

Delete by Record ID

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "DELETE",
  "recordId": "42"
}

Delete Multiple Records

{
  "baseUrl": "https://app.nocodb.com",
  "apiToken": "xc-abc123...",
  "baseId": "p_xyz789",
  "tableId": "md_def456",
  "mode": "DELETE",
  "data": [1, 2, 3, 4, 5]
}

You can also pass objects with Id fields; the Actor will extract the IDs automatically.

Output

READ Mode

Records are pushed directly to the default dataset. Each record appears as returned by NocoDB, including system fields like Id, CreatedAt, etc.

CREATE, UPDATE, DELETE Modes

Returns an operation result:

{
  "success": true,
  "operation": "create",
  "records_affected": 5
}

On failure:

{
  "success": false,
  "operation": "create",
  "records_affected": 0,
  "error": "API Error (401): Invalid token"
}

Error Handling

The Actor validates inputs before making API calls and provides clear error messages. Common issues:

• 401 Unauthorized: Check your API token
• 404 Not Found: Verify baseId and tableId are correct
• 400 Bad Request: Usually malformed filter syntax or invalid field names

Failed operations still produce output with success: false so you can handle errors programmatically in workflows.

Performance Notes

• Pagination is automatic. For large tables, the Actor fetches pages of records until it reaches your limit or exhausts the data.
• Write operations batch records to avoid hitting rate limits.
• No artificial delays are added. If you're hitting rate limits on a self-hosted instance, adjust your NocoDB configuration.

Limitations

• This Actor uses the NocoDB v3 API. Older NocoDB versions (pre-v3) are not supported. If you need this support, I can implement this easily.
• Linked records and lookup fields are returned as-is from the API. Complex relational queries should be handled via NocoDB views.
• File attachments are returned as URLs; this Actor does not download attachment contents.