Caching API

Use Embeddable’s Caching API to tell Embeddable which security contexts need refreshing. The refresh frequency comes from the refresh_key you set in your pre-aggregations within the data model.

fetch('https://api.<region>.embeddable.com/api/v1/caching/refresh-contexts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}` // Keep your API key secure
  },
  body: JSON.stringify({
    embeddables: [
      {
        embeddableId: "4beec55e-11f5-489a-8417-eb77c6a3c6c3",
        savedVersions: ["production"]  // If not provided, the latest saved version will be used by default
      }
    ],
    scheduledRefreshContexts: [
      {
        securityContext: {
          userId: '9sZSJ9LHsiYXR0cmli'
        },
        environment: 'default',
        timezones: ['UTC']
      },
      {
        securityContext: {
          userId: 'HsiYXR0cmli9sZSJ9L'
        },
        environment: 'prod'
      }
    ],
    roles: ['default']
  })
});
 
Response:
Status 204 (No Content)

💡

The savedVersion value for a given dashboard tells Embeddable which models and cube version it should use when refreshing pre-aggregations (e.g. it will use those tagged as “production”)

region: your deployment region (learn more).
apiKey: your API key
embeddables: (required) a list of Embeddables to refresh. Each object must contain:
- id: the unique identifier of the Embeddable dashboard.
- savedVersions: (optional) an array of saved versions to refresh. If not provided, the latest saved version will be used by default.
securityContext: a JSON object passed to your data models to enforce row-level security. When setting up scheduled refreshes for pre-aggregations, provide a list of securityContext objects to the scheduledRefreshContexts array in the API. This ensures Cube can generate the required security contexts before running the refresh. Learn more here (opens in a new tab).
environment: the environment (e.g. staging / prod, or a specific database for a single-tenant set up), pre-defined using our Environments API.
timezone is the timezone you want the pre-aggregation to be built for. When your components call loadData, they can only use pre-aggregations that match their timezone. Timezone must be a string in tz database format (opens in a new tab), e.g. 'America/Los_Angeles', 'Europe/Paris', 'Australia/Sydney', 'UTC', etc. Defaults to 'UTC' if omitted.

If you load a dashboard using a security token containing a security context that has not been configured via the Caching API, no cache will be available for that dashboard. Cube will therefore build the requested pre-aggregation on-demand, which may take some time.

💡

Non-scheduled security contexts are built once. Cube won’t refresh them or check their refresh keys.

Each time you call this it will override the previous settings. For example, if you want to stop a security context from refreshing, just call the API again with all security contexts except the one you want to stop.

Pre-aggregations Intro to development