n8n Data Tables

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/modules/data-table/data-table.service.ts
• packages/@n8n/api-types/src/schemas/data-table.schema.ts
• packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md
• packages/testing/playwright/tests/e2e/data-tables/tables.spec.ts
• packages/testing/playwright/tests/e2e/data-tables/details.spec.ts

n8n Data Tables are flat, internal storage entities designed to provide a workflow-friendly way to store, manage, and retrieve records within the n8n ecosystem. They serve as a predictable alternative to external databases, allowing users to perform operations like inserting, updating, and querying data directly through n8n nodes or specialized management tools. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

The system is integrated into the n8n project structure, appearing in the frontend under "Overview" or specific "Project" views. It supports various data types, schema management, and file imports from formats such as CSV, XLSX, and JSON. Sources: packages/testing/playwright/tests/e2e/data-tables/tables.spec.ts:31-70, packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Core Architecture and Data Management

Data Tables are structured as flat stores containing columns and rows. Every table includes default system columns to track metadata. Sources: packages/testing/playwright/tests/e2e/data-tables/details.spec.ts:140-150

Default System Columns

When a new Data Table is created, it is automatically initialized with the following columns:

• id: A unique identifier for the record.
• createdAt: Timestamp of record creation.
• updatedAt: Timestamp of the last record update.

Sources: packages/testing/playwright/tests/e2e/data-tables/details.spec.ts:148-150, packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Supported Data Types

Data Tables support four primary data types for custom columns. It is recommended to choose string for mixed values or enums to avoid parsing errors. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Type	Use Case
string	Text, IDs, URLs, and mixed values.
number	Integer or float values.
boolean	True/False values.
date	Standardized date formats.

Sources: packages/testing/playwright/tests/e2e/data-tables/details.spec.ts:47-50, packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Schema and Lifecycle Operations

Management of Data Tables involves discovering tables within projects, defining schemas, and performing row-level mutations. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Management Workflow

The lifecycle of a data table operation typically follows a Read-Decide-Write pattern to ensure data integrity and prevent schema mismatches.

The diagram shows the standard procedure for managing tables, prioritizing discovery and schema verification before mutations. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Table Discovery and Projects

Tables can exist within a "Personal" project or be assigned to specific team projects. The system allows filtering tables by projectId to ensure scoped access. Sources: packages/testing/playwright/tests/e2e/data-tables/tables.spec.ts:31-60

Row Operations and Querying

Data Tables support standard CRUD (Create, Read, Update, Delete) operations on rows, often facilitated by the data-tables tool or n8n nodes. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Querying Logic

The query system supports multiple filter operators that can be joined by and or or logic. Query results are typically limited to 100 rows per call to maintain performance.

• Supported Operators: eq, neq, like, gt, gte, lt, lte.
• Pagination: Supported via limit and offset parameters.

Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Row Mutations

Row updates and deletions require specific filters to target data accurately. Destructive actions like delete-rows mandate at least one filter to prevent accidental data loss. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

The sequence illustrates the interaction between the UI and the service during row-level management. Sources: packages/testing/playwright/tests/e2e/data-tables/details.spec.ts:192-230, packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

File Import Procedures

Data can be imported into Data Tables from external files. The process involves parsing the file structure and mapping it to the internal schema. Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

1. Parsing: Uses the parse-file tool to process CSV, TSV, JSON, or XLSX files.
2. Previewing: A preview of the first 20 rows is recommended to verify the schema.
3. Normalization: Column names from the file are normalized (e.g., to snake_case) before being mapped to table columns.
4. Batching: Rows are inserted in batches of at most 100 to optimize resource usage.

Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md

Best Practices for Data Table Design

• Naming Conventions: Use snake_case for column names (e.g., external_id).
• Avoid System Overlaps: Do not name custom columns id or createdAt to avoid conflict with system-generated columns.
• Narrow Schemas: Prefer explicit columns for fields used in workflow logic (filtering/branching) rather than storing large JSON blobs in a single column.
• Formula Handling: Cells starting with =, +, or @ are treated as plain text to prevent formula injection.

Sources: packages/@n8n/instance-ai/skills/data-table-manager/SKILL.md