@lowdefy/docs-content 6.1.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /package/content/{other → actions}/updatesession.md +0 -0
@@ -34,12 +34,15 @@ The `MongoDBCollection` connection sets up a connection to a MongoDB deployment.
34
34
 
35
35
  >Since the connection URI contains authentication secrets, it should be stored using the [`_secret`](operators/secret.md) operator.
36
36
 
37
- When using MongoDBUpdateOne and MongoDBDeleteOne requests, take note that the responses differ if the connection has a log collection.
37
+ When the connection has a `changeLog` collection, all write requests log a change record to that collection. The record contains the request arguments, the request context (`blockId`, `pageId`, `requestId`, `connectionId`, `payload`), a `timestamp`, the request `type`, the connection's `changeLog.meta` value, and either the driver response or `before`/`after` document snapshots (for `MongoDBUpdateOne`, `MongoDBVersionedUpdateOne` and `MongoDBDeleteOne`). The response shape of every request stays the same whether or not a log collection is configured.
38
38
 
39
39
  #### Properties
40
40
  - `databaseUri: string`: __Required__ - Connection uri string for the MongoDb deployment. Should be stored using the [_secret](operators/secret.md) operator.
41
41
  - `databaseName: string`: Default: Database specified in connection string - The name of the database in the MongoDB deployment.
42
42
  - `collection: string`: __Required__ - The name of the MongoDB collection.
43
+ - `changeLog: object`: Log all changes made by write requests to a log collection.
44
+ - `collection: string`: __Required__ - The name of the collection change log records are written to.
45
+ - `meta: object`: Additional data to include in every change log record, for example the user making the change.
43
46
  - `read: boolean`: Default: `true` - Allow read operations like find on the collection.
44
47
  - `write: boolean`: Default: `false` - Allow write operations like update on the collection.
45
48
  - `options: object`: See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/interfaces/mongoclientoptions.html) for more information.
@@ -103,12 +106,20 @@ Request types:
103
106
  - MongoDBBulkWrite
104
107
  - MongoDBDeleteMany
105
108
  - MongoDBDeleteOne
109
+ - MongoDBEnrichmentClaim
110
+ - MongoDBEnrichmentComplete
111
+ - MongoDBEnrichmentEnqueue
106
112
  - MongoDBFind
107
113
  - MongoDBFindOne
114
+ - MongoDBInsertConsecutiveId
108
115
  - MongoDBInsertMany
116
+ - MongoDBInsertManyConsecutiveIds
109
117
  - MongoDBInsertOne
118
+ - MongoDBTableChanges
119
+ - MongoDBTableQuery
110
120
  - MongoDBUpdateMany
111
121
  - MongoDBUpdateOne
122
+ - MongoDBVersionedUpdateOne
112
123
 
113
124
 
114
125
  ### MongoDBAggregation
@@ -291,7 +302,7 @@ requests:
291
302
  ### MongoDBDeleteOne
292
303
 
293
304
  The `MongoDBDeleteOne` request deletes a single document in the collection specified in the connectionId. It requires a filter, which is written in the query syntax, to select a document to delete. It will delete the first document that matches the filter.
294
- > MongoDBDeleteOne response differs when the connection has a log collection. When a log collection is set on the connection, a findOneAndDelete operation is performed compared to the standard deleteOne operation.
305
+ > When the connection has a log collection, a findOneAndDelete operation is performed instead of the standard deleteOne operation so the deleted document can be captured in the change log. The response shape is the same in both cases.
295
306
 
296
307
  #### Properties
297
308
  - `filter: object`: __Required__ - The filter used to select the document to update.
@@ -334,6 +345,359 @@ requests:
334
345
  _payload: selected_id
335
346
  ```
336
347
 
348
+ ### Enrichment run queue
349
+
350
+ Three requests run the enrichment columns of a `Table`: columns whose cells are computed per row by a provider (an API endpoint of the app) or an AI prompt, from the values of other columns. `MongoDBEnrichmentEnqueue` marks cells queued, `MongoDBEnrichmentClaim` hands a worker a batch of queued cells, and `MongoDBEnrichmentComplete` writes the worker's results. There is no queue collection: each cell's run state is stored in its row, under `_enrich.<column key>`, next to the row's data.
351
+
352
+ ```yaml
353
+ _enrich:
354
+ email: # the column key
355
+ status: ok # queued | running | ok | error | empty
356
+ value: ada@acme.test # the result the column shows (its field is _enrich.email.value)
357
+ raw: { ... } # the provider's response, for the details panel
358
+ error: null # the message, with status error (or the last failed attempt, while queued again)
359
+ inputHash: 0659b6fcca796a # the hash of the inputs the value was computed from
360
+ runId: 66f9… # the enqueue that queued the cell
361
+ attempts: 1
362
+ claimToken: … # the claim of the worker that ran it
363
+ queuedAt, startedAt, finishedAt, leaseUntil
364
+ waitingFor: [company] # while queued behind the enrichment columns it reads
365
+ ```
366
+
367
+ A cell moves from `queued` to `running` (claimed by a worker, with a lease) to `ok`, `empty` (the provider found nothing) or `error`. A failed attempt goes back to `queued` after a backoff until `maxAttempts`. While a cell is queued or running again, its previous `value`, `raw` and `inputHash` stay, so the table keeps showing the old value until a new result lands.
368
+
369
+ The three requests take the table's columns as `columnDefs`, the declared and user-defined columns merged, as the app passes them to the `Table` (a Table columns list can be passed as it is). Enrichment and ai columns run; other columns are only looked up by key:
370
+
371
+ ```yaml
372
+ - key: email
373
+ kind: enrichment # or ai
374
+ provider: finder # the worker calls the endpoint enrich_finder; ai columns default to ai
375
+ inputs:
376
+ domain: { column: domain } # another column's value; required unless required: false
377
+ country: { value: ZA } # a literal value
378
+ autoRun: true # run when an input column completes
379
+ - key: pitch
380
+ kind: ai # provider defaults to ai (the enrich_ai endpoint)
381
+ prompt: Write a two line pitch for {{ name }}
382
+ inputs:
383
+ name: { column: name } # list every column the prompt uses
384
+ email: { column: email } # an enrichment column: its value, once its cell is ok
385
+ output: { type: tag, options: [Hot, Warm, Cold] } # text, number, boolean, tag or tags
386
+ ```
387
+
388
+ >Read the columns on the server, never from the browser. A request payload is whatever the browser sends: an endpoint that passes `_payload: columnDefs` to these requests lets any user run any column config (another provider, other inputs, another prompt) against the rows the filter allows. Build `columnDefs` in the endpoint from your declared columns and the stored user columns, as the examples below do, and check user columns when they are saved.
389
+
390
+ >AI prompts and formula templates are user content: they only take `{{ column }}` placeholders, filled in as plain text. Never render a prompt with a template engine (`_nunjucks` or a `_js` template) on the server: a template can run code. The `Table` refuses prompts and formulas with tags (`{% %}`), comments (`{# #}`) or expressions (`{{ a | upper }}`); check the same when you save a user column.
391
+
392
+ A `{ column }` input reads another enrichment or ai column's value (only when that cell is `ok`; while it is queued or running, the cell waits for it: it is queued with `waitingFor`, out of claims until that cell finishes), or a field of `fields`, the table's `MongoDBTableQuery` fields keyed by column key, at its `path`. A column outside both is refused, so a user-defined column can never send a field the table does not list to a provider. A required input that is `null`, missing or `''` sets the cell to `empty` with `error: Missing input: <column>` instead of running it. A chain of inputs that comes back to a column is refused, since `autoRun` would run it forever.
393
+
394
+ The browser never sends MongoDB syntax, and the requests only ever write the cell properties above, under `_enrich.<column key>` of an enrichment or ai column of `columnDefs` (column keys are 1 to 128 letters, digits, `_` or `-`). Every read and write is scoped by the base `filter` (required unless the connection is tenant-scoped; `filter: {}` for every document) and, on a tenant connection, by the tenant; the `filter` may not name `_enrich`. No request runs JavaScript on the database server.
395
+
396
+ ##### Input hash
397
+
398
+ `inputHash` is the hash of a cell's inputs, `{ [param]: value }` with optional inputs that have no value left out: [cyrb53](https://github.com/bryc/code/blob/master/jshash/experimental/cyrb53.js) (seed 0) of the canonical JSON of the inputs, as 14 lowercase hex digits. The canonical JSON has object keys sorted at every depth, no whitespace, dates as ISO strings, ObjectIds as hex strings and undefined values left out. The `Table` computes the same hash in the browser, so a cell whose row's inputs changed since its value was computed shows as stale, and `mode: stale` re-runs exactly those cells. A claim hashes the inputs it gives the worker, and the result is stored with that hash.
399
+
400
+ ##### Columns and fields on the server
401
+
402
+ Every endpoint that runs these requests reads the table's columns itself, with a request or step (declared columns merged with the stored user columns), and builds `fields` the same way: the declared `MongoDBTableQuery` fields, plus one field per user-defined input column. The recommended layout keeps what users type under `values.<key>` (set the Table's `inputFieldPrefix: values`), so a user column can never name, read or write another field of the row:
403
+
404
+ ```yaml
405
+ # leads/load_table.yaml, referenced by every enrichment endpoint
406
+ - id: load_columns
407
+ type: MongoDBAggregation
408
+ connectionId: table_columns
409
+ properties:
410
+ pipeline:
411
+ - $match: { tableId: leads }
412
+ - $sort: { position: 1 }
413
+ - :set_state:
414
+ columnDefs:
415
+ _array.concat:
416
+ - _ref: leads/columns.yaml # the declared columns
417
+ - _step: load_columns # the user columns, as stored
418
+ fields:
419
+ _js:
420
+ fn: |
421
+ const fields = { ...args.declared };
422
+ args.columns
423
+ .filter((column) => column.userDefined === true && column.kind === 'input')
424
+ .forEach((column) => {
425
+ fields[column.key] = { type: column.type ?? 'text', path: `values.${column.key}` };
426
+ });
427
+ return fields;
428
+ args:
429
+ declared:
430
+ _ref: leads/fields.yaml # the declared MongoDBTableQuery fields
431
+ columns:
432
+ _step: load_columns
433
+ ```
434
+
435
+ `columnDefs` and `fields` may come from any operator (`_state`, `_step`, `_payload` for data you checked); the requests validate them each time they run.
436
+
437
+ ##### The worker
438
+
439
+ The worker is an API endpoint: it claims a batch of cells, calls each cell's provider endpoint with `:parallel_for` (`:concurrency` limits how many run at once), and completes each cell. Complete queues the `autoRun` columns a completed cell feeds (a waterfall between columns) and releases the cells waiting for it, so a later round runs them. It loops until a claim returns nothing, or for at most ten rounds. A schedule runs it every minute, and the endpoint that enqueues a run starts it at once with a detached call. A worker that crashes loses nothing: its cells are claimed again when their lease runs out, and a result from a worker whose lease ran out is ignored.
440
+
441
+ ```yaml
442
+ api:
443
+ - id: enrichment_worker
444
+ type: InternalApi
445
+ schedules:
446
+ - cron: '* * * * *'
447
+ routine:
448
+ - _ref: leads/load_table.yaml # columnDefs and fields, read on the server
449
+ - :set_state:
450
+ claimed: 1
451
+ rounds: 0
452
+ - :while:
453
+ _and:
454
+ - _gt: [{ _state: claimed }, 0]
455
+ - _lt: [{ _state: rounds }, 10]
456
+ :do:
457
+ - id: claim
458
+ type: MongoDBEnrichmentClaim
459
+ connectionId: leads
460
+ properties:
461
+ filter: {} # cells were scoped when they were queued
462
+ fields:
463
+ _state: fields
464
+ columnDefs:
465
+ _state: columnDefs
466
+ limit: 20
467
+ - :parallel_for: cell
468
+ :in:
469
+ _step: claim
470
+ :concurrency: 5 # at most five provider calls at once
471
+ :do:
472
+ - :try:
473
+ - id: call_provider
474
+ type: CallApi
475
+ properties:
476
+ endpointId:
477
+ _string.concat: [enrich_, { _item: cell.provider }]
478
+ payload:
479
+ inputs:
480
+ _item: cell.inputs
481
+ prompt:
482
+ _item: cell.prompt # ai columns
483
+ output:
484
+ _item: cell.output # the column's output config
485
+ - id: complete
486
+ type: MongoDBEnrichmentComplete
487
+ connectionId: leads
488
+ properties:
489
+ filter: {}
490
+ columnDefs:
491
+ _state: columnDefs
492
+ results:
493
+ # The claim's cell, with the provider's answer merged in:
494
+ # { status, value, raw } or { status, error, retry }.
495
+ - _object.assign:
496
+ - rowKey:
497
+ _item: cell.rowKey
498
+ columnKey:
499
+ _item: cell.columnKey
500
+ claimToken:
501
+ _item: cell.claimToken
502
+ - _step: call_provider.$
503
+ :catch:
504
+ - id: complete_error
505
+ type: MongoDBEnrichmentComplete
506
+ connectionId: leads
507
+ properties:
508
+ filter: {}
509
+ columnDefs:
510
+ _state: columnDefs
511
+ results:
512
+ - rowKey:
513
+ _item: cell.rowKey
514
+ columnKey:
515
+ _item: cell.columnKey
516
+ claimToken:
517
+ _item: cell.claimToken
518
+ status: error
519
+ error:
520
+ _error: message
521
+ - :set_state:
522
+ claimed:
523
+ _array.length:
524
+ _step: claim
525
+ rounds:
526
+ _sum: [{ _state: rounds }, 1]
527
+ ```
528
+
529
+ A request or service error a `:catch` handles is logged at debug, so a provider that fails on purpose (a 404 in a waterfall) does not fill the log with errors. Config, operator and internal errors are still logged as errors, with their config location, even when a `:catch` handles them.
530
+
531
+ Each provider endpoint `enrich_<provider id>` takes `{ inputs, prompt, output }` and returns `{ status: ok | empty, value, raw }`, or `{ status: error, error, retry: false }` for a final failure; throwing is a failed attempt that is retried. `null` for `error` or `retry` (what `_step` gives for a key the provider did not return) is the same as leaving it out. The app declares these endpoints, so a column can only call what the app exposes, and API keys stay on the server. For a concurrency per provider, group the claimed cells by `provider` and run each group with its own `:concurrency`, or run a worker per provider with `providers` on the claim.
532
+
533
+ The AI provider (`enrich_ai`) fills the prompt's `{{ input }}` and `{{ input.path }}` placeholders (a dot path reads into the input's value, the pattern the Table accepts) with the cell's inputs by plain string replacement, in one pass, so a row value that looks like a template stays text, and asks the model for an answer of the column's `output.type`.
534
+
535
+ The endpoint the table's run events call queues the cells, then starts the worker without waiting for it (a detached call needs the `CRON_SECRET` environment variable):
536
+
537
+ ```yaml
538
+ api:
539
+ - id: run_enrichment
540
+ type: Api
541
+ routine:
542
+ - _ref: leads/load_table.yaml
543
+ - id: enqueue
544
+ type: MongoDBEnrichmentEnqueue
545
+ connectionId: leads
546
+ properties:
547
+ filter:
548
+ org_id:
549
+ _user: organization.id
550
+ fields:
551
+ _state: fields
552
+ columnDefs:
553
+ _state: columnDefs # read on the server, never _payload
554
+ columns:
555
+ _payload: columns
556
+ mode:
557
+ _payload: mode
558
+ selection:
559
+ _payload: selection
560
+ user:
561
+ _user: true
562
+ - id: start_worker
563
+ type: CallApi
564
+ properties:
565
+ endpointId: enrichment_worker
566
+ detached: true
567
+ - :return:
568
+ _step: enqueue
569
+ ```
570
+
571
+ A claim reads the oldest due cells of each column. On a large table, index each enrichment column's queue fields, for example `{ "_enrich.email.status": 1, "_enrich.email.queuedAt": 1 }`, with the base filter fields first when every run is scoped by them.
572
+
573
+ ### MongoDBEnrichmentClaim
574
+
575
+ The `MongoDBEnrichmentClaim` request claims up to `limit` enrichment cells for a worker: the oldest cells that are queued and due (`queuedAt` passed, so a retry waits out its backoff), and running cells whose lease ran out. Each claimed cell is set to `running` with `startedAt`, `leaseUntil` (now plus `leaseMs`), `attempts` plus one and a new random `claimToken`. See [Enrichment run queue](#enrichment-run-queue).
576
+
577
+ Each claim carries the column config the worker needs (`kind`, `title`, `provider`, `prompt`, `output`), so the worker never looks the column up again.
578
+
579
+ Concurrent workers never claim the same cell. Every claim is a compare-and-set: the write matches the cell only in the state the claim read (its status, token, attempts and run) and while it is still claimable, so when two workers read the same cell, only the first write changes it. A worker that lost cells to another reads further candidates, up to five rounds, so it does not stop while cells are still queued.
580
+
581
+ A claim also settles cells it can not hand out: a cell whose required input is now missing is set to `empty` with the missing column named, a cell whose enrichment input is queued or running again waits for it (queued with `waitingFor`, released when that input finishes), and a running cell whose lease ran out on its last attempt (`maxAttempts`) becomes an `error`. A cell a claim sets to `empty` or `error` releases the cells waiting for it, as a final result does.
582
+
583
+ ##### Response
584
+
585
+ ```yaml
586
+ - rowKey: 66f9… # the row key (rowKeyField)
587
+ columnKey: email
588
+ kind: enrichment # or ai
589
+ title: Email # when the column has one
590
+ provider: finder # ai columns: ai unless they name another
591
+ prompt: … # ai columns
592
+ output: email # when set: the enrichment result path, or the ai answer's { type, options? }
593
+ runId: 66f9…
594
+ claimToken: 3b1f…:0659b6fcca796a
595
+ attempt: 1
596
+ inputHash: 0659b6fcca796a
597
+ inputs: # resolved from columnDefs
598
+ domain: acme.test
599
+ row: # _id, the row key and the fields paths only
600
+ _id: …
601
+ name: Acme
602
+ domain: acme.test
603
+ ```
604
+
605
+ #### Properties
606
+ - `columnDefs: object[]`: __Required__ - The table columns, declared and user-defined merged. See [Enrichment run queue](#enrichment-run-queue).
607
+ - `fields: object`: __Required__ - The table's `MongoDBTableQuery` fields, keyed by column key: the fields column inputs read and claimed rows return.
608
+ - `columns: string[]`: Claim only cells of these enrichment or ai columns. Defaults to every enrichment and ai column.
609
+ - `providers: string[]`: Claim only cells of columns that use these providers, for a worker per provider.
610
+ - `filter: object`: The base filter every read and write is scoped by. Required unless the connection is tenant-scoped. Set it to `{}` to claim cells of every document.
611
+ - `limit: integer`: Default: `20` - The most cells one claim returns, at most 200.
612
+ - `leaseMs: integer`: Default: `120000` - How long a claimed cell stays with its worker. After it, the cell can be claimed again, and the first worker's result is ignored. Keep it longer than a provider call, and keep the servers' clocks in sync.
613
+ - `maxAttempts: integer`: Default: `3` - A cell whose lease ran out on this attempt becomes an error instead of being claimed again. Use the same value as `MongoDBEnrichmentComplete`.
614
+ - `rowKeyField: string`: Default: `_id` - The document field returned as `rowKey`.
615
+
616
+ ### MongoDBEnrichmentComplete
617
+
618
+ The `MongoDBEnrichmentComplete` request writes a worker's results to the cells it claimed. A result is applied only while its cell still holds the claim, its `claimToken` with status `running`, so a worker whose lease ran out (and whose cell was claimed again or queued again since) changes nothing, and a result sent twice is applied once. See [Enrichment run queue](#enrichment-run-queue).
619
+
620
+ - `ok` and `empty` results replace the cell's `value` and `raw` (an empty result has no value), and store `finishedAt` and the `inputHash` of the inputs the claim gave the worker.
621
+ - An `error` below `maxAttempts` goes back to `queued` with its error message, due after `backoffMs * 2^(attempt - 1)` (30 seconds, then 60, …, at most a day), or after the result's `retryAfterMs` when the provider said how long to wait (a rate limit's `Retry-After`). On the last attempt, or with `retry: false`, the error is final. The previous value stays in both cases.
622
+ - A final result (`ok`, `empty`, or an error that is not retried) releases the cells of the row waiting for it (`waitingFor`), so they are claimed next; one whose input failed then finds it missing.
623
+ - An `ok` result queues the `autoRun` columns that read the column, in its row, unless they are queued or running already.
624
+ - A `raw` larger than `rawMaxBytes` is stored as `{ _truncated: true, bytes, maxBytes, preview }`, with the first 1000 characters of its JSON, so one large response can not fill the row. A `value` larger than `rawMaxBytes` makes the result a final error.
625
+
626
+ ##### Response
627
+
628
+ ```yaml
629
+ applied: 18 # results written
630
+ ignored: 2 # results whose claim no cell holds any more
631
+ requeued: 1 # errors queued again for a retry
632
+ released: 4 # waiting cells released by the results
633
+ downstream: # autoRun columns that read a column that just completed ok, now queued
634
+ - rowKey: 66f9…
635
+ columns: [pitch]
636
+ ```
637
+
638
+ The `downstream` columns are already queued: the worker's next claim runs them.
639
+
640
+ #### Properties
641
+ - `results: object[]`: __Required__ - At most 1000 results, each:
642
+ - `rowKey: any`: __Required__ - The `rowKey` of the claim.
643
+ - `columnKey: string`: __Required__ - The `columnKey` of the claim.
644
+ - `claimToken: string`: __Required__ - The `claimToken` of the claim.
645
+ - `status: enum`: __Required__ - `ok`, `empty` (no result) or `error`.
646
+ - `value: any`: The result the column shows.
647
+ - `raw: any`: The provider's response.
648
+ - `cost: integer`: What the provider call behind the result cost, in micro-USD, such as a [`TregCall`](/Treg) `cost.micro`. Stored as the cell's `cost` with any status; a result without a cost leaves the cell's cost as it was.
649
+ - `error: string | null`: The error message, with status `error`. `null` is the same as leaving it out.
650
+ - `retry: boolean | null`: Default: `true` - With status `error`, `false` makes the error final. `null` is the same as leaving it out.
651
+ - `retryAfterMs: integer | null`: With status `error` below `maxAttempts`, the wait before the cell is claimed again, in place of the exponential backoff, at most a day. A worker passes a `ServiceError`'s `retryAfter` (seconds, such as a [`TregCall`](/Treg) 429 or 503) times 1000. `null` is the same as leaving it out.
652
+ - `columnDefs: object[]`: __Required__ - The table columns, declared and user-defined merged.
653
+ - `filter: object`: The base filter every read and write is scoped by. Required unless the connection is tenant-scoped.
654
+ - `maxAttempts: integer`: Default: `3` - The attempts a cell gets.
655
+ - `backoffMs: integer`: Default: `30000` - The wait before a failed cell is claimed again, doubled per attempt made.
656
+ - `rawMaxBytes: integer`: Default: `65536` - The largest raw response (BSON bytes) stored as it is.
657
+ - `rowKeyField: string`: Default: `_id` - The document field a row key matches.
658
+ - `rowKeyType: enum`: Default: `auto` - How row keys are read, as for `MongoDBTableChanges`.
659
+
660
+ ### MongoDBEnrichmentEnqueue
661
+
662
+ The `MongoDBEnrichmentEnqueue` request queues cells of enrichment columns: the cells of `columns` in the selected rows that `mode` names. See [Enrichment run queue](#enrichment-run-queue).
663
+
664
+ - `all`: every cell that is not queued, or running with a live lease. A run in progress is never restarted, whatever the mode.
665
+ - `empty`: cells never run, or whose last result was empty.
666
+ - `errors`: cells that failed.
667
+ - `stale`: cells with a result whose inputs changed since it was computed. The request reads each candidate row's inputs (in batches of 1000 rows, with only the input paths projected) and compares their hash with the cell's `inputHash`.
668
+
669
+ A queued cell gets `status: queued`, the `runId`, `queuedAt` and `attempts: 0`; its previous value, raw and inputHash stay until a new result lands. A cell whose required input has no value is set to `empty` with `error: Missing input: <column>` instead, and its previous result is cleared.
670
+
671
+ Columns can run together with the columns they read: the request plans them upstream first, and a cell whose required enrichment input is queued in the same call (or is queued or running already) is queued with `waitingFor: [<column>]`, out of claims until that input finishes, never `Missing input`. So one call can run `[email, pitch]` where the pitch reads the email.
672
+
673
+ `selection` is the table's `selected` value: row keys, or `{ all: true, except, filter, search }`, compiled against `fields` like `MongoDBTableChanges` compiles it, with the same limits. Leave it out to run every row inside the base `filter`. Row keys are read as in `MongoDBTableChanges` Row keys: an ObjectId as `{ _oid }` or its Table key text, and a numeric key as the number or its text.
674
+
675
+ The cells are written as unordered bulkWrites of 1000 cells, each write guarded by the mode's condition, so a cell a worker took since it was read is left alone. When more than `maxCells` cells would be written, nothing is written and the request throws, so a large run can be confirmed first.
676
+
677
+ ##### Response
678
+
679
+ ```yaml
680
+ queued: 2400 # cells queued, those waiting for an input column included
681
+ skipped: 12 # selected cells the mode left alone (live, fresh or not matching)
682
+ missingInputs: 3 # cells set to empty for a missing input
683
+ runId: 66f9…
684
+ ```
685
+
686
+ #### Properties
687
+ - `columns: string[]`: __Required__ - The keys of the enrichment or ai columns to run.
688
+ - `columnDefs: object[]`: __Required__ - The table columns, declared and user-defined merged.
689
+ - `fields: object`: __Required__ - The table's `MongoDBTableQuery` fields, keyed by column key: the fields column inputs read and a select-all selection is compiled against.
690
+ - `selection: object | any[]`: The rows to run, the `Table` `selected` value. Defaults to every row inside `filter`.
691
+ - `mode: enum`: Default: `all` - `all`, `empty`, `errors` or `stale`.
692
+ - `filter: object`: The base filter every read and write is scoped by, for example `{ org_id: { _user: organization.id } }`. Required unless the connection is tenant-scoped. Set it to `{}` to run on every document.
693
+ - `maxCells: integer`: Default: `10000` - The most cells one enqueue may write, queued and missing input cells together.
694
+ - `maxTimeMS: integer`: Default: `30000` - The time limit of each read.
695
+ - `runId: string`: The `runId` the queued cells get, 1 to 64 letters, digits, `_` or `-`. Generated when left out.
696
+ - `user: object`: The user that `{ $user: path }` values in a selection filter resolve from. Set it to `{ _user: true }`.
697
+ - `timezone: string`: Default: `UTC` - The IANA time zone whose days the date filters of a selection compare.
698
+ - `rowKeyField: string`: Default: `_id` - The document field a row key matches.
699
+ - `rowKeyType: enum`: Default: `auto` - How row keys are read, as for `MongoDBTableChanges`.
700
+
337
701
  ### MongoDBFind
338
702
 
339
703
  The `MongoDBFind` request executes a MongoDB [query](https://docs.mongodb.com/manual/tutorial/query-documents/) on the collection specified in the connectionId. It returns the array of documents returned by the query.
@@ -465,6 +829,34 @@ requests:
465
829
  _payload: _id
466
830
  ```
467
831
 
832
+ ### MongoDBInsertConsecutiveId
833
+
834
+ The `MongoDBInsertConsecutiveId` request inserts a single document into the collection specified in the connectionId, assigning a sequential, human-readable `_id` like `INV0001`. The id is built from a prefix and the next consecutive number for that prefix, zero-padded to `length` digits. The id read and the insert run inside a transaction so concurrent requests cannot claim the same id.
835
+
836
+ > Transactions require MongoDB to run as a replica set. Standalone deployments are not supported by this request.
837
+
838
+ #### Properties
839
+ - `doc: object`: __Required__ - The document to be inserted. The `_id` is assigned by the request.
840
+ - `prefix: string`: __Required__ - Prefix to add to the id, for example `INV`.
841
+ - `length: number`: The numeric part of the id is zero-padded to this number of digits. If omitted, the number is not padded.
842
+ - `options: object`: Optional settings passed to the insert. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#insertone) for more information.
843
+
844
+ #### Examples
845
+
846
+ ###### Insert an invoice with a sequential id (INV0001, INV0002, ...):
847
+ ```yaml
848
+ requests:
849
+ - id: insert_invoice
850
+ type: MongoDBInsertConsecutiveId
851
+ connectionId: my_mongodb_collection_id
852
+ properties:
853
+ prefix: INV
854
+ length: 4
855
+ doc:
856
+ amount:
857
+ _state: amount
858
+ ```
859
+
468
860
  ### MongoDBInsertMany
469
861
 
470
862
  The `MongoDBInsertMany` request inserts an array of documents into the collection specified in the connectionId. If a `_id` field is not specified on a document, a MongoDB `ObjectID` will be generated.
@@ -512,6 +904,33 @@ requests:
512
904
 
513
905
  ```
514
906
 
907
+ ### MongoDBInsertManyConsecutiveIds
908
+
909
+ The `MongoDBInsertManyConsecutiveIds` request inserts an array of documents into the collection specified in the connectionId, assigning each document a sequential, human-readable `_id` like `INV0001`. Ids continue from the highest existing id for the prefix. The id read and the insert run inside a transaction so concurrent requests cannot claim the same ids.
910
+
911
+ > Transactions require MongoDB to run as a replica set. Standalone deployments are not supported by this request.
912
+
913
+ #### Properties
914
+ - `docs: object[]`: __Required__ - The documents to be inserted. The `_id` values are assigned by the request.
915
+ - `prefix: string`: __Required__ - Prefix to add to the ids, for example `INV`.
916
+ - `length: number`: The numeric part of each id is zero-padded to this number of digits. If omitted, the numbers are not padded.
917
+ - `options: object`: Optional settings passed to the insert. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#insertmany) for more information.
918
+
919
+ #### Examples
920
+
921
+ ###### Insert order lines with sequential ids:
922
+ ```yaml
923
+ requests:
924
+ - id: insert_order_lines
925
+ type: MongoDBInsertManyConsecutiveIds
926
+ connectionId: my_mongodb_collection_id
927
+ properties:
928
+ prefix: LINE
929
+ length: 6
930
+ docs:
931
+ _state: order_lines
932
+ ```
933
+
515
934
  ### MongoDBInsertOne
516
935
 
517
936
  The `MongoDBInsertOne` request inserts a document into the collection specified in the connectionId. If a `_id` field is not specified, a MongoDB `ObjectID` will be generated.
@@ -560,6 +979,539 @@ requests:
560
979
  _date: now
561
980
  ```
562
981
 
982
+ ### MongoDBTableChanges
983
+
984
+ The `MongoDBTableChanges` request saves the value of a `TableInput` block. The value of a `TableInput` is not its rows but a changeset: only what changed since `data`. The request validates the changeset against an allowlist of `fields` and compiles it to one `bulkWrite` on the server. The browser never sends MongoDB syntax: keys that are not in `fields`, keys that start with `$` (operators such as `$where`, positional paths such as `items.$[x]`), values of the wrong type, and operator objects such as `{ $ne: null }` as values or row keys are refused before anything is written.
985
+
986
+ The changeset is the `TableInput` value:
987
+
988
+ ```yaml
989
+ updated: # changed fields of existing rows: { [rowKey]: { [field]: value } }
990
+ flour:
991
+ qty: 450 # the key is the column field, a dot path
992
+ details.note: strong
993
+ added: # new rows: [{ rowKey, ...fields }]
994
+ - rowKey: 3f2c9a61-… # a temporary key the browser generated
995
+ ingredient: Yeast
996
+ qty: 7
997
+ removed: # existing rows to delete: [rowKey]
998
+ - salt
999
+ moved: # with rowDrag.positionField: { [rowKey]: position }
1000
+ water: 1536
1001
+ order: [salt, flour] # with rowDrag and no positionField: every row key in the new order
1002
+ ```
1003
+
1004
+ The `fields` keys are the column `field` dot paths, because those are the keys of the changeset, and only those fields can be written (at their `path`). This differs from `MongoDBTableQuery`, whose `fields` are keyed by the column `key`: a `TableInput` column `{ key: owner, field: owner.name }` is `owner.name` here and `owner` (with `path: owner.name`) in `MongoDBTableQuery`. A changeset key that is the `path` of a field keyed otherwise is refused with an error that names the mismatch. Values are coerced to the field type like `MongoDBTableQuery` values: numbers from numeric strings, dates from date strings and timestamps, and `null` clears a value of any type. `avatar`, `image` and `json` fields accept documents, but not with keys that start with `$`.
1005
+
1006
+ Every operation is scoped by the base `filter`, for example the organization or owner of the rows. The row key is combined with the filter using `$and`, so it can only narrow it. `filter` is required, unless the connection is tenant-scoped: then the tenant is merged into every operation and stamped on new rows, as for `MongoDBBulkWrite`. Set `filter: {}` to allow writes to every document in the collection.
1007
+
1008
+ ##### Scope fields
1009
+
1010
+ The `filter` and `insertDefaults` fields are the scope of the rows, such as their organization or owner, and the table can never write them:
1011
+
1012
+ - A field (or the `positionField`) whose path is a `filter` field, or inside or over one, is refused (with a `filter` on `owner.id`, the fields `owner.id`, `owner` and `owner.id.name` are all refused). Otherwise an update could move a row out of scope. This includes fields named inside `$and`, `$or` and `$nor`.
1013
+ - A field whose path is set by `insertDefaults`, or inside or over one of its values, is refused, so a new row can not replace a default. A default `{ address: { country: FR } }` still leaves `address.city` writable. For a starting value the user may change, give the `TableInput` column a default instead.
1014
+ - New rows are stamped with the equality conditions of the `filter`: `{ org_id: X }`, `{ org_id: { $eq: X } }` and the equalities inside `$and`. A row added with a `filter` of `{ org_id: { _user: organization.id } }` belongs to that organization without an `insertDefaults` entry. `insertDefaults` may repeat such a value, but a different value is refused.
1015
+ - Any other `filter` condition (`$ne`, `$in`, a regex, the clauses of `$or`) can not be stamped. A save that adds rows then needs that field set by `insertDefaults`. A `filter` with an operator such as `$expr` or `$where` refuses added rows. Saves that only update, move or remove rows are not affected.
1016
+
1017
+ In array mode the `filter` scopes the document: every operation, the `$push` of new items included, matches only the document with `array.documentId` inside the `filter`. Item fields are compared with the `filter` at their path in the document (`items.<field>`), and new items are not stamped, since they are not documents of the collection.
1018
+
1019
+ ##### Collection mode
1020
+
1021
+ By default every row is a document, matched by `rowKeyField` (default `_id`). The changeset compiles to:
1022
+
1023
+ ```yaml
1024
+ - deleteOne: { filter: { $and: [<filter>, { _id: <key> }] } } # one per removed row
1025
+ - updateOne: # one per updated or moved row
1026
+ filter: { $and: [<filter>, { _id: <key> }] }
1027
+ update: { $set: { qty: 450, details.note: strong, position: 1536 } } # its fields and position in one $set
1028
+ - insertOne: { document: { <insertDefaults>, <row fields>, _id: <new ObjectId> } } # one per added row
1029
+ ```
1030
+
1031
+ An update sets only the changed dot paths, so the rest of the document is kept. A move writes one position field on one row. An `order` needs a `positionField` in collection mode: it writes positions 1024, 2048, … to every row in the order.
1032
+
1033
+ ##### Array mode
1034
+
1035
+ With `array: { documentId, path }`, the rows are the items of an embedded array in one document, such as the ingredients of a recipe. Every operation matches that document inside the base filter, and field paths and `positionField` are paths in the item. MongoDB can not `$set` into, `$pull` from and `$push` to the same array in one update, so the changeset compiles to up to four updates of that document, run in order:
1036
+
1037
+ ```yaml
1038
+ - $set: { items.$[r0].qty: 450, items.$[r1].position: 1536 } # arrayFilters: [{ r0._id: flour }, { r1._id: water }]
1039
+ - $pull: { items: { _id: { $in: [salt] } } }
1040
+ - $push: { items: { $each: [<new items>] } }
1041
+ - <a pipeline update that puts the items in the order of "order"> # only for an order without a positionField
1042
+ ```
1043
+
1044
+ New items get a generated ObjectId `_id` when `itemKeyField` is `_id`. Without a `positionField`, the array order is the row order, and an `order` is applied by a pipeline update that reorders the items on the server, as the array is when the update runs. Items are moved, never rewritten, so an edit someone else saved to an item in the meantime is kept; items the order does not name (added since the table loaded) follow in their current order, and keys of items that are gone are skipped. Setting the whole array from the browser's copy instead would overwrite such edits.
1045
+
1046
+ When the document is not found inside the filter, nothing is written and the request throws.
1047
+
1048
+ ##### Response
1049
+
1050
+ ```yaml
1051
+ matchedCount: 2 # collection mode: rows matched by updates and moves
1052
+ modifiedCount: 2
1053
+ insertedCount: 1
1054
+ deletedCount: 1
1055
+ insertedKeys: # the key each added row got, by its temporary rowKey
1056
+ 3f2c9a61-…: { _oid: 66f9… }
1057
+ unmatchedKeys: [] # updated, moved or removed rows that matched nothing
1058
+ ```
1059
+
1060
+ In array mode `matchedCount` and `modifiedCount` count the document (0 or 1), `insertedCount` is the items pushed and `deletedCount` the removed items that were in the array.
1061
+
1062
+ `unmatchedKeys` lists the existing rows the changeset named that matched nothing: outside the `filter` (another organization's row), deleted by someone else, or never there. Treat a non-empty `unmatchedKeys` as a failed save, for example with a `Throw` action after the request, since nothing was written for those rows. Numeric keys are listed as numbers and ObjectId keys as `{ _oid }`. The rows are found with a read of their keys, scoped like the writes: removed rows are read before the write (a removed row that someone else deletes between that read and the write counts as matched, since it is gone as asked), and updated rows after it, only when fewer rows matched than were updated. A save that only updates rows that all match is one round trip.
1063
+
1064
+ The operations are one `bulkWrite`, not a transaction: with `ordered: true` the first failing operation stops the rest, and the ones before it stay written.
1065
+
1066
+ ##### Row keys
1067
+
1068
+ The `TableInput` keys rows by `rowKey` (default `_id`, then `id`). An ObjectId key comes back from the browser as the text `{"_oid":"…"}`, which the default `rowKeyType: auto` reads as an ObjectId. Object keys are always strings, so a numeric key `5` arrives as `"5"` in `updated` and `moved`, and as `5` in `removed` and `order`. With `rowKeyType: auto` both are the same row, and it matches a document key `5` or `"5"` (`{ $in: [5, "5"] }`). A string is read as a number only when it is exactly how that number prints (`"5"`, `"-2"`, `"1.5"`; not `"05"` or `"1e3"`). If a collection holds both `5` and `"5"` as different rows, set `rowKeyType: number` or `rowKeyType: string` to match one form only. `rowKeyType: objectId` also reads 24 character hex strings as ObjectIds.
1069
+
1070
+ ##### Bulk selection
1071
+
1072
+ Set `selection` instead of `changes` to write the same values to many rows, such as a bulk "Assign owner" action on the rows selected in a `Table`. `selection` is the table's `selected` value:
1073
+
1074
+ - an array of row keys, which compiles to `{ <rowKeyField>: { $in: [keys] } }`;
1075
+ - `{ all: true, except, filter, search }` when the header checkbox selects every row the view matches: the keys in `except` were deselected since, and `filter` and `search` are the view's. It compiles to the view's filter and search, validated and compiled like `MongoDBTableQuery` against `queryFields` (the table's `MongoDBTableQuery` `fields`, with the same limits and refusals), and `{ <rowKeyField>: { $nin: [except] } }`.
1076
+
1077
+ `set` is `{ [field]: value }` and `unset` a list of fields, both `fields` keys, checked and coerced like `updated` values, and never a scope field. The save is one `updateMany`:
1078
+
1079
+ ```yaml
1080
+ - updateMany:
1081
+ filter: { $and: [<filter>, <view filter>, <view search>, { _id: { $nin: [<except>] } }] }
1082
+ update: { $set: { owner.name: Ada }, $unset: { due: '' } }
1083
+ ```
1084
+
1085
+ The base `filter` (and the tenant, on a tenant connection) is one clause of the `$and`, so a crafted view can only narrow it. Row keys are read as in Row keys, and a `selection` has at most `maxChanges` keys. The response is `{ matchedCount, modifiedCount }`. `selection` can not be used in array mode.
1086
+
1087
+ #### Properties
1088
+ - `changes: object`: The `TableInput` value, `{ _payload: changes }`: `{ updated, added, removed, moved, order }`. Required unless `selection` is set.
1089
+ - `selection: object | any[]`: Bulk mode: the rows to write `set` and `unset` to, the `Table` `selected` value, `{ _payload: selected }`. See Bulk selection.
1090
+ - `set: object`: Bulk mode: `{ [field]: value }` to set on every selected row.
1091
+ - `unset: string[]`: Bulk mode: fields to remove from every selected row.
1092
+ - `queryFields: object`: Bulk mode: the `MongoDBTableQuery` `fields` of the table, keyed by column key. Needed when a `selection` has a `filter` or `search`.
1093
+ - `user: object`: Bulk mode: the user that `{ $user: path }` values in a `selection` filter resolve from. Set it to `{ _user: true }`.
1094
+ - `timezone: string`: Default: `UTC` - Bulk mode: the IANA time zone whose days the date filters of a `selection` compare, as for `MongoDBTableQuery`.
1095
+ - `fields: object`: __Required__ - The allowlist, keyed by the `TableInput` column `field` (its dot path, the changeset key), not the column `key` that `MongoDBTableQuery` fields use. Each field is an object:
1096
+ - `type: enum`: __Required__ - The column type, as for `MongoDBTableQuery`. Values are checked and coerced to it.
1097
+ - `path: string`: Default: the field key - Dot path the value is written to, in the document or, in array mode, in the item.
1098
+ - `filter: object`: The base filter that scopes every operation, for example `{ org_id: { _user: organization.id } }`. New rows are stamped with its equality conditions, and `fields` can not write its fields. Required unless the connection is tenant-scoped. Set it to `{}` to allow writes to every document. See Scope fields.
1099
+ - `rowKeyField: string`: Default: `_id` - The document field a row key matches, in collection mode. With any other field, added rows need their key from a column or `insertDefaults`.
1100
+ - `rowKeyType: enum`: Default: `auto` - How row keys are read and matched: `auto`, `objectId`, `string` or `number`. See Row keys.
1101
+ - `array: object`: Array mode: the rows are the items of an embedded array in one document.
1102
+ - `documentId: any`: __Required__ - The `_id` of the document. Use `{ _oid: <hex string> }` for an ObjectId from a string.
1103
+ - `path: string`: __Required__ - Dot path of the array in the document.
1104
+ - `itemKeyField: string`: Default: `_id` - The item field a row key matches.
1105
+ - `positionField: string`: Dot path of the numeric position field, the `TableInput` `rowDrag.positionField`. Needed to save `moved`, and to save `order` in collection mode.
1106
+ - `insertDefaults: object`: Values every added row gets, for example `{ created_by: { _user: id } }` or a created date. `fields` can not write them. Keys may be dot paths. See Scope fields.
1107
+ - `ordered: boolean`: Default: `true` - Run the operations in order and stop at the first error. `false` (collection mode only) runs every operation and reports every error.
1108
+ - `maxChanges: integer`: Default: `1000` - The most row changes one request may apply (updated, added, removed and moved rows, plus order entries). A larger changeset throws.
1109
+ - `options: object`: Optional `bulkWrite` settings, for example `writeConcern`, `bypassDocumentValidation` or `comment`. See `MongoDBBulkWrite`.
1110
+
1111
+ #### Examples
1112
+
1113
+ ###### Save the ingredients of a recipe (array mode):
1114
+ The ingredients are an array in the recipe document, ordered by a `position` field. Dragging a row gives it a position between its neighbours, so a move saves one field on one item.
1115
+ ```yaml
1116
+ id: recipe
1117
+ type: Box
1118
+ requests:
1119
+ - id: get_recipe
1120
+ type: MongoDBAggregation
1121
+ connectionId: recipes
1122
+ payload:
1123
+ recipe_id:
1124
+ _url_query: id
1125
+ properties:
1126
+ pipeline:
1127
+ - $match:
1128
+ _id:
1129
+ _payload: recipe_id
1130
+ org_id:
1131
+ _user: organization.id
1132
+ - $project:
1133
+ title: 1
1134
+ items:
1135
+ $sortArray:
1136
+ input: $items
1137
+ sortBy:
1138
+ position: 1
1139
+ - id: save_items
1140
+ type: MongoDBTableChanges
1141
+ connectionId: recipes
1142
+ payload:
1143
+ recipe_id:
1144
+ _url_query: id
1145
+ changes:
1146
+ _state: items
1147
+ properties:
1148
+ array:
1149
+ documentId:
1150
+ _payload: recipe_id
1151
+ path: items
1152
+ filter:
1153
+ org_id:
1154
+ _user: organization.id
1155
+ positionField: position
1156
+ fields:
1157
+ ingredient:
1158
+ type: text
1159
+ qty:
1160
+ type: number
1161
+ unit:
1162
+ type: text
1163
+ changes:
1164
+ _payload: changes
1165
+ events:
1166
+ onMount:
1167
+ - id: fetch
1168
+ type: Request
1169
+ params: get_recipe
1170
+ blocks:
1171
+ - id: items
1172
+ type: TableInput
1173
+ properties:
1174
+ data:
1175
+ _request: get_recipe.0.items
1176
+ addRow: true
1177
+ rowDrag:
1178
+ positionField: position
1179
+ rowActions:
1180
+ delete: true
1181
+ columns:
1182
+ - key: ingredient
1183
+ editable: true
1184
+ - key: qty
1185
+ type: number
1186
+ editable: true
1187
+ - key: unit
1188
+ editable: true
1189
+ - id: save
1190
+ type: Button
1191
+ properties:
1192
+ title: Save
1193
+ events:
1194
+ onClick:
1195
+ - id: save_items
1196
+ type: Request
1197
+ params: save_items
1198
+ - id: check_saved
1199
+ type: Throw
1200
+ params:
1201
+ throw:
1202
+ _gt:
1203
+ - _array.length:
1204
+ _if_none:
1205
+ - _request: save_items.unmatchedKeys
1206
+ - []
1207
+ - 0
1208
+ message: Some items were changed or removed by someone else. Reload and try again.
1209
+ - id: refetch
1210
+ type: Request
1211
+ params: get_recipe
1212
+ - id: reset
1213
+ type: CallMethod
1214
+ params:
1215
+ blockId: items
1216
+ method: resetChanges
1217
+ ```
1218
+
1219
+ ###### Save edits to a list of deals (collection mode):
1220
+ Every row is a document. New deals get the organization from the `filter` and the creator from `insertDefaults`. The table can not set either, and a `fields` entry for `org_id` or `created_by` would be refused.
1221
+ ```yaml
1222
+ requests:
1223
+ - id: save_deals
1224
+ type: MongoDBTableChanges
1225
+ connectionId: deals
1226
+ payload:
1227
+ changes:
1228
+ _state: deals_table
1229
+ properties:
1230
+ filter:
1231
+ org_id:
1232
+ _user: organization.id
1233
+ fields:
1234
+ # Keyed by the TableInput column field, the changeset keys.
1235
+ name:
1236
+ type: text
1237
+ stage:
1238
+ type: tag
1239
+ amount:
1240
+ type: currency
1241
+ owner.name:
1242
+ type: text
1243
+ close_date:
1244
+ type: date
1245
+ insertDefaults:
1246
+ org_id:
1247
+ _user: organization.id
1248
+ created_by:
1249
+ _user: id
1250
+ created:
1251
+ _date: now
1252
+ changes:
1253
+ _payload: changes
1254
+ ```
1255
+
1256
+ ###### Assign an owner to the selected deals (bulk selection):
1257
+ The `deals_table` `Table` in server mode shows the deals of `deals_page` (the `MongoDBTableQuery` example below). A button in its `bulkActions` sends the table's `selected` value, a list of keys or every row matching the view, and the request sets the owner on those rows inside the organization.
1258
+ ```yaml
1259
+ requests:
1260
+ - id: assign_owner
1261
+ type: MongoDBTableChanges
1262
+ connectionId: deals
1263
+ payload:
1264
+ selected:
1265
+ _state: deals_table.selected
1266
+ owner:
1267
+ _state: new_owner
1268
+ properties:
1269
+ filter:
1270
+ org_id:
1271
+ _user: organization.id
1272
+ fields:
1273
+ owner.name:
1274
+ type: text
1275
+ # The table's MongoDBTableQuery fields, keyed by column key.
1276
+ queryFields:
1277
+ name:
1278
+ type: text
1279
+ search: true
1280
+ stage:
1281
+ type: tag
1282
+ owner:
1283
+ type: text
1284
+ path: owner.name
1285
+ search: true
1286
+ amount:
1287
+ type: currency
1288
+ user:
1289
+ _user: true
1290
+ selection:
1291
+ _payload: selected
1292
+ set:
1293
+ owner.name:
1294
+ _payload: owner
1295
+ ```
1296
+
1297
+ ### MongoDBTableQuery
1298
+
1299
+ The `MongoDBTableQuery` request serves a `Table` block in server mode. The table sends its view (sort, filter, search, grouping and aggregates) and the rows it needs, and the request compiles them to one aggregation on the server, against an allowlist of `fields`. The browser never sends MongoDB syntax: view keys that are not in `fields`, operators the field type does not allow and values of the wrong type are refused, regex input is escaped, and no `$where`, `$expr` or raw stages are accepted from the view.
1300
+
1301
+ The base `pipeline` always runs first, so use it for tenant or permission scoping. The view can only narrow what the base pipeline returns. On a tenant connection the tenant scope is added before the base pipeline, as for `MongoDBAggregation`.
1302
+
1303
+ Rows return only `_id`, the `fields` paths and the `returnFields` paths (`project: true`, the default), so a field the table does not list never reaches the browser, even when the documents hold it. Add the paths that cells read without a field of their own to `returnFields`, such as an avatar `srcField`, a link `labelField` or a `rowKey` other than `_id`. Set `project: false` to return the documents as the base pipeline leaves them, for example when it ends with its own `$project`.
1304
+
1305
+ The request compiles to:
1306
+
1307
+ ```yaml
1308
+ - <base pipeline stages>
1309
+ - $match: <view filter>
1310
+ - $match: <view search>
1311
+ - $match: <groupPath>
1312
+ - $sort: <view sort, then _id> # when rows are returned
1313
+ - $facet:
1314
+ rows: [$skip, $limit, $project] # or groups: [$group, $sort, $skip, $limit]
1315
+ total: [$count]
1316
+ aggregates: [$group] # when the view has aggregates
1317
+ distinct_a0: [$group, $count] # one per countDistinct
1318
+ ```
1319
+
1320
+ Rows are sorted by the view sort with `_id` as a tiebreak, so blocks of rows never repeat or skip a row. The sort runs before `$facet`, so an index on the base pipeline match, filter and sort fields (for example `{ org_id: 1, amount: -1, _id: 1 }` for a table of one organization sorted by amount) serves it, and each block reads the rows in index order. Without such an index, MongoDB sorts every matching document for each block, so add indexes for the sorts a large table offers.
1321
+
1322
+ ##### Response
1323
+
1324
+ ```yaml
1325
+ rows: [...] # the rows from startRow to endRow, [] when groups are returned
1326
+ total: 12408 # rows matching the view, or the number of groups at this level
1327
+ groups: # only when view.group has more levels than groupPath
1328
+ - key: won # the group value (null for missing values)
1329
+ count: 210
1330
+ aggregates: { amount: 125000 }
1331
+ aggregates: # only when view.aggregates is set, over the rows this request matches
1332
+ amount: 3400000
1333
+ ```
1334
+
1335
+ When `view.group` is set and `groupPath` is shorter than it, the request returns the groups of the next level, inside the groups in `groupPath`. When `groupPath` has a value for every level, it returns the leaf rows of that group.
1336
+
1337
+ ##### Filters
1338
+
1339
+ The view `filter` is a condition: `{ and: [...] }`, `{ or: [...] }` or `{ key, op, value }`. The operators each field type allows:
1340
+
1341
+ | Field types | Operators |
1342
+ | --- | --- |
1343
+ | all | `eq`, `ne`, `in`, `nin`, `empty`, `notEmpty` |
1344
+ | `text`, `email`, `phone`, `url`, `link`, `html`, `relation`, `tag`, `status`, `avatar` | `contains`, `notContains`, `startsWith`, `endsWith` |
1345
+ | `number`, `currency`, `percent`, `progress`, `rating` | `gt`, `gte`, `lt`, `lte`, `between` (`value: [from, to]`) |
1346
+ | `date`, `datetime` | `before`, `after`, `between`, `within` (`value: { last or next: n, unit: day, week, month or year }`) |
1347
+ | `boolean` | `isTrue`, `isFalse` |
1348
+ | `tags`, `people` | `contains` (has the value), `notContains` (does not have the value); `in` is has any of, `nin` is has none of |
1349
+ | `image`, `json` | the operators for all types only |
1350
+
1351
+ These are the operators the `Table` filter menus offer for each column type, so any filter a user builds is accepted. An `avatar` field filters on the text at its `path` (the name the cell shows), like a `text` field.
1352
+
1353
+ - Text comparisons are case-insensitive.
1354
+ - `empty` matches null, missing, `''` and `[]`.
1355
+ - `eq` and `ne` on dates compare whole days, and so do `before`, `after` and `between` on `date` fields. `within` covers whole days, from the start of the day `n` units ago to the end of today (or from the start of today to the end of the day `n` units ahead), as the table filters in the browser.
1356
+ - Days are the days of `timezone`, UTC by default. The browser filters by the user's local days, so pass the user's time zone for day-based filters, for example `timezone: { _payload: timezone }` with `timezone: { _js: 'return Intl.DateTimeFormat().resolvedOptions().timeZone;' }` in the request `payload`. A date-only value such as `2026-03-01` (what `date` column filters send) is that day in the time zone. An instant is compared by the day it falls on there.
1357
+ - `isFalse` matches every value that is not `true`.
1358
+ - Numeric values may be numbers or numeric strings, and date values dates, date strings or timestamps.
1359
+
1360
+ A value can be `{ $user: path }`, for example `{ key: owner, op: eq, value: { $user: id } }`. It is resolved on the server from the request's `user` property, which should be set to `{ _user: true }` (evaluated on the server from the session), never from a value the browser sends. The request throws when the user value is not set, rather than matching rows where the field is empty.
1361
+
1362
+ ##### Aggregates
1363
+
1364
+ `view.aggregates` maps field keys to a function. All field types allow `count`, `countDistinct`, `countEmpty`, `countNotEmpty` and `percentEmpty` (a fraction from 0 to 1). Numeric types also allow `sum`, `avg`, `min` and `max`, text types (`text`, `email`, `phone`, `url`, `link`, `html`, `relation`, `tag`, `status`, `avatar`) `min` and `max`, and date types `earliest` and `latest`. `min` and `max` of text leave out empty values and compare strings as MongoDB does: by code point, so `Z` comes before `a`, unless `options.collation` sets a locale.
1365
+
1366
+ `countDistinct` groups by the field's values, so it needs `groupable: true` on the field, like grouping by it. Over the whole result it counts the groups in their own `$facet` branch, so a field with many distinct values never builds them all into one document; in a group level it collects the values of each group.
1367
+
1368
+ ##### Limits
1369
+
1370
+ The view comes from the browser, so the work one request can ask of MongoDB is bounded:
1371
+
1372
+ - A filter has at most 200 conditions and groups (empty groups count), nested at most 8 levels deep.
1373
+ - A filter has at most 1000 values in all, and `in` and `nin` at most 500 each.
1374
+ - A string value (a `contains` text, an `eq` value, a list item) has at most 200 characters, like the search.
1375
+ - A sort has at most 10 keys, and a view at most 5 group levels.
1376
+ - One request returns at most `maxRows` rows or groups (default 1000).
1377
+ - The aggregation stops after `options.maxTimeMS`, 10000 (10 seconds) by default. Set a larger value in `options` for a slow collection, or add indexes for the filters and sorts the table uses.
1378
+
1379
+ A request over a limit throws before the query runs.
1380
+
1381
+ #### Properties
1382
+ - `fields: object`: __Required__ - The allowlist, keyed by the Table column `key` (the view's keys), not the column `field` that `MongoDBTableChanges` fields use; `path` gives the field path. Each field is an object:
1383
+ - `type: enum`: __Required__ - The column type: `text`, `email`, `phone`, `url`, `link`, `html`, `relation`, `tag`, `status`, `number`, `currency`, `percent`, `progress`, `rating`, `date`, `datetime`, `boolean`, `tags`, `people`, `avatar`, `image` or `json`. It decides the operators and aggregates the field allows.
1384
+ - `path: string`: Default: the field key - Dot path of the value in the documents the base pipeline returns.
1385
+ - `search: boolean`: Default: `false` - Include the field in the view search. Each search word must match at least one search field.
1386
+ - `sortable: boolean`: Default: `true` - Allow sorting by the field.
1387
+ - `filterable: boolean`: Default: `true` - Allow filtering by the field.
1388
+ - `groupable: boolean`: Default: `false` - Allow grouping by the field, and `countDistinct` on it. `tags` and `people` fields can not be grouped.
1389
+ - `pipeline: object[]`: Default: `[]` - Base aggregation stages that always run first, for example tenant scoping and a `$project`. `$out` and `$merge` are not allowed.
1390
+ - `view: object`: The Table view, `{ _payload: view }`. Only `sort`, `filter`, `search`, `group` and `aggregates` are read.
1391
+ - `startRow: integer`: Default: `0` - Index of the first row to return, `{ _payload: startRow }`.
1392
+ - `endRow: integer`: Default: `startRow + maxRows` - Index after the last row to return, `{ _payload: endRow }`.
1393
+ - `groupPath: any[]`: Default: `[]` - The group values of the expanded group, one per group level, `{ _payload: groupPath }`.
1394
+ - `maxRows: integer`: Default: `1000` - The most rows or groups one request may return. A request for more throws.
1395
+ - `user: object`: The user that `{ $user: path }` filter values resolve from. Set it to `{ _user: true }`.
1396
+ - `timezone: string`: Default: `UTC` - The IANA time zone, for example `Europe/London`, whose days date filters compare. See Filters.
1397
+ - `project: boolean`: Default: `true` - Return only `_id`, the `fields` paths and `returnFields` in each row. Set it to `false` to return the documents as the base pipeline leaves them.
1398
+ - `returnFields: string[]`: More dot paths each row returns, for values that cells read without a field of their own, for example an avatar `srcField` or a link `labelField`.
1399
+ - `options: object`: Optional aggregate settings, for example `collation`, `maxTimeMS` (default `10000`), `allowDiskUse` or `hint`. See `MongoDBAggregation`.
1400
+
1401
+ #### Examples
1402
+
1403
+ ###### A Table in server mode:
1404
+ The Table sends `{ startRow, endRow, view, groupPath }` as the fetch event. The request `payload` reads it with `_event`, and the properties read the payload with `_payload`. Field keys match the Table column keys.
1405
+ ```yaml
1406
+ id: deals
1407
+ type: PageHeaderMenu
1408
+ requests:
1409
+ - id: deals_page
1410
+ type: MongoDBTableQuery
1411
+ connectionId: deals
1412
+ payload:
1413
+ view:
1414
+ _event: view
1415
+ startRow:
1416
+ _event: startRow
1417
+ endRow:
1418
+ _event: endRow
1419
+ groupPath:
1420
+ _event: groupPath
1421
+ properties:
1422
+ pipeline:
1423
+ - $match:
1424
+ org_id:
1425
+ _user: organization.id
1426
+ # Rows return _id, the field paths and these paths only.
1427
+ returnFields:
1428
+ - owner.avatar
1429
+ fields:
1430
+ name:
1431
+ type: text
1432
+ search: true
1433
+ stage:
1434
+ type: tag
1435
+ groupable: true
1436
+ owner:
1437
+ type: text
1438
+ path: owner.name
1439
+ search: true
1440
+ groupable: true
1441
+ amount:
1442
+ type: currency
1443
+ created:
1444
+ type: date
1445
+ user:
1446
+ _user: true
1447
+ view:
1448
+ _payload: view
1449
+ startRow:
1450
+ _payload: startRow
1451
+ endRow:
1452
+ _payload: endRow
1453
+ groupPath:
1454
+ _payload: groupPath
1455
+ blocks:
1456
+ - id: deals_table
1457
+ type: Table
1458
+ properties:
1459
+ data:
1460
+ mode: server
1461
+ request: deals_page
1462
+ columns:
1463
+ - key: name
1464
+ - key: stage
1465
+ type: tag
1466
+ groupable: true
1467
+ - key: owner
1468
+ field: owner.name
1469
+ type: avatar
1470
+ groupable: true
1471
+ cell:
1472
+ srcField: owner.avatar
1473
+ - key: amount
1474
+ type: currency
1475
+ aggregate: sum
1476
+ - key: created
1477
+ type: date
1478
+ ```
1479
+
1480
+ ###### Only the current user's deals, with a filter the table can not remove:
1481
+ ```yaml
1482
+ requests:
1483
+ - id: my_deals_page
1484
+ type: MongoDBTableQuery
1485
+ connectionId: deals
1486
+ payload:
1487
+ view:
1488
+ _event: view
1489
+ startRow:
1490
+ _event: startRow
1491
+ endRow:
1492
+ _event: endRow
1493
+ properties:
1494
+ pipeline:
1495
+ - $match:
1496
+ owner_id:
1497
+ _user: id
1498
+ fields:
1499
+ name:
1500
+ type: text
1501
+ search: true
1502
+ amount:
1503
+ type: currency
1504
+ closed:
1505
+ type: boolean
1506
+ view:
1507
+ _payload: view
1508
+ startRow:
1509
+ _payload: startRow
1510
+ endRow:
1511
+ _payload: endRow
1512
+ maxRows: 500
1513
+ ```
1514
+
563
1515
  ### MongoDBUpdateMany
564
1516
 
565
1517
  The `MongoDBUpdateMany` request updates multiple documents that match a certain criteria in the collection specified in the connectionId. It requires a filter, which is written in the query syntax, to select the documents to update.
@@ -619,11 +1571,15 @@ requests:
619
1571
  ### MongoDBUpdateOne
620
1572
 
621
1573
  The `MongoDBUpdateOne` request updates a single document in the collection specified in the connectionId. It requires a filter, which is written in the query syntax, to select a document to update. It will update the first document that matches the filter. If the `upsert` option is set to true, it will insert a new document if no document is found to update.
622
- > MongoDBUpdateOne response differs when the connection has a log collection. When a log collection is set on the connection, a findOneAndUpdate operation is performed compared to the standard updateOne operation.
1574
+
1575
+ If no document matches the filter, the request throws `No matching record to update.` — a silent no-op update usually indicates a bug. Set `disableNoMatchError: true` on the request to restore the pre-5.5.0 behavior of returning `matchedCount: 0`. Requests with the `upsert` option never throw this error. Running `lowdefy upgrade` adds `disableNoMatchError: true` to existing requests so upgraded apps keep their behavior.
1576
+
1577
+ > When the connection has a log collection, a findOneAndUpdate operation is performed instead of the standard updateOne operation so before and after document snapshots can be captured in the change log. The response shape is the same in both cases.
623
1578
 
624
1579
  #### Properties
625
1580
  - `filter: object`: __Required__ - The filter used to select the document to update.
626
1581
  - `update: object | object[]`: __Required__ - The update operations to be applied to the document.
1582
+ - `disableNoMatchError: boolean`: Default: `false` - Do not throw an error when no document matches the filter.
627
1583
  - `options: object`: Optional settings. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#updateone) for more information. Supported settings are:
628
1584
  - `arrayFilters: object[]`: _Array_ - Array filters for the [`$[<identifier>]`](https://docs.mongodb.com/manual/reference/operator/update/positional-filtered/) array update operator.
629
1585
  - `authdb: string`: Specifies the authentication information to be used.
@@ -692,6 +1648,47 @@ requests:
692
1648
  _date: now
693
1649
  ```
694
1650
 
1651
+ ### MongoDBVersionedUpdateOne
1652
+
1653
+ The `MongoDBVersionedUpdateOne` request updates a single document while preserving the previous version. The matched document is re-inserted under a new `_id`, and the update is applied to the new copy — so the collection keeps a full version history of the document.
1654
+
1655
+ If no document matches the filter, the request throws `No matching record to update.`. Set `disableNoMatchError: true` on the request to suppress the error. Requests with the `upsert` update option never throw this error.
1656
+
1657
+ > The version insert and the update are separate operations, not a transaction. If the update fails, the inserted version copy remains in the collection.
1658
+
1659
+ > When the connection has a log collection, a findOneAndUpdate operation is performed instead of the standard updateOne operation so before and after document snapshots can be captured in the change log. The response shape is the same in both cases.
1660
+
1661
+ #### Properties
1662
+ - `filter: object`: __Required__ - The filter used to select the document to version and update.
1663
+ - `update: object | object[]`: __Required__ - The update operations to be applied to the new copy of the document.
1664
+ - `disableNoMatchError: boolean`: Default: `false` - Do not throw an error when no document matches the filter.
1665
+ - `options: object`: Optional settings for each underlying operation:
1666
+ - `find: object`: Options for the find one operation. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#findone).
1667
+ - `insert: object`: Options for the insert one operation that creates the version copy. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#insertone).
1668
+ - `update: object`: Options for the update operation. See the [driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html#updateone).
1669
+
1670
+ #### Examples
1671
+
1672
+ ###### Update a document, keeping the previous version:
1673
+ ```yaml
1674
+ requests:
1675
+ - id: versioned_update
1676
+ type: MongoDBVersionedUpdateOne
1677
+ connectionId: my_mongodb_collection_id
1678
+ payload:
1679
+ doc_id:
1680
+ _state: doc_id
1681
+ properties:
1682
+ filter:
1683
+ doc_id:
1684
+ _payload: doc_id
1685
+ current: true
1686
+ update:
1687
+ $set:
1688
+ status:
1689
+ _state: status
1690
+ ```
1691
+
695
1692
  ## Websockets
696
1693
 
697
1694
  Websocket types:
@@ -703,6 +1700,8 @@ The `MongoDBChangeStream` [websocket](/websockets-introduction) opens a MongoDB
703
1700
 
704
1701
  Properties are evaluated per subscription, so `_user` and `_payload` operators in the `pipeline` produce user-specific streams.
705
1702
 
1703
+ A change stream reads the collection, so a connection with `read: false` refuses subscriptions, as it refuses read requests.
1704
+
706
1705
  > Change streams require MongoDB to run as a replica set — they are not available on standalone deployments. MongoDB Atlas clusters support them out of the box.
707
1706
 
708
1707
  #### Properties
@@ -755,3 +1754,15 @@ pages:
755
1754
  ```
756
1755
 
757
1756
  The change event payload is available on `_event: messages` in `onMessage` and via the [`_websocket`](/websocket-subscriptions) operator — each message is the MongoDB change event, including `operationType`, `documentKey` and `fullDocument`.
1757
+
1758
+ ## Errors
1759
+
1760
+ When MongoDB rejects an operation, the request fails with a `ServiceError` that carries:
1761
+
1762
+ - `code` — the MongoDB error code, for example `11000` for a duplicate key.
1763
+ - `message` — a plain sentence naming the collection and the request type, like `MongoDB: Duplicate key on collection "orders".`
1764
+ - `hint` — a sentence saying what to do about it, for example to insert with `MongoDBUpdateOne` and `upsert: true`, to add an index covering the filter, or to grant the database user a role.
1765
+
1766
+ The driver's own message is never sent to the browser — it can quote values from the document that triggered the error. It is logged on the server instead, where the dev server terminal prints it under the located error line as `Caused by: MongoServerError: E11000 …`.
1767
+
1768
+ Network, DNS and TLS failures are also `ServiceError`s, classified by the connection layer rather than by an error code.