Working with Collections

A Collection is an in-memory, table-shaped variable that lives entirely on the user's device for the duration of the app session (or persists across sessions if explicitly saved with SaveData), created and populated with ClearCollect() or Collect(). Collections are the right tool whenever data needs to be held locally rather than round-tripped to a data source on every read — caching a small reference table for offline use, staging a multi-step form's data before a single final submit, or holding the working set for a non-delegable operation like a complex client-side sort — but they are the wrong tool for anything that should be shared across users or persisted centrally, since a Collection disappears when the app is closed unless SaveData is used, and SaveData only persists to that specific device, not to other users.

Collect() appends one or more records to an existing Collection (creating it if it doesn't already exist), while ClearCollect() first empties the Collection and then repopulates it in one step, which is the standard pattern for refreshing a cached dataset from a data source. Updating a specific row within a Collection uses Update(), UpdateIf(), or Patch() targeted at the Collection itself (for example, Patch(colOpenOrders, LookUp(colOpenOrders, OrderId = 5), {Total: 250})), and removing rows uses Remove() for specific records or RemoveIf() for a condition, all of which operate purely in local memory and take effect instantly without any network round trip, which is precisely why Collections feel more responsive than data-source-backed operations but also why they require an explicit later step (like a Patch loop against the real data source) to actually persist changes.

Because a Collection's edits exist only in local memory, they must be explicitly written back to a real data source, typically with a ForAll loop calling Patch() for each changed row, or by tracking a smaller list of dirty rows and patching only those to avoid unnecessary writes; skipping this step means the user's changes vanish the moment the app closes. For offline scenarios specifically, SaveData(collectionName, "uniqueFileName") and LoadData(collectionName, "uniqueFileName") persist a Collection to the device's local storage across sessions (mobile and desktop players only — not the web player), which is the standard pattern for building an app that lets field workers keep working without connectivity and sync their changes once back online.