---
title: "Create Cache"
method: POST
path: "/data/projects/{projectId}/cache"
tags: ["Data -- Cache"]
---

# Create Cache

`POST /data/projects/{projectId}/cache`

## Request

- Base URL: `https://partner.peaka.studio/api/v1`
- URL: `https://partner.peaka.studio/api/v1/data/projects/{projectId}/cache`
- Auth: HTTP bearer

Creates a new cache for a specific table in a catalog. Caching copies data from an external data source into the internal Peaka BigTable store for faster query performance.

Not every table can be cached: check `isCacheable` and `supportedCacheTypes` in the List Tables response before creating a cache. `supportedCacheTypes` tells which of the modes below are available for the table (`FULL_REFRESH`, `INCREMENTAL`).

The cache can be configured in three modes:
- **One-time cache**: No schedules provided. Data is cached once during creation and never automatically refreshed.
- **Scheduled incremental updates**: Provide `incrementalCacheSchedule` to periodically sync only the changes (inserts, updates, deletes) since the last sync.
- **Scheduled full refresh + incremental**: Provide both `fullRefreshCacheSchedule` and `incrementalCacheSchedule`.   Full refresh drops and rebuilds the entire cached table periodically, while incremental updates run more frequently between full refreshes.

After creation, the initial sync is triggered automatically based on the provided schedules. If only an incremental schedule is given, an incremental sync starts immediately. If a full refresh schedule is given, a full refresh starts immediately.

The schedule `expression` uses ISO-8601 duration format (e.g. `PT6H` = every 6 hours, `PT15M` = every 15 minutes, `P1D` = every day).

## Path parameters

- `projectId` string, required

## Request body

- CacheRequest: This class represents a request to cache data. It contains the catalog ID, schema name, table name, and schedule of the cache request.
  - `catalogId` string: The ID of the catalog for the cache request.
  - `schemaName` string: The name of the schema for the cache request.
  - `tableName` string: The name of the table for the cache request.
  - `incrementalCacheSchedule` Schedule: This class represents a schedule for a cache request. It contains the type and expression of the schedule.
    - `type` string: The type of the schedule. BASIC or NONE.
    - `expression` string: The expression of the schedule. Valid if the type is other than NONE. For BASIC, the expression is a duration in ISO-8601 format. "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
  - `fullRefreshCacheSchedule` Schedule: This class represents a schedule for a cache request. It contains the type and expression of the schedule.
    - `type` string: The type of the schedule. BASIC or NONE.
    - `expression` string: The expression of the schedule. Valid if the type is other than NONE. For BASIC, the expression is a duration in ISO-8601 format. "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds)

## Response `200`

Cache created successfully. Returns the created cache configuration including its generated ID and schedules.

## Other responses

- `400`: Invalid request. The catalog, schema, or table may not exist, or the schedule expression is invalid. When the table is not cacheable (`isCacheable: false` in the table metadata), the error body carries `errorCode: TABLE_NOT_CACHEABLE`.
- `409`: A cache already exists for this table.

---

[API](https://skmtc.dev/peaka/apis/peaka-gateway-api.md) · [All operations](https://skmtc.dev/peaka/apis/peaka-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peaka/apis/peaka-gateway-api/revisions/e68b033a22d5?raw)