@dotdo/postgres 0.1.0

package/dist/iceberg/analytics.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Iceberg Historical Data Analytics
+ * Task: postgres-no1 - Historical data analytics feature
+ *
+ * Provides historical analytics capabilities for Iceberg tables:
+ * - Change rate analysis (inserts, updates, deletes over time)
+ * - Row count trends across snapshots
+ * - Data growth metrics and projections
+ * - Snapshot comparison and diff analysis
+ *
+ * @example
+ * ```typescript
+ * const analytics = createHistoricalAnalytics({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   catalog,
+ * })
+ *
+ * // Get change rates over a time period
+ * const changeRate = await analytics.getChangeRate(
+ *   tableId,
+ *   new Date('2024-01-01'),
+ *   new Date('2024-01-31')
+ * )
+ *
+ * // Get data growth metrics
+ * const growth = await analytics.getGrowthMetrics(tableId)
+ *
+ * // Compare two snapshots
+ * const comparison = await analytics.getSnapshotComparison(
+ *   tableId,
+ *   snapshotId1,
+ *   snapshotId2
+ * )
+ * ```
+ */
+import type { IcebergDataFile } from './types';
+import type { IcebergCatalog, TableIdentifier } from './catalog';
+import { type TimestampSpec } from './time-travel';
+/**
+ * Change rate analysis result
+ */
+export interface ChangeRateAnalysis {
+    /** Start timestamp of analysis period */
+    startTimestampMs: number;
+    /** End timestamp of analysis period */
+    endTimestampMs: number;
+    /** Duration of analysis period in milliseconds */
+    durationMs: number;
+    /** Total records added */
+    totalAdded: number;
+    /** Total records deleted */
+    totalDeleted: number;
+    /** Net change in records */
+    netChange: number;
+    /** Average records added per day */
+    addedPerDay: number;
+    /** Average records deleted per day */
+    deletedPerDay: number;
+    /** Average net change per day */
+    netChangePerDay: number;
+    /** Number of snapshots in period */
+    snapshotCount: number;
+    /** Snapshots analyzed */
+    snapshots: SnapshotChangeInfo[];
+}
+/**
+ * Information about changes in a specific snapshot
+ */
+export interface SnapshotChangeInfo {
+    /** Snapshot ID */
+    snapshotId: number;
+    /** Snapshot timestamp */
+    timestampMs: number;
+    /** Timestamp formatted as ISO string */
+    timestamp: string;
+    /** Records added in this snapshot */
+    recordsAdded: number;
+    /** Records deleted in this snapshot */
+    recordsDeleted: number;
+    /** Net change in this snapshot */
+    netChange: number;
+    /** Total records after this snapshot */
+    totalRecords: number;
+    /** Operation type */
+    operation: string;
+}
+/**
+ * Data growth metrics
+ */
+export interface GrowthMetrics {
+    /** Current total records */
+    currentRecordCount: number;
+    /** Current total data size in bytes */
+    currentDataSizeBytes: number;
+    /** Current number of data files */
+    currentFileCount: number;
+    /** Oldest snapshot timestamp */
+    oldestSnapshotMs: number | null;
+    /** Newest snapshot timestamp */
+    newestSnapshotMs: number | null;
+    /** Total time span in milliseconds */
+    timeSpanMs: number;
+    /** Average growth rate (records per day) */
+    avgRecordsPerDay: number;
+    /** Average data size growth (bytes per day) */
+    avgBytesPerDay: number;
+    /** Projected record count in 30 days */
+    projectedRecordsIn30Days: number;
+    /** Projected data size in 30 days (bytes) */
+    projectedBytesIn30Days: number;
+    /** Growth trend */
+    trend: 'growing' | 'shrinking' | 'stable';
+    /** Historical data points */
+    history: GrowthDataPoint[];
+}
+/**
+ * Growth data point at a specific time
+ */
+export interface GrowthDataPoint {
+    /** Snapshot ID */
+    snapshotId: number;
+    /** Timestamp */
+    timestampMs: number;
+    /** Timestamp formatted */
+    timestamp: string;
+    /** Total records at this point */
+    recordCount: number;
+    /** Total data size at this point */
+    dataSizeBytes: number;
+    /** Number of files at this point */
+    fileCount: number;
+}
+/**
+ * Snapshot comparison result
+ */
+export interface SnapshotComparison {
+    /** First snapshot info */
+    snapshot1: SnapshotComparisonInfo;
+    /** Second snapshot info */
+    snapshot2: SnapshotComparisonInfo;
+    /** Time difference in milliseconds */
+    timeDifferenceMs: number;
+    /** Record count difference (snapshot2 - snapshot1) */
+    recordCountDelta: number;
+    /** Data size difference in bytes (snapshot2 - snapshot1) */
+    dataSizeDelta: number;
+    /** File count difference (snapshot2 - snapshot1) */
+    fileCountDelta: number;
+    /** Files added between snapshots */
+    filesAdded: IcebergDataFile[];
+    /** Files deleted between snapshots */
+    filesDeleted: IcebergDataFile[];
+    /** Files that exist in both snapshots */
+    filesUnchanged: IcebergDataFile[];
+    /** Summary statistics */
+    summary: {
+        /** Percentage change in record count */
+        recordCountChangePercent: number;
+        /** Percentage change in data size */
+        dataSizeChangePercent: number;
+        /** Average file size in snapshot 1 */
+        avgFileSizeSnapshot1: number;
+        /** Average file size in snapshot 2 */
+        avgFileSizeSnapshot2: number;
+    };
+}
+/**
+ * Snapshot info for comparison
+ */
+export interface SnapshotComparisonInfo {
+    /** Snapshot ID */
+    snapshotId: number;
+    /** Snapshot timestamp */
+    timestampMs: number;
+    /** Timestamp formatted */
+    timestamp: string;
+    /** Total records */
+    recordCount: number;
+    /** Total data size */
+    dataSizeBytes: number;
+    /** Number of files */
+    fileCount: number;
+    /** Operation type */
+    operation: string;
+}
+/**
+ * Historical analytics configuration
+ */
+export interface HistoricalAnalyticsConfig {
+    /** R2 bucket for reading data */
+    bucket: R2Bucket;
+    /** Iceberg catalog instance */
+    catalog: IcebergCatalog;
+    /** Default retention window for analytics (default: 90 days) */
+    retentionWindowMs?: number;
+    /** Enable caching of analysis results (default: true) */
+    enableCache?: boolean;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtlMs?: number;
+}
+/**
+ * Historical Analytics for Iceberg Tables
+ *
+ * Provides advanced analytics capabilities for Iceberg time-travel data:
+ * - Change rate analysis
+ * - Growth trend analysis
+ * - Snapshot comparison
+ */
+export declare class HistoricalAnalytics {
+    private bucket;
+    private catalog;
+    private reader;
+    private retentionWindowMs;
+    private enableCache;
+    private cacheTtlMs;
+    private cache;
+    constructor(config: HistoricalAnalyticsConfig);
+    /**
+     * Get change rate analysis for a table over a time period
+     *
+     * Analyzes insert, update, and delete rates between two timestamps.
+     *
+     * @param table - Table identifier
+     * @param startTime - Start timestamp
+     * @param endTime - End timestamp
+     * @returns Change rate analysis
+     */
+    getChangeRate(table: TableIdentifier, startTime: TimestampSpec, endTime: TimestampSpec): Promise<ChangeRateAnalysis>;
+    /**
+     * Get data growth metrics for a table
+     *
+     * Analyzes historical growth patterns and projects future growth.
+     *
+     * @param table - Table identifier
+     * @param samplingInterval - Optional sampling interval in ms (default: 1 day)
+     * @returns Growth metrics
+     */
+    getGrowthMetrics(table: TableIdentifier, samplingInterval?: number): Promise<GrowthMetrics>;
+    /**
+     * Compare two snapshots and return the differences
+     *
+     * Analyzes the changes between two snapshots, including file additions,
+     * deletions, and statistical changes.
+     *
+     * @param table - Table identifier
+     * @param snapshot1Id - First snapshot ID (earlier)
+     * @param snapshot2Id - Second snapshot ID (later)
+     * @returns Snapshot comparison result
+     */
+    getSnapshotComparison(table: TableIdentifier, snapshot1Id: number, snapshot2Id: number): Promise<SnapshotComparison>;
+    /**
+     * Generate cache key
+     */
+    private getCacheKey;
+    /**
+     * Get value from cache
+     */
+    private getFromCache;
+    /**
+     * Set value in cache
+     */
+    private setInCache;
+    /**
+     * Clear the cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        ttlMs: number;
+    };
+}
+/**
+ * Create a historical analytics instance
+ */
+export declare function createHistoricalAnalytics(config: HistoricalAnalyticsConfig): HistoricalAnalytics;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/iceberg/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/iceberg/analytics.ts"],"names":[],"mappings":"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"}