The JSON type stores arbitrary JSON data, supporting both unstructured and typed configurations for performance and type safety.
For completely dynamic JSON data without a fixed schema:
interface Event { metadata: Record<string, any>; // Basic JSON - accepts any structure config: any; // Basic JSON - fully dynamic}For better performance and validation, define typed fields within your JSON using ClickHouseJson. This creates a ClickHouse JSON column with explicit type hints for specific paths while still allowing additional dynamic fields.
import { ClickHouseJson } from "@514labs/moose-lib"; // Define the structure for your JSON payloadinterface PayloadStructure { name: string; count: number; timestamp?: Date;} interface Event { id: string; // JSON with typed paths - better performance, allows extra fields payload: PayloadStructure & ClickHouseJson;}Configure ClickHouseJson with options to control resource usage:
import { ClickHouseJson, Key, DateTime } from "@514labs/moose-lib"; interface ProductProperties { category: string; price: number; inStock: boolean;} interface ProductEvent { eventId: Key<string>; timestamp: DateTime; properties: ProductProperties & ClickHouseJson< 128, // max_dynamic_paths: limit tracked paths 8, // max_dynamic_types: limit type variations ["_internal"], // skip_paths: exclude specific paths ["^debug_"] // skip_regexps: exclude paths matching regex >;}import { ClickHouseJson, Key, DateTime } from "@514labs/moose-lib"; interface ProductProperties { category: string; price: number; inStock: boolean;} interface ProductEvent { eventId: Key<string>; timestamp: DateTime; properties: ProductProperties & ClickHouseJson< 128, // max_dynamic_paths: limit tracked paths 8, // max_dynamic_types: limit type variations ["_internal"], // skip_paths: exclude specific paths ["^debug_"] // skip_regexps: exclude paths matching regex >;}| Option | Type | Description |
|---|---|---|
max_dynamic_paths | number | Maximum unique JSON paths to track. Controls memory for variable structures. |
max_dynamic_types | number | Maximum type variations per path. Useful when paths may contain different types. |
skip_paths | string[] | Exact JSON paths to ignore (e.g., ["temp", "debug.info"]). |
skip_regexps | string[] | Regex patterns for paths to exclude (e.g., ["^tmp\\.", ".*_internal$"]). |
With typed JSON, you get the best of both worlds—type safety for known fields and flexibility for dynamic data:
// This data is valid:{ "eventId": "evt_123", "timestamp": "2025-10-22T12:00:00Z", "properties": { "category": "electronics", // Typed field ✓ "price": 99.99, // Typed field ✓ "inStock": true, // Typed field ✓ "customTag": "holiday-sale", // Extra field - accepted ✓ "brandId": 42, // Extra field - accepted ✓ "_internal": "ignored" // Skipped by skip_paths ✓ }}any, Dict[str, Any]): Use when JSON structure is completely unknown or rarely queriedClickHouseJson): Use when you have known fields that need indexing/querying, but want to allow additional dynamic fields