Skip to main content

Run bulk operations

Bulk SDK and REST requests reduce round trips when several records need the same kind of operation. Refine creates each record in a separate request and uses a single request for ID-based bulk updates and deletes. Use a bounded batch, keep a stable identifier on every record, and retain the original input so a failed request can be inspected or retried.

The examples use the tasks table from the quickstart. Generate firstTaskId and secondTaskId once in application code and reuse them through the sequence. The REST create example does the same with FIRST_TASK_ID and SECOND_TASK_ID in the current shell.

For Refine, register the provider and sign in. Import useCreateMany, useUpdateMany, and useDeleteMany from @refinedev/core. Place the hooks at the top level of a component beneath <Refine> and invoke mutations from event handlers. Review and confirm the IDs before invoking deletion.

Create several records#

Send an array to the same data resource used to create one record.

await database
  .from('tasks')
  .create([
    {id: firstTaskId, title: 'Prepare release notes', done: false},
    {id: secondTaskId, title: 'Publish release notes', done: false},
  ])
  .execute();

REST and the JavaScript builder return the created records in data. Python's direct create() method returns the created-record list.

Update several records#

Each bulk-update object must include the table's primary key and at least one field to change. The examples use the generated UUID field named id.

await database
  .from('tasks')
  .bulkUpdate([
    {id: firstTaskId, done: true},
    {id: secondTaskId, done: true},
  ])
  .execute();

Bulk update responses place the updated records and their count in data.records and data.count. After the mutation succeeds, read each selected record to verify the updated values.

Delete records by ID#

Prefer ID-based deletion when the application already knows the exact target set.

Review bulk targets
  • Affected resource and cascade: The target is the bounded list of record IDs in the named site, app, and table. Review foreign-key behavior for every selected record.
  • Reversibility: Bulk deletion is permanent.
  • Authorization: Treat authorization as a property of every record; the caller needs the table policy's delete action for the intended scope.
  • Backup or export: Export the selected records and retain the exact ID list when the workflow requires recovery.
  • Confirmation: Compare the site, app, table, ID list, and intended count with the records read immediately before the request.
  • Success response and postcondition: Compare deleted_count with the intended count, then read the IDs again and verify that they are absent.
  • Recovery: This guide documents no bulk undelete. Recreate records only from retained data and re-verify constraints and authorization.
await database
  .from('tasks')
  .bulkDelete([firstTaskId, secondTaskId])
  .execute();

The SDK and REST responses report deleted_count. In Refine, verify deletion by reading the selected IDs again.

Delete records selected by a filter#

Use the filter to select the records, review the complete target set, and save their id values as an application-owned manifest. Submit that manifest through the bulk-delete workflow above in bounded chunks.

If the manifest is too large to collect in one run, pause writes and repeatedly read page 1 after deleting each reviewed chunk. Do not advance to page 2 after deleting page 1: offset-based pages shift as records are removed and can skip targets. An immutable cutoff or a previously captured ID manifest provides the same protection when writes cannot be paused.

This select-review-delete workflow keeps every target visible and authorizes each selected record.

You can also delete every matching record in one request with deleteFiltered() in JavaScript, delete_filtered() in Python, or DELETE …/data/?filter= in REST. It's permanent: run the same filter as a read and compare total first. The request is refused when a condition is empty or when the query also uses search or pagination, and, for callers authorized by app roles, when more than 1,000 records match.

Plan a reliable batch#

  • Choose an explicit batch size of up to 1,000 records. Keep each batch small enough to review, read back, and retry independently.
  • Reuse application-owned UUIDs when reconciling a retry. A repeated create can return a duplicate-key conflict instead of inserting a second row.
  • Validate required fields and field types before sending the batch.
  • Treat authorization as a property of every record, not only the request.
  • Read data.count or deleted_count when exposed and compare it with the intended target count. For Refine, verify every selected ID after the mutation.
  • Split independent work into smaller batches when you need narrower retries or simpler diagnostics.

Next steps#