cache-function-results

name	cache-function-results
description	Add caching to Datagrok functions using meta.cache annotations
when-to-use	When user asks to cache function results, add memoization, or optimize repeated computations
effort	low

Cache Function Results

Help the user add caching to Datagrok functions to improve performance by storing results for repeated calls with the same inputs.

Usage

/cache-function-results [function-name] [--mode <client|server|all>]

Instructions

1. Choose the cache mode

Add meta.cache annotation to the function header:

• client — stores results in the browser's IndexedDB
• server — stores results on the Datagrok server
• all — uses both client and server caches together

2. Add caching to a TypeScript/JavaScript function

//name: Get Users
//meta.cache: all
//meta.cache.invalidateOn: 0 0 * * *
//output: dataframe result
export async function getUsers(): Promise<DG.DataFrame> {
  // Expensive operation — results will be cached
}

3. Add caching to a Python/R script

#name: Example
#language: python
#meta.cache: client
#meta.cache.invalidateOn: 0 * * * *
#input: string table [Data table]
#output: int result

...

4. Add caching to a SQL query

--name: ActivityDetails
--connection: Chembl
--meta.cache: all
--meta.cache.invalidateOn: 0 0 * * *
--input: string target = "CHEMBL1827"
SELECT * FROM activity_details WHERE target_id = @target
--end

5. Set cache invalidation

Use meta.cache.invalidateOn with a cron expression to control when cached results expire:

Cron expression	Meaning
0 * * * *	Every hour
0 0 * * *	Every day at midnight
0 0 * * 1	Every Monday at midnight
0 0 1 * *	First day of each month

If meta.cache.invalidateOn is not specified, the cache never expires automatically.

6. Cache all queries under a connection

Instead of annotating each query, enable caching at the connection level:

Via UI: Right-click the connection > Edit... > check Cache Results and optionally fill Invalidate On.

Via connection JSON:

{
  "name": "Northwind",
  "parameters": {
    "server": "db.example.com",
    "port": 5432,
    "db": "mydb",
    "cacheResults": true,
    "cacheSchema": false
  }
}

7. Client-side cache limits

• Function output must be scalar (int, float, string) or dataframe, graphics, datetime
• Maximum cache size per function: 100 MB
• Maximum record count: 100,000
• Users enable it in Settings > Cache > Client-side cache

8. Server-side cache

• No restrictions on size or parameter types
• Users enable it in Settings > Cache > Server-side cache
• Works together with client-side cache when mode is all

Behavior

• Default to meta.cache: all unless the user specifies a preference.
• Always suggest adding meta.cache.invalidateOn with an appropriate schedule — warn that without it the cache never refreshes.
• Only recommend caching for functions that are immutable (same input produces same output).
• Warn against caching database queries when the underlying data changes frequently.
• For connection-level caching, mention that it applies to all queries under that connection.