Data Table API

DataTableClient manages n8n data tables — tables, columns, and rows with filtering and upsert support.

This is one of the most flexible handles in the client. The row methods have typed overloads so the return type changes based on flags like returnType and returnData.

Access

const dataTable = client.dataTables();

Methods

Common Tasks

• create tables for lightweight operational data
• insert rows in batches
• update rows with filters
• upsert one logical record based on a filter
• manage table columns separately from row data

list(params?)

List data tables.

const { data, nextCursor } = await client.dataTables().list({
  limit: 10,
  filter: 'name',
  sortBy: 'createdAt:desc',
});

get(id)

Get a data table by ID.

const table = await client.dataTables().get('dt-123');

create(data)

Create a new data table.

const table = await client.dataTables().create({
  name: 'User Events',
  columns: [
    { name: 'event', type: 'string' },
    { name: 'createdAt', type: 'date' },
  ],
});

Column types supported at creation time: string, number, boolean, date, json. The json type is available when creating columns but may not appear in read responses from the API.

update(id, data)

Update a data table.

const updated = await client.dataTables().update('dt-123', {
  name: 'User Events v2',
});

delete(id)

Delete a data table.

await client.dataTables().delete('dt-123');

Row Operations

listRows(dataTableId, params?)

List rows in a data table.

const { data, nextCursor } = await client.dataTables().listRows('dt-123', {
  filter: 'event=login',
  sortBy: 'timestamp:desc',
  search: 'alice',
});

insertRows(dataTableId, data)

Insert rows into a data table.

const rowIds = await client.dataTables().insertRows('dt-123', {
  data: [
    { event: 'login', createdAt: '2024-01-01T00:00:00Z' },
    { event: 'logout', createdAt: '2024-01-01T01:00:00Z' },
  ],
  returnType: 'id',
});

updateRows(dataTableId, data)

Update rows matching a filter.

const updatedRows = await client.dataTables().updateRows('dt-123', {
  filter: {
    filters: [{ columnName: 'event', condition: 'eq', value: 'login' }],
  },
  data: { event: 'sign_in' },
  returnData: true,
});

upsertRow(dataTableId, data)

Insert or update a single row.

const row = await client.dataTables().upsertRow('dt-123', {
  filter: {
    filters: [{ columnName: 'event', condition: 'eq', value: 'login' }],
  },
  data: { event: 'login', createdAt: '2024-01-01T00:00:00Z' },
  returnData: true,
});

deleteRows(dataTableId, params)

Delete rows matching a filter.

const result = await client.dataTables().deleteRows('dt-123', {
  filter: JSON.stringify({
    type: 'and',
    filters: [{ columnName: 'event', condition: 'eq', value: 'logout' }],
  }),
  returnData: true,
  dryRun: false,
});

Column Operations

listColumns(dataTableId)

List columns in a data table.

const columns = await client.dataTables().listColumns('dt-123');

createColumn(dataTableId, data)

Add a column to a data table.

const column = await client.dataTables().createColumn('dt-123', {
  name: 'user_id',
  type: 'string',
});

updateColumn(dataTableId, columnId, data)

Update a column.

const updated = await client.dataTables().updateColumn('dt-123', 'col-1', {
  name: 'user_identifier',
});

deleteColumn(dataTableId, columnId)

Delete a column.

await client.dataTables().deleteColumn('dt-123', 'col-1');

Return Type Narrowing

Some row operations change their return type based on the request flags:

const count = await client.dataTables().insertRows('dt-123', {
  data: [{ event: 'login' }],
});
// { count: number }

const ids = await client.dataTables().insertRows('dt-123', {
  data: [{ event: 'login' }],
  returnType: 'id',
});
// number[]

DataTableResource

Use getResource(), listResources(), or createResource() to get a bound DataTableResource instance.

const resource = await client.dataTables().getResource('dt-123');
const created = await client.dataTables().createResource({
  name: 'User Events',
  columns: [
    { name: 'event', type: 'string' },
    { name: 'createdAt', type: 'date' },
  ],
});

Properties

Property	Type	Description
id	string	Data table ID
name	string	Data table name

Table methods

Method	Returns	Description
refresh()	this	Re-fetch the table from the API
update(data)	this	Update the table — replaces snapshot with the API response
patch(data)	this	Convenience update — merges partial fields into the current table snapshot before updating
delete()	void	Delete the table

Row methods

Row methods on the resource mirror the corresponding client methods but with the table ID pre-filled.

Method	Returns	Description
listRows(params?)	DataTableRowListResponse	List rows in the table
insertRows(data)	overloads	Insert rows — return type depends on returnType
updateRows(data)	overloads	Update rows matching a filter
upsertRow(data)	overloads	Insert or update a single row
deleteRows(params)	overloads	Delete rows matching a filter

Column methods

Method	Returns	Description
listColumns()	DataTableColumn[]	List columns in the table
createColumn(data)	DataTableColumn	Add a column — patches snapshot to include it
updateColumn(columnId, data)	DataTableColumn	Update a column — replaces matching entry in snapshot
deleteColumn(columnId)	void	Delete a column — removes it from the snapshot

Snapshot management

refresh(), update(), and patch() call replaceSnapshot(). Column methods (createColumn, updateColumn, deleteColumn) call mergeSnapshot() to patch the columns array locally without re-fetching the full table.

Example

const table = await client.dataTables().createResource({
  name: 'Events',
  columns: [{ name: 'event', type: 'string' }],
});

await table.createColumn({ name: 'timestamp', type: 'date' });

const rows = await table.insertRows({
  data: [{ event: 'login' }],
  returnType: 'all',
});

await table.deleteColumn(table.data.columns[0].id);