Cache Behavior

Component reads support server-side caching. You control how fresh the response needs to be by passing a cacheTTL value (seconds) in your request.

cacheTTL value	Behaviour
> 0	Return a cached response if it is no older than cacheTTL seconds
0 (or omitted)	Always fetch fresh from the database

cacheTTL is seconds — buildTTL is minutes

The two TTL options sit next to each other in the same options object but use different units. cacheTTL: 60 means one minute; buildTTL: 60 means one hour.

Accepted range

Positive values are clamped to the range 5–300 seconds:

You pass	Effective TTL
0 or negative	0 — cache bypassed, fresh read
1–4	5s (clamped up)
5–300	used as-is
> 300	300s (clamped down)

Clamping is silent — no error is returned. If you need sub-5-second freshness, pass cacheTTL: 0 and read fresh.

Components

Pass cacheTTL in the options argument of find(), findOne(), or paginate():

import { Component } from '@ptkl/sdk/beta'

const products = new Component('products')

// Serve a cached result up to 60 seconds old.
const list = await products.find(
  { currentPage: 0, perPage: 20 },
  { cacheTTL: 60 }
)

// Force a fresh read — bypass the cache entirely.
const fresh = await products.find(
  { currentPage: 0, perPage: 20 },
  { cacheTTL: 0 }
)

// findOne respects cacheTTL the same way.
const item = await products.findOne(
  { $adv: { slug: 'my-product' } },
  { cacheTTL: 60 }
)

You can also limit which fields are returned with only:

const result = await products.find(
  { currentPage: 0, perPage: 20, only: ['name', 'price'] },
  { cacheTTL: 60 }
)

Note: only is supported on V4 component reads. V3 component reads do not support field projection.

Choosing a TTL

TTL range	Good for
5–30 s	Data that changes often but can tolerate brief staleness (live feeds, counters)
60–300 s	Reference data that rarely changes during a session (catalogues, settings)
0	Any read that must reflect the latest write (immediately after a mutation)

Restrictions

cacheTTL is silently ignored when the request includes unmaskPasswords: true — responses with plaintext credentials are never cached, read or written.

Direct API Usage

If you are calling the API without the SDK, pass X-Cache-Ttl as an HTTP header. The same 5–300 second clamping applies:

POST /v4/system/component/products/models HTTP/1.1
X-Cache-Ttl: 60
Content-Type: application/json

If both the options.cacheTTL body field and the X-Cache-Ttl header are present, the body value wins. The header is consulted only when the body value is absent or 0.

Thunder

Thunder reads accept an option with the same name, the same unit, and the same maximum-age meaning. Two differences remain:

	Components	Thunder
cacheTTL omitted	Same as 0 — fresh read	Serve any cached entry, regardless of age
Clamped	Yes, 5–300 s	No — any positive value is honoured
cacheTTL: 0	Bypass the cache, fresh read	Bypass the cache, fresh read

Thunder treats omission differently on purpose: it is a read-optimised store where nearly every caller omits the option, so making omission a cache bypass would send that entire population to the database. See Thunder → Read Options.