Storage Policies

Default behavior

If you configure nothing, the built-in fallback is a single raw tier from age 0 to null.

That means:

• all points are stored as raw rows
• original granularity is preserved
• retention is effectively infinite
• no rollups are created
• nothing is deleted by policy

How policies are applied

Policies are evaluated in this order:

1. matching rule inside the user's assigned preset, if the user has one
2. exact provider + seriesType default rule
3. seriesType default rule
4. provider default rule
5. global default rule
6. built-in raw-forever fallback

The same policy logic is used for:

• manual syncs
• cron syncs
• Garmin webhook ingestion
• SDK/mobile push ingestion

Configure the policy

await wearables.replaceTimeSeriesPolicyConfiguration(ctx, {
  defaultRules: [
    {
      tiers: [{ kind: "raw", fromAge: "0m", toAge: null }],
    },
    {
      provider: "garmin",
      seriesType: "heart_rate",
      tiers: [
        { kind: "raw", fromAge: "0m", toAge: "24h" },
        { kind: "rollup", fromAge: "24h", toAge: "7d", bucket: "30m" },
        { kind: "rollup", fromAge: "7d", toAge: null, bucket: "3h" },
      ],
    },
  ],
  presets: [
    {
      key: "pro",
      rules: [
        {
          provider: "garmin",
          seriesType: "heart_rate",
          tiers: [
            { kind: "raw", fromAge: "0m", toAge: "7d" },
            { kind: "rollup", fromAge: "7d", toAge: null, bucket: "1h" },
          ],
        },
      ],
    },
  ],
  maintenance: {
    enabled: true,
    interval: "1h",
  },
});

This example keeps a raw-everything fallback for any provider or metric that does not match a more specific rule. It then adds a Garmin-specific heart-rate rule that keeps raw samples for 24h, compacts older data into 30m rollups until 7d, and keeps 3h rollups after that.

It also defines a pro preset. Users assigned to that preset get a more generous Garmin heart-rate policy: raw samples for 7d, then 1h rollups forever. The hourly maintenance loop is what keeps stored rows aligned with those tiers over time.

Assign a preset to a user

await wearables.setUserTimeSeriesPolicyPreset(ctx, {
  userId: "user-123",
  presetKey: "pro",
});

In this example, assigning pro to user-123 gives only that user the longer Garmin heart-rate raw window. Other users continue using the default rules unless they are assigned a different preset.

Clear a preset assignment with:

await wearables.setUserTimeSeriesPolicyPreset(ctx, {
  userId: "user-123",
  presetKey: null,
});

Configuration reference

Top-level fields

Rule fields

Valid provider values

• garmin
• suunto
• polar
• whoop
• strava
• apple
• samsung
• google

provider is not Garmin-only. The policy resolver accepts any ProviderName, and the same storage-policy engine is used for every source that writes time-series rows.

In practice today, policies actively affect:

• garmin
• whoop
• suunto
• apple
• samsung
• google

Rules targeting strava or polar are still valid, but they do not currently change stored time-series behavior because those integrations do not currently write dataPoints rows.

seriesType

Use any supported metric key from Series Types, for example:

• heart_rate
• resting_heart_rate
• oxygen_saturation
• steps
• weight
• respiratory_rate
• garmin_stress_level

Tier fields

Duration values

Duration fields accept:

• compact strings such as 500ms, 30s, 15m, 24h, 7d, 2w
• non-negative numbers interpreted as milliseconds

Validation rules

The implementation enforces:

• the first tier must start at age 0
• tiers must be contiguous without gaps or overlap
• open-ended tiers must be last
• only one raw tier is allowed per rule
• rollup buckets must be positive whole-minute durations

If data becomes older than the last tier, maintenance deletes it.

Aggregations

For rollup-backed reads:

• the response always includes value
• value is chosen from the configured aggregations with this priority: avg, then last, then max, then min, then count

So if you configure:

aggregations: ["last"];

then value for the rollup point will be the bucket's last value.

Maintenance behavior

Scheduled maintenance is internal to the component and enabled by default. After an upgrade, older scheduled jobs drain. The component ignores duplicate jobs and keeps one active maintenance schedule.

It is responsible for:

• compacting raw rows into rollups when they age out of a raw tier
• compacting finer rollups into coarser rollups when an older tier uses larger buckets
• deleting data older than the final tier

If you disable maintenance, new writes still go to the correct tier for their current age, but older already-stored data is no longer guaranteed to migrate or delete on schedule.

Useful patterns

Keep raw forever:

{
  tiers: [{ kind: "raw", fromAge: "0m", toAge: null }],
}

Keep raw 24h, then 30-minute rollups until day 7, then delete:

{
  provider: "garmin",
  seriesType: "heart_rate",
  tiers: [
    { kind: "raw", fromAge: "0m", toAge: "24h" },
    { kind: "rollup", fromAge: "24h", toAge: "7d", bucket: "30m" },
  ],
}

Store rollups only, never raw:

{
  provider: "garmin",
  seriesType: "oxygen_saturation",
  tiers: [
    {
      kind: "rollup",
      fromAge: "0m",
      toAge: null,
      bucket: "5m",
      aggregations: ["avg", "last", "count"],
    },
  ],
}