> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaka.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Cache
> 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.
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).
## OpenAPI
````yaml post /data/projects/{projectId}/cache
openapi: 3.0.1
info:
title: Peaka Gateway API
description: Peaka Gateway API Documentation
version: '1.0'
servers:
- url: https://partner.peaka.studio/api/v1
description: Default Server URL (US Zone)
- url: https://partner.eu.peaka.studio/api/v1
description: EU Zone
security:
- bearerAuth: []
paths:
/data/projects/{projectId}/cache:
post:
tags:
- Data -- Cache
summary: Create Cache
description: >-
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.
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).
operationId: createCache
parameters:
- name: projectId
in: path
description: The unique identifier of the project that owns the data source
required: true
schema:
type: string
example: mtKDhe1U
requestBody:
description: >-
Cache creation request specifying the target table and optional sync
schedules
content:
application/json:
schema:
$ref: '#/components/schemas/CacheRequest'
examples:
One-Time Cache:
description: >-
Creates a cache with no automatic refresh. Data is synced once
at creation time.
value:
id: 960bd651-7b3c-4511-9a88-18e14ac7742a
catalogId: '627249916703408649'
schemaName: payment
tableName: customers
Incremental Schedule Only:
description: >-
Creates a cache that incrementally syncs changes every 6
hours. Only new/updated/deleted rows since the last sync are
processed.
value:
id: 960bd651-7b3c-4511-9a88-18e14ac7742a
catalogId: '627249916703408649'
schemaName: payment
tableName: customers
incrementalCacheSchedule:
type: BASIC
expression: PT6H
Full Refresh + Incremental Schedule:
description: >-
Creates a cache with both schedules. Incremental sync runs
every 6 hours for fast delta updates, and a full refresh
rebuilds the entire cache every 24 hours to ensure
consistency.
value:
id: 960bd651-7b3c-4511-9a88-18e14ac7742a
catalogId: '627249916703408649'
schemaName: payment
tableName: customers
fullRefreshCacheSchedule:
type: BASIC
expression: PT24H
incrementalCacheSchedule:
type: BASIC
expression: PT6H
required: true
responses:
'200':
description: >-
Cache created successfully. Returns the created cache configuration
including its generated ID and schedules.
content:
'*/*':
schema:
$ref: '#/components/schemas/Cache'
'400':
description: >-
Invalid request. The catalog, schema, or table may not exist, or the
schedule expression is invalid.
content:
'*/*':
schema:
$ref: '#/components/schemas/Cache'
'409':
description: A cache already exists for this table.
content:
'*/*':
schema:
$ref: '#/components/schemas/Cache'
components:
schemas:
CacheRequest:
type: object
properties:
catalogId:
type: string
description: The ID of the catalog for the cache request.
schemaName:
type: string
description: The name of the schema for the cache request.
tableName:
type: string
description: The name of the table for the cache request.
incrementalCacheSchedule:
$ref: '#/components/schemas/Schedule'
fullRefreshCacheSchedule:
$ref: '#/components/schemas/Schedule'
description: |-
This class represents a request to cache data.
It contains the catalog ID, schema name, table name, and schedule of the cache request.
Cache:
type: object
properties:
id:
type: string
description: The ID of the cache.
catalogId:
type: string
description: The ID of the catalog for the cache request.
schemaName:
type: string
description: The name of the schema for the cache request.
tableName:
type: string
description: The name of the table for the cache request.
incrementalCacheSchedule:
$ref: '#/components/schemas/Schedule'
fullRefreshCacheSchedule:
$ref: '#/components/schemas/Schedule'
appId:
type: string
writeOnly: true
projectId:
type: string
description: The ID of the project for the cache request.
Schedule:
type: object
properties:
type:
type: string
description: The type of the schedule. BASIC or NONE.
expression:
type: string
description: |-
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)
description: |-
This class represents a schedule for a cache request.
It contains the type and expression of the schedule.
securitySchemes:
bearerAuth:
type: http
description: >-
Use the Authorization header with the value 'Bearer ' to
authenticate. Partner API Keys have full access; Project API Keys are
limited to their project scope. Learn more:
https://docs.peaka.com/api-reference/authentication
scheme: bearer
bearerFormat: Api Key
````