Documentation

Appearance

How do offline datasets work? ​

Offline datasets let a connected product carry a bounded copy of cloud-managed data locally so the device can continue making product decisions when Dataplicity is unavailable.

Typical examples include:

  • authorised tags or credentials;
  • site configuration;
  • approved product records;
  • schedules;
  • customer-specific reference data needed for offline operation.

The important design question is not merely how to download the data. It is what authority the local copy has, how stale it may become, and how you reconcile changes after reconnect.

Use offline data only for decisions the device is allowed to make locally ​

A dataset is useful when the device already has a local decision it can safely make.

For example:

text
cloud/customer system
        |
        | published dataset version
        v
device local copy
        |
        | local lookup while online or offline
        v
product decision

The device should still enforce its own safety and domain rules.

Define the dataset contract ​

For every offline dataset specify:

  • record schema;
  • stable record identifiers;
  • owning customer/site/product scope;
  • dataset version;
  • freshness/expiry policy;
  • what happens when the dataset is missing;
  • what happens when it is stale;
  • whether the device can create local state derived from it;
  • how updates are applied atomically;
  • how much storage is required.

Without those rules, an offline cache can quietly become an uncontrolled second database.

Staleness is a product decision ​

Different products tolerate different ages of offline data.

Examples:

  • an HVAC weekly schedule may remain useful for days;
  • a list of service technicians may tolerate a moderate delay;
  • available prepaid credit may require a much tighter model;
  • revoked access credentials may need explicit expiry or revocation handling.

Do not present “works offline” as if it means “cloud data can be stale forever.”

Credit and entitlement need more than a copied number ​

Suppose a device receives a balance of 100 units and then spends 40 units while offline. Another device may also be operating offline against related state.

A copied balance alone does not solve distributed credit accounting.

For credit, prepaid access, fuel, or other scarce entitlement, you may need a domain-specific model such as:

  • per-device reservations;
  • bounded offline allowances;
  • monotonic transaction IDs;
  • local durable journals;
  • expiry windows;
  • reconciliation after reconnect;
  • conflict handling and reversal rules.

Offline datasets can distribute the approved input to that model. They do not automatically make distributed financial state safe.

Apply updates atomically ​

A device should not observe a half-written dataset.

A common local pattern is:

  1. receive the new version into temporary storage;
  2. validate schema/checksum/signature as required by your product;
  3. fsync/persist according to durability needs;
  4. atomically switch the active version;
  5. keep or remove the previous version according to rollback policy.

The exact implementation depends on the device application and storage constraints.

Be mindful of flash wear ​

Large or frequently changing datasets can create unnecessary writes on embedded flash.

Design for the actual update pattern:

  • send meaningful changes rather than rewriting continuously;
  • batch updates where acceptable;
  • avoid persisting volatile fields that are not required offline;
  • use an appropriate local filesystem/database strategy;
  • measure write amplification on constrained hardware;
  • reserve durable writes for data whose loss actually matters.

Dataplicity can deliver data; your device application still owns how it persists and consumes that data safely.

Report which version is active ​

For operational confidence, have the device report the active dataset version or another verification signal.

Then an operator can distinguish:

  • cloud version 42 published;
  • device online but still using version 41;
  • device offline using version 41;
  • device rejected version 42;
  • device successfully activated version 42.

That is more useful than merely knowing that a download request was issued.

Scope datasets correctly ​

Customer data should not leak between tenants.

If a dataset is customer/site scoped:

  • generate/distribute only the records authorised for that scope;
  • remove or replace cached data when a device is reassigned;
  • test cross-customer isolation;
  • preserve audit evidence of version/allocation changes where required.

See Customer, site, and device isolation.

Offline-first workflow pattern ​

A healthy architecture is often:

text
cloud defines bounded policy/data
        |
        v
device caches approved version
        |
        +----> product continues during outage
        |
        v
local journal records important events
        |
        v
reconnect -> upload/reconcile -> receive newer policy

This keeps cloud convenience without making connectivity a prerequisite for correct local operation.