From 7f0070ce491a32d5fdba30f82da15e8ec620bc12 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Thu, 16 Jul 2026 00:20:30 -0300 Subject: [PATCH 1/2] docs: Explain noReturn write operations --- .../02-database/05-crud.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md b/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md index 980fe720..f2d7745c 100644 --- a/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md +++ b/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md @@ -254,6 +254,32 @@ var companiesDeleted = await Company.db.deleteWhere( The above example will delete any row where the `name` ends in _Ltd_. The `deleteWhere` method returns a `List` of the models deleted, ordered by name in descending order, followed by id in ascending order. +## Skip reading affected rows + +List-returning write methods normally read the affected rows back from the database. Set `noReturn` to `true` when you only need the operation to succeed and do not need those model objects: + +```dart +await Company.db.updateWhere( + session, + columnValues: (t) => [t.name('Archived company')], + where: (t) => t.name.like('% Ltd'), + noReturn: true, +); +``` + +The write still runs with the same filters, conflict handling, transaction, and atomicity guarantees, but the method returns an empty list. Skipping the returned data avoids transferring and deserializing affected rows. This is useful for bulk imports, cleanup jobs, and other writes where you do not need generated IDs, database defaults, updated values, or the affected model objects. + +The `noReturn` parameter is available on these generated methods: + +- `insert`. +- `update` and `updateWhere`. +- `upsert`. +- `delete` and `deleteWhere`. + +It is not available on single-row methods such as `insertRow`, `updateRow`, `upsertRow`, or `deleteRow`, which return the affected row. + +Because the returned list is empty, options that only control the order of returned rows have no observable effect. Ordering can still matter on filtered operations when it determines which rows a `limit` or `offset` selects. + ## Count Count is a special type of query that helps counting the number of rows in the database that matches a specific [filter](./filtering). From 6b48db364261f32b903178579146fc278c5c4f0e Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Tue, 21 Jul 2026 15:33:36 -0300 Subject: [PATCH 2/2] docs: Tighten the noReturn section on the CRUD page Use a section title in line with the other CRUD headings, fold the method list into a sentence instead of one-word bullets, name orderBy explicitly, and match the filter used by the surrounding examples. --- .../02-database/05-crud.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md b/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md index f2d7745c..8ba0f33c 100644 --- a/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md +++ b/docs/06-concepts/03-data-and-the-database/02-database/05-crud.md @@ -254,31 +254,24 @@ var companiesDeleted = await Company.db.deleteWhere( The above example will delete any row where the `name` ends in _Ltd_. The `deleteWhere` method returns a `List` of the models deleted, ordered by name in descending order, followed by id in ascending order. -## Skip reading affected rows +## Skipping returned rows -List-returning write methods normally read the affected rows back from the database. Set `noReturn` to `true` when you only need the operation to succeed and do not need those model objects: +The batch and filtered write methods read the affected rows back from the database and return them as a list. Pass `noReturn: true` when the write itself is all you need. ```dart await Company.db.updateWhere( session, columnValues: (t) => [t.name('Archived company')], - where: (t) => t.name.like('% Ltd'), + where: (t) => t.name.like('%Ltd'), noReturn: true, ); ``` -The write still runs with the same filters, conflict handling, transaction, and atomicity guarantees, but the method returns an empty list. Skipping the returned data avoids transferring and deserializing affected rows. This is useful for bulk imports, cleanup jobs, and other writes where you do not need generated IDs, database defaults, updated values, or the affected model objects. - -The `noReturn` parameter is available on these generated methods: - -- `insert`. -- `update` and `updateWhere`. -- `upsert`. -- `delete` and `deleteWhere`. +The write runs with the same filters, conflict handling, transaction, and atomicity guarantees, but the method returns an empty list instead of reading the rows back. Skipping that read saves transferring and deserializing every affected row, which is worth it for bulk imports, cleanup jobs, and any write where the generated ids, database defaults, and updated values are not used afterwards. -It is not available on single-row methods such as `insertRow`, `updateRow`, `upsertRow`, or `deleteRow`, which return the affected row. +The `noReturn` parameter is available on `insert`, `update`, `updateWhere`, `upsert`, `delete`, and `deleteWhere`. The single-row methods `insertRow`, `updateRow`, `upsertRow`, and `deleteRow` always return the affected row. -Because the returned list is empty, options that only control the order of returned rows have no observable effect. Ordering can still matter on filtered operations when it determines which rows a `limit` or `offset` selects. +Since the result is empty, `orderBy` and `orderByList` have no visible effect on it. They still matter on filtered operations, where they decide which rows a `limit` or `offset` selects. ## Count