Working with Collections

Analogy categoryAnalogies

What Collections Are and When to Use Them

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.

🏏

Cricket analogy: A Collection is like a scorer's personal notebook kept courtside during a match — fast to update ball by ball, but it vanishes with the scorer at day's end unless they formally transcribe it into the official archived scorebook.

powerfx

// Load a delegable subset from Dataverse into a local Collection, then work with it offline
ClearCollect(
    colOpenOrders,
    Filter(Orders, Status = 'Orders (Status)'.Open)
);

// Add a locally-created row without touching the server yet
Collect(colOpenOrders, {OrderId: -1, CustomerName: "Walk-in", Total: 0});

Collect, ClearCollect, and Modifying Collection Rows

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.

🏏

Cricket analogy: ClearCollect() wiping and repopulating a Collection in one step is like an innings break where the scoreboard is reset to zero and immediately reloaded with the second innings' fresh data, rather than manually erasing digit by digit.

Persisting Collection Changes and Using SaveData

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.

🏏

Cricket analogy: SaveData persisting only to that specific device is like a scorer's personal digital scoring app saving its match data only to their own tablet, requiring a deliberate export step before that data reaches the official league database.

SaveData/LoadData require a unique, consistent file name per Collection and only work in the mobile and Windows players, not the browser-based web player — apps intended to run in a browser need a different offline strategy, such as syncing eagerly whenever connectivity is detected.

Large Collections consume device memory and can noticeably slow down galleries and forms bound to them; avoid ClearCollect()-ing an entire multi-million-row table into a Collection just to work around a delegation warning — that defeats the purpose of delegation and can crash the app on lower-end devices.

A Collection is an in-memory, table-shaped local variable created with Collect() or ClearCollect(), scoped to the device for that session.
ClearCollect() wipes and repopulates a Collection in one step; Collect() appends without clearing.
Update(), UpdateIf(), Patch(), Remove(), and RemoveIf() modify Collection rows instantly and entirely in local memory.
Collection changes are not automatically persisted to a real data source — a ForAll/Patch loop (or dirty-row tracking) is needed to sync back.
SaveData()/LoadData() persist a Collection to local device storage across sessions, enabling offline field-worker scenarios, but only in mobile/desktop players.
Collections are unsuitable for data that must be shared across users or centrally persisted, since they live on a single device.
Loading an entire large table into a Collection to dodge a delegation warning is a performance anti-pattern that can crash the app.