perf: Debounce information schema queries to Cube Store (1.8x) (#9879)

Introduces the @AsyncDebounce decorator to debounce promises for the getTablesQuery and getPrefixTablesQuery methods. This prevents redundant concurrent executions of the same operations, improving performance by avoiding duplicate database metadata queries.

For the performance benchmark, I've used 1 cube with 1 pre-agg that has 10 partitions, partitioned by time dimension with year granularity.

Previously, Cube would run 10 queries for the information schema while loading pre-aggregation.

### (average across runs)
•	Throughput almost doubled – from ~112 req/s (max 144) to ~206 req/s (max 229).
•	Average latency halved – from ~0.98 s to ~0.54 s.
•	p95 latency dropped from ~2.19 s to ~0.91 s.
•	Fast responses (<1 s) surged from ~57% to ~95%, with some runs hitting 100%.
•	Success rate improved from ~86% to ~98%, reaching 100% in the best runs.
•	Max latency fell from peaks of ~4.06 s to just ~2.05 s.

Author: ovr

packages/cubejs-backend-shared/CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Package Overview
+
+The `@cubejs-backend/shared` package contains shared utilities, types, and helper functions used across all Cube backend packages. This package provides core functionality like environment configuration, promise utilities, decorators, and common data types.
+
+## Development Commands
+
+**Note: This project uses Yarn as the package manager.**
+
+```bash
+# Build the package
+yarn build
+
+# Build with TypeScript compilation
+yarn tsc
+
+# Watch mode for development
+yarn watch
+
+# Run unit tests
+yarn unit
+
+# Run linting
+yarn lint
+
+# Fix linting issues
+yarn lint:fix
+```
+
+## Architecture Overview
+
+### Core Components
+
+The shared package is organized into several key modules:
+
+1. **Environment Configuration** (`src/env.ts`): Centralized environment variable management with type safety and validation
+2. **Promise Utilities** (`src/promises.ts`): Async helpers including debouncing, memoization, cancellation, and retry logic
+3. **Decorators** (`src/decorators.ts`): Method decorators for cross-cutting concerns like async debouncing
+4. **Type Helpers** (`src/type-helpers.ts`): Common TypeScript utility types used across packages
+5. **Time Utilities** (`src/time.ts`): Date/time manipulation and formatting functions
+6. **Process Utilities** (`src/process.ts`): Process management and platform detection

packages/cubejs-backend-shared/package.json

@@ -43,6 +43,7 @@
     "env-var": "^6.3.0",
     "fs-extra": "^9.1.0",
     "https-proxy-agent": "^7.0.6",
+    "lru-cache": "^11.1.0",
     "moment-range": "^4.0.2",
     "moment-timezone": "^0.5.47",
     "node-fetch": "^2.6.1",

packages/cubejs-backend-shared/src/decorators.ts

@@ -0,0 +1,26 @@
+import { asyncDebounceFn, AsyncDebounceOptions } from './promises';
+
+export function AsyncDebounce(options: AsyncDebounceOptions = {}) {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor => {
+    const originalMethod = descriptor.value;
+
+    return {
+      configurable: true,
+      get() {
+        const debouncedMethod = asyncDebounceFn(originalMethod.bind(this), options);
+
+        Object.defineProperty(this, propertyKey, {
+          value: debouncedMethod,
+          configurable: true,
+          writable: false
+        });
+
+        return debouncedMethod;
+      }
+    };
+  };
+}

packages/cubejs-backend-shared/src/index.ts

@@ -20,3 +20,4 @@ export * from './time';
 export * from './process';
 export * from './platform';
 export * from './FileRepository';
+export * from './decorators';

packages/cubejs-backend-shared/src/promises.ts

@@ -1,5 +1,6 @@
 /* eslint-disable arrow-body-style,no-restricted-syntax */
 import crypto from 'crypto';
+import { LRUCache } from 'lru-cache';
 
 import { Optional } from './type-helpers';
 
@@ -264,28 +265,35 @@ export const retryWithTimeout = <T>(
     timeout
   );
 
-/**
- * Creates a debounced version of an asynchronous function.
- */
-export const asyncDebounce = <Ret, Arguments>(
+export type AsyncDebounceOptions = {
+  max?: number;
+  ttl?: number;
+};
+
+export const asyncDebounceFn = <Ret, Arguments>(
   fn: (...args: Arguments[]) => Promise<Ret>,
+  options: AsyncDebounceOptions = {}
 ) => {
-  const cache = new Map<string, Promise<Ret>>();
+  const { max = 100, ttl = 60 * 1000 } = options;
+
+  const cache = new LRUCache<string, Promise<Ret>>({
+    max,
+    ttl,
+  });
 
   return async (...args: Arguments[]) => {
     const key = crypto.createHash('md5')
       .update(args.map((v) => JSON.stringify(v)).join(','))
       .digest('hex');
 
-    if (cache.has(key)) {
-      return <Promise<Ret>>cache.get(key);
+    const existing = cache.get(key);
+    if (existing) {
+      return existing;
     }
 
     try {
       const promise = fn(...args);
-
       cache.set(key, promise);
-
       return await promise;
     } finally {
       cache.delete(key);
@@ -309,7 +317,7 @@ export const asyncMemoize = <Ret, Arguments>(
 ) => {
   const cache = new Map<string, MemoizeBucket<Ret>>();
 
-  const debouncedFn = asyncDebounce(fn);
+  const debouncedFn = asyncDebounceFn(fn);
 
   const call = async (...args: Arguments[]) => {
     const key = options.extractKey(...args);
@@ -372,7 +380,7 @@ export const asyncMemoizeBackground = <Ret, Arguments>(
 ) => {
   const cache = new Map<string, BackgroundMemoizeBucket<Ret, Arguments>>();
 
-  const debouncedFn = asyncDebounce(fn);
+  const debouncedFn = asyncDebounceFn(fn);
 
   const refreshBucket = async (bucket: BackgroundMemoizeBucket<Ret, Arguments>) => {
     try {

packages/cubejs-backend-shared/test/decorators.test.ts

@@ -0,0 +1,19 @@
+import { AsyncDebounce } from '../src';
+
+describe('AsyncDebounce decorator', () => {
+  test('should preserve this context', async () => {
+    class TestClass {
+      private value = 'test-value';
+
+      @AsyncDebounce()
+      public async getValue() {
+        return this.value;
+      }
+    }
+
+    const instance = new TestClass();
+    const result = await instance.getValue();
+
+    expect(result).toBe('test-value');
+  });
+});

packages/cubejs-backend-shared/test/promises.test.ts

@@ -5,7 +5,10 @@ import {
   retryWithTimeout,
   withTimeout,
   withTimeoutRace,
-  asyncMemoize, asyncRetry, asyncDebounce, asyncMemoizeBackground,
+  asyncMemoize,
+  asyncRetry,
+  asyncDebounceFn,
+  asyncMemoizeBackground,
 } from '../src';
 
 test('createCancelablePromise', async () => {
@@ -453,7 +456,7 @@ describe('asyncDebounce', () => {
   test('multiple async calls to single', async () => {
     let called = 0;
 
-    const doOnce = asyncDebounce(
+    const doOnce = asyncDebounceFn(
       async (arg1: string, arg2: string) => {
         called++;
 

packages/cubejs-cubestore-driver/src/CubeStoreDriver.ts

@@ -14,7 +14,7 @@ import {
   QueryOptions,
   ExternalDriverCompatibilities, TableStructure, TableColumnQueryResult,
 } from '@cubejs-backend/base-driver';
-import { getEnv } from '@cubejs-backend/shared';
+import { AsyncDebounce, getEnv } from '@cubejs-backend/shared';
 import { format as formatSql, escape } from 'sqlstring';
 import fetch from 'node-fetch';
 
@@ -158,13 +158,15 @@ export class CubeStoreDriver extends BaseDriver implements DriverInterface {
     });
   }
 
+  @AsyncDebounce()
   public async getTablesQuery(schemaName) {
     return this.query(
       `SELECT table_name, build_range_end FROM information_schema.tables WHERE table_schema = ${this.param(0)}`,
       [schemaName]
     );
   }
 
+  @AsyncDebounce()
   public async getPrefixTablesQuery(schemaName, tablePrefixes) {
     const prefixWhere = tablePrefixes.map(_ => 'table_name LIKE CONCAT(?, \'%\')').join(' OR ');
     return this.query(

packages/cubejs-cubestore-driver/tsconfig.json

@@ -9,6 +9,6 @@
     "noImplicitAny": false,
     "outDir": "dist",
     "rootDir": ".",
-    "baseUrl": ".",
+    "baseUrl": "."
   }
 }

packages/cubejs-query-orchestrator/src/orchestrator/PreAggregationLoadCache.ts

@@ -97,9 +97,11 @@ export class PreAggregationLoadCache {
     const client = preAggregation.external ?
       await this.externalDriverFactory() :
       await this.driverFactory();
+
     if (this.tablePrefixes && client.getPrefixTablesQuery && this.preAggregations.options.skipExternalCacheAndQueue) {
       return client.getPrefixTablesQuery(preAggregation.preAggregationsSchema, this.tablePrefixes);
     }
+
     return client.getTablesQuery(preAggregation.preAggregationsSchema);
   }