feat: Support custom numeric formatting (#10213)

Author: ovr

packages/cubejs-api-gateway/openspec.yml

@@ -305,12 +305,27 @@ components:
       required:
         - type
         - value
+    V1CubeMetaCustomNumericFormat:
+      type: "object"
+      description: Custom numeric format for numeric measures and dimensions
+      properties:
+        type:
+          type: "string"
+          enum: ["custom-numeric"]
+          description: Type of the format (must be 'custom-numeric')
+        value:
+          type: "string"
+          description: "d3-format specifier string (e.g., '.2f', ',.0f', '$,.2f', '.0%', '.2s'). See https://d3js.org/d3-format"
+      required:
+        - type
+        - value
     V1CubeMetaFormat:
       oneOf:
         - $ref: "#/components/schemas/V1CubeMetaSimpleFormat"
         - $ref: "#/components/schemas/V1CubeMetaLinkFormat"
         - $ref: "#/components/schemas/V1CubeMetaCustomTimeFormat"
-      description: Format of dimension - can be a simple string format, a link configuration, or a custom time format
+        - $ref: "#/components/schemas/V1CubeMetaCustomNumericFormat"
+      description: Format of measure or dimension - can be a simple string format, a link configuration, a custom time format, or a custom numeric format
     V1MetaResponse:
       type: "object"
       properties:

packages/cubejs-client-core/src/types.ts

@@ -16,9 +16,11 @@ export type GranularityAnnotation = {
 };
 
 export type DimensionCustomTimeFormat = { type: 'custom-time'; value: string };
+export type CustomNumericFormat = { type: 'custom-numeric'; value: string };
 export type DimensionLinkFormat = { type: 'link'; label: string };
 export type DimensionFormat = 'percent' | 'currency' | 'number' | 'imageUrl' | 'id' | 'link'
-  | DimensionLinkFormat | DimensionCustomTimeFormat;
+  | DimensionLinkFormat | DimensionCustomTimeFormat | CustomNumericFormat;
+export type MeasureFormat = 'percent' | 'currency' | 'number' | CustomNumericFormat;
 
 export type Annotation = {
   title: string;

packages/cubejs-schema-compiler/src/compiler/CubeToMetaTransformer.ts

@@ -19,6 +19,12 @@ import type { JoinGraph } from './JoinGraph';
 import type { ErrorReporter } from './ErrorReporter';
 import { CompilerInterface } from './PrepareCompiler';
 
+export type CustomNumericFormat = { type: 'custom-numeric'; value: string };
+export type DimensionCustomTimeFormat = { type: 'custom-time'; value: string };
+export type DimensionLinkFormat = { type: 'link'; label?: string };
+export type DimensionFormat = string | DimensionLinkFormat | DimensionCustomTimeFormat | CustomNumericFormat;
+export type MeasureFormat = string | CustomNumericFormat;
+
 // Extended types for cube symbols with all runtime properties
 export interface ExtendedCubeSymbolDefinition extends CubeSymbolDefinition {
   description?: string;
@@ -61,7 +67,7 @@ export type MeasureConfig = {
   title: string;
   description?: string;
   shortTitle: string;
-  format?: string;
+  format?: MeasureFormat;
   cumulativeTotal: boolean;
   cumulative: boolean;
   type: string;
@@ -77,10 +83,6 @@ export type MeasureConfig = {
   public: boolean;
 };
 
-export type DimensionCustomTimeFormat = { type: 'custom-time'; value: string };
-export type DimensionLinkFormat = { type: 'link'; label?: string };
-export type DimensionFormat = string | DimensionLinkFormat | DimensionCustomTimeFormat;
-
 export type DimensionConfig = {
   name: string;
   title: string;
@@ -372,7 +374,7 @@ export class CubeToMetaTransformer implements CompilerInterface {
       title: this.title(cubeTitle, nameToMetric, false),
       description: extendedMetricDef.description,
       shortTitle: this.title(cubeTitle, nameToMetric, true),
-      format: extendedMetricDef.format,
+      format: this.transformMeasureFormat(extendedMetricDef.format),
       cumulativeTotal: isCumulative,
       cumulative: isCumulative,
       type,
@@ -396,21 +398,39 @@ export class CubeToMetaTransformer implements CompilerInterface {
   }
 
   private transformDimensionFormat({ format, type }: ExtendedCubeSymbolDefinition): DimensionFormat | undefined {
-    if (!format || type !== 'time') {
+    if (!format || typeof format === 'object') {
       return format;
     }
 
-    if (typeof format === 'object') {
+    const standardFormats = ['imageUrl', 'currency', 'percent', 'number', 'id'];
+    if (standardFormats.includes(format)) {
       return format;
     }
 
-    // I don't know why, but we allow to define these formats for time dimensions.
-    // TODO: Should we deprecate it?
-    const standardFormats = ['imageUrl', 'currency', 'percent', 'number', 'id'];
+    // Custom time format for time dimensions
+    if (type === 'time') {
+      return { type: 'custom-time', value: format };
+    }
+
+    // Custom numeric format for number dimensions
+    if (type === 'number') {
+      return { type: 'custom-numeric', value: format };
+    }
+
+    return format;
+  }
+
+  private transformMeasureFormat(format: string | undefined): MeasureFormat | undefined {
+    if (!format) {
+      return undefined;
+    }
+
+    const standardFormats = ['percent', 'currency', 'number'];
     if (standardFormats.includes(format)) {
       return format;
     }
 
-    return { type: 'custom-time', value: format };
+    // Custom numeric format
+    return { type: 'custom-numeric', value: format };
   }
 }

packages/cubejs-schema-compiler/src/compiler/CubeValidator.ts

@@ -182,6 +182,82 @@ const timeFormatSchema = Joi.alternatives([
   customTimeFormatSchema
 ]);
 
+// d3-format specification (Python format spec mini-language)
+// See: https://d3js.org/d3-format
+// See: https://docs.python.org/3/library/string.html#format-specification-mini-language
+// Format specifier: [[fill]align][sign][symbol][0][width][,][.precision][~][type]
+const NUMERIC_FORMAT_TYPES = new Set([
+  'e', // exponent notation
+  'f', // fixed-point notation
+  'g', // either decimal or exponent notation
+  'r', // decimal notation, rounded to significant digits
+  's', // decimal notation with an SI prefix
+  '%', // multiply by 100 and format as percentage
+  'p', // multiply by 100, round to significant digits, and format as percentage
+  'b', // binary notation
+  'o', // octal notation
+  'd', // decimal notation (integer)
+  'x', // lowercase hexadecimal notation
+  'X', // uppercase hexadecimal notation
+  'c', // character data
+  'n', // like g, but with locale-specific thousand separator
+]);
+
+// d3-format specifier: [[fill]align][sign][symbol][0][width][,][.precision][~][type]
+// Regex breakdown:
+// (?:(.)?([<>=^]))?           - optional fill (any char) + align (<>=^)
+// ([+\-( ])?                  - optional sign (+, -, (, or space)
+// ([$#])?                     - optional symbol ($ or #)
+// (0)?                        - optional zero flag
+// (\d+)?                      - optional width (positive integer)
+// (,)?                        - optional comma flag (grouping)
+// (?:\.(\d+))?                - optional precision (.N where N is non-negative integer)
+// (~)?                        - optional tilde (trim insignificant zeros)
+// ([a-zA-Z%])?                - optional type character
+const NUMERIC_FORMAT_REGEX = /^(?:(.)?([<>=^]))?([+\-( ])?([$#])?(0)?(\d+)?(,)?(?:\.(\d+))?(~)?([a-zA-Z%])?$/;
+
+const customNumericFormatSchema = Joi.string().custom((value, helper) => {
+  const match = value.match(NUMERIC_FORMAT_REGEX);
+  if (!match) {
+    return helper.message({
+      custom: `Invalid numeric format "${value}". Must be a valid d3-format specifier (e.g., ".2f", ",.0f", "$,.2f", ".0%", ".2s")`
+    });
+  }
+
+  const [, fill, align, sign, symbol, zero, width, comma, precision, tilde, type] = match;
+
+  if (fill && !align) {
+    return helper.message({
+      custom: `Invalid numeric format "${value}". Fill character requires alignment specifier (<, >, =, or ^)`
+    });
+  }
+
+  if (type && !NUMERIC_FORMAT_TYPES.has(type.toLowerCase())) {
+    return helper.message({
+      custom: `Invalid numeric format "${value}". Unknown type character '${type}'. Valid types: ${[...NUMERIC_FORMAT_TYPES].join(', ')}`
+    });
+  }
+
+  // Validate that the format is not empty (must have at least something meaningful)
+  if (!sign && !symbol && !zero && !width && !comma && precision === undefined && !tilde && !type) {
+    return helper.message({
+      custom: `Invalid numeric format "${value}". Format must contain at least one specifier (e.g., type, precision, comma, sign, symbol)`
+    });
+  }
+
+  return value;
+});
+
+const measureFormatSchema = Joi.alternatives([
+  Joi.string().valid('percent', 'currency', 'number'),
+  customNumericFormatSchema
+]);
+
+const dimensionNumericFormatSchema = Joi.alternatives([
+  formatSchema,
+  customNumericFormatSchema
+]);
+
 const BaseDimensionWithoutSubQuery = {
   aliases: Joi.array().items(Joi.string()),
   type: Joi.any().valid('string', 'number', 'boolean', 'time', 'geo').required(),
@@ -195,8 +271,10 @@ const BaseDimensionWithoutSubQuery = {
   suggestFilterValues: Joi.boolean().strict(),
   enableSuggestions: Joi.boolean().strict(),
   format: Joi.when('type', {
-    is: 'time',
-    then: timeFormatSchema,
+    switch: [
+      { is: 'time', then: timeFormatSchema },
+      { is: 'number', then: dimensionNumericFormatSchema },
+    ],
     otherwise: formatSchema
   }),
   meta: Joi.any(),
@@ -302,7 +380,7 @@ const ToDate = {
 
 const BaseMeasure = {
   aliases: Joi.array().items(Joi.string()),
-  format: Joi.any().valid('percent', 'currency', 'number'),
+  format: measureFormatSchema,
   public: Joi.boolean().strict(),
   // TODO: Deprecate and remove, please use public
   visible: Joi.boolean().strict(),