From 65dab1202c756ea55c91f9f4abeb1d19a107b8f8 Mon Sep 17 00:00:00 2001
From: johancube <johan@cube.dev>
Date: Tue, 28 Oct 2025 17:22:14 +0300
Subject: [PATCH 1/2] feat(client-core): add CacheMode type

---
 packages/cubejs-client-core/src/index.ts |  9 ++++++++-
 packages/cubejs-client-core/src/types.ts | 25 ++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/cubejs-client-core/src/index.ts b/packages/cubejs-client-core/src/index.ts
index fe1e9d5019069..5e91a1e8a2899 100644
--- a/packages/cubejs-client-core/src/index.ts
+++ b/packages/cubejs-client-core/src/index.ts
@@ -6,6 +6,7 @@ import ProgressResult from './ProgressResult';
 import HttpTransport, { ErrorResponse, ITransport, TransportOptions } from './HttpTransport';
 import RequestError from './RequestError';
 import {
+  CacheMode,
   ExtractTimeMembers,
   LoadResponse,
   MetaResponse,
@@ -107,6 +108,10 @@ export type CubeSqlOptions = LoadMethodOptions & {
    * Query timeout in milliseconds
    */
   timeout?: number;
+  /**
+   * Cache mode for query execution
+   */
+  cache?: CacheMode;
 };
 
 export type CubeSqlSchemaColumn = {
@@ -711,6 +716,7 @@ class CubeApi {
       () => {
         const request = this.request('cubesql', {
           query: sqlQuery,
+          cache: options?.cache,
           method: 'POST',
           signal: options?.signal,
           fetchTimeout: options?.timeout
@@ -768,7 +774,8 @@ class CubeApi {
       fetchTimeout: options?.timeout,
       baseRequestId: uuidv4(),
       params: {
-        query: sqlQuery
+        query: sqlQuery,
+        cache: options?.cache
       }
     });
 
diff --git a/packages/cubejs-client-core/src/types.ts b/packages/cubejs-client-core/src/types.ts
index 400de81044e93..7f27a7a9f8d9c 100644
--- a/packages/cubejs-client-core/src/types.ts
+++ b/packages/cubejs-client-core/src/types.ts
@@ -526,3 +526,28 @@ export type ProgressResponse = {
   stage: string;
   timeElapsed: number;
 };
+
+/**
+ * Cache mode options for query execution.
+ *
+ * - **stale-if-slow** (default): Equivalent to previously used `renewQuery: false`.
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, tries to return the value from the database.
+ *   Returns fresh value from the database if the query executed until the first "Continue wait" interval is reached.
+ *   Returns stale value from cache otherwise.
+ *
+ * - **stale-while-revalidate**: AKA "backgroundRefresh".
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, returns stale data from cache.
+ *   Updates the cache in background.
+ *
+ * - **must-revalidate**: Equivalent to previously used `renewQuery: true`.
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, tries to return the value from the database.
+ *   Returns fresh value from the database even if it takes minutes and many "Continue wait" intervals.
+ *
+ * - **no-cache**: AKA "forceRefresh".
+ *   Skips refresh key checks.
+ *   Returns fresh data from the database, even if it takes minutes and many "Continue wait" intervals.
+ */
+export type CacheMode = 'stale-if-slow' | 'stale-while-revalidate' | 'must-revalidate' | 'no-cache';

From a8becbf2edc6780068f2d0801eedad30343f55c8 Mon Sep 17 00:00:00 2001
From: johancube <johan@cube.dev>
Date: Tue, 28 Oct 2025 18:16:44 +0300
Subject: [PATCH 2/2] feat(client-core): add synchronization comment for
 CacheMode type

---
 packages/cubejs-client-core/src/types.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/cubejs-client-core/src/types.ts b/packages/cubejs-client-core/src/types.ts
index 7f27a7a9f8d9c..db50bd61fcd59 100644
--- a/packages/cubejs-client-core/src/types.ts
+++ b/packages/cubejs-client-core/src/types.ts
@@ -527,6 +527,8 @@ export type ProgressResponse = {
   timeElapsed: number;
 };
 
+// NOTE: This type must be kept in sync with CacheMode in @cubejs-backend/shared (packages/cubejs-backend-shared/src/shared-types.ts)
+// This duplication is intentional as @cubejs-client/core does not depend on @cubejs-backend/shared
 /**
  * Cache mode options for query execution.
  *