exp: Materialize (#3567)

The commit introduces a MaterializationService that automatically
creates persistent tables (CREATE OR REPLACE PERFETTO TABLE) for query
nodes after successful execution, improving query performance for reused
results.

  Key Changes

  1. New MaterializationService (materialization_service.ts:1-122)
- Manages lifecycle of materialized tables using CREATE OR REPLACE
PERFETTO TABLE
  - Sanitizes node IDs for SQL safety (alphanumeric + underscores only)
  - Executes includes/preambles before creating materialized tables
  - Uses _exp_materialized_ prefix for table names

  2. Automatic Materialization (builder.ts:380-391)
  - Queries are automatically materialized after successful execution
  - Only materializes valid queries (no errors/warnings)
  - Errors logged but don't block the UI

3. Cleanup Integration (explore_page.ts:247-276,
explore_page.ts:319-335)
- handleClearAllNodes(): Drops all materialized tables in parallel
before clearing
- handleDeleteNode(): Cleans up materialized table when deleting a node
- Added getAllNodes() helper to traverse the node graph bidirectionally

  4. UI Indicator (data_explorer.ts:114-124)
  - Database icon with tooltip showing materialized table name
  - Provides visibility into which nodes are materialized

Author: aMayzner

ui/src/plugins/dev.perfetto.ExplorePage/explore_page.ts

@@ -28,6 +28,7 @@ import {exportStateAsJson, importStateFromJson} from './json_handler';
 import {showImportWithStatementModal} from './sql_json_handler';
 import {registerCoreNodes} from './query_builder/core_nodes';
 import {nodeRegistry} from './query_builder/node_registry';
+import {MaterializationService} from './query_builder/materialization_service';
 import {HistoryManager} from './history_manager';
 
 registerCoreNodes();
@@ -51,6 +52,7 @@ interface ExplorePageAttrs {
 }
 
 export class ExplorePage implements m.ClassComponent<ExplorePageAttrs> {
+  private materializationService?: MaterializationService;
   private historyManager?: HistoryManager;
 
   private selectNode(attrs: ExplorePageAttrs, node: QueryNode) {
@@ -244,14 +246,70 @@ export class ExplorePage implements m.ClassComponent<ExplorePageAttrs> {
     }));
   }
 
-  handleClearAllNodes(attrs: ExplorePageAttrs) {
+  async handleClearAllNodes(attrs: ExplorePageAttrs) {
+    // Clean up materialized tables for all nodes
+    if (this.materializationService !== undefined) {
+      const allNodes = this.getAllNodes(attrs.state.rootNodes);
+      const materialized = allNodes.filter(
+        (node) => node.state.materialized === true,
+      );
+
+      // Drop all materializations in parallel
+      const results = await Promise.allSettled(
+        materialized.map((node) =>
+          this.materializationService!.dropMaterialization(node),
+        ),
+      );
+
+      // Log any failures but don't block the clear operation
+      results.forEach((result, index) => {
+        if (result.status === 'rejected') {
+          console.error(
+            `Failed to drop materialization for node ${materialized[index].nodeId}:`,
+            result.reason,
+          );
+        }
+      });
+    }
+
     attrs.onStateUpdate((currentState) => ({
       ...currentState,
       rootNodes: [],
       selectedNode: undefined,
     }));
   }
 
+  private getAllNodes(rootNodes: QueryNode[]): QueryNode[] {
+    const allNodes: QueryNode[] = [];
+    const visited = new Set<string>();
+    const queue = [...rootNodes];
+
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      if (visited.has(node.nodeId)) {
+        continue;
+      }
+      visited.add(node.nodeId);
+      allNodes.push(node);
+
+      // Traverse forward edges
+      queue.push(...node.nextNodes);
+
+      // Traverse backward edges
+      if ('prevNode' in node && node.prevNode) {
+        queue.push(node.prevNode);
+      } else if ('prevNodes' in node) {
+        for (const prevNode of node.prevNodes) {
+          if (prevNode !== undefined) {
+            queue.push(prevNode);
+          }
+        }
+      }
+    }
+
+    return allNodes;
+  }
+
   handleDuplicateNode(attrs: ExplorePageAttrs, node: QueryNode) {
     const {onStateUpdate} = attrs;
     onStateUpdate((currentState) => ({
@@ -260,9 +318,25 @@ export class ExplorePage implements m.ClassComponent<ExplorePageAttrs> {
     }));
   }
 
-  handleDeleteNode(attrs: ExplorePageAttrs, node: QueryNode) {
+  async handleDeleteNode(attrs: ExplorePageAttrs, node: QueryNode) {
     const {state, onStateUpdate} = attrs;
 
+    // Clean up materialized table if it exists
+    if (
+      this.materializationService !== undefined &&
+      node.state.materialized === true
+    ) {
+      try {
+        await this.materializationService.dropMaterialization(node);
+      } catch (e) {
+        console.error(
+          `Failed to drop materialization for node ${node.nodeId}:`,
+          e,
+        );
+        // Continue with node deletion even if materialization cleanup fails
+      }
+    }
+
     let newRootNodes = state.rootNodes.filter((n) => n !== node);
     if (state.rootNodes.includes(node) && node.nextNodes.length > 0) {
       newRootNodes = [...newRootNodes, ...node.nextNodes];
@@ -509,6 +583,12 @@ export class ExplorePage implements m.ClassComponent<ExplorePageAttrs> {
       {
         onkeydown: (e: KeyboardEvent) => this.handleKeyDown(e, wrappedAttrs),
         oncreate: (vnode) => {
+          // Initialize materialization service
+          if (this.materializationService === undefined) {
+            this.materializationService = new MaterializationService(
+              attrs.trace.engine,
+            );
+          }
           (vnode.dom as HTMLElement).focus();
         },
         tabindex: 0,

ui/src/plugins/dev.perfetto.ExplorePage/query_builder/builder.ts

@@ -82,6 +82,7 @@ import {QueryService} from './query_service';
 import {findErrors, findWarnings} from './query_builder_utils';
 import {NodeIssues} from './node_issues';
 import {UIFilter} from './operations/filter';
+import {MaterializationService} from './materialization_service';
 
 export interface BuilderAttrs {
   readonly trace: Trace;
@@ -131,6 +132,7 @@ export interface BuilderAttrs {
 
 export class Builder implements m.ClassComponent<BuilderAttrs> {
   private queryService: QueryService;
+  private materializationService: MaterializationService;
   private query?: Query | Error;
   private queryExecuted: boolean = false;
   private isQueryRunning: boolean = false;
@@ -143,6 +145,9 @@ export class Builder implements m.ClassComponent<BuilderAttrs> {
 
   constructor({attrs}: m.Vnode<BuilderAttrs>) {
     this.queryService = new QueryService(attrs.trace.engine);
+    this.materializationService = new MaterializationService(
+      attrs.trace.engine,
+    );
   }
 
   view({attrs}: m.CVnode<BuilderAttrs>) {
@@ -361,7 +366,7 @@ export class Builder implements m.ClassComponent<BuilderAttrs> {
     return undefined;
   }
 
-  private runQuery(node: QueryNode) {
+  private async runQuery(node: QueryNode) {
     if (
       this.query === undefined ||
       this.query instanceof Error ||
@@ -371,7 +376,9 @@ export class Builder implements m.ClassComponent<BuilderAttrs> {
     }
 
     this.isQueryRunning = true;
-    this.queryService.runQuery(queryToRun(this.query)).then((response) => {
+
+    try {
+      const response = await this.queryService.runQuery(queryToRun(this.query));
       this.response = response;
       const ds = new InMemoryDataSource(this.response.rows);
       this.dataSource = {
@@ -411,8 +418,27 @@ export class Builder implements m.ClassComponent<BuilderAttrs> {
       if (node instanceof SqlSourceNode) {
         node.onQueryExecuted(this.response.columns);
       }
+
+      // Automatically materialize the node after successful execution
+      if (isAQuery(this.query) && !error && !warning) {
+        try {
+          await this.materializationService.materializeNode(node, this.query);
+        } catch (e) {
+          console.error('Failed to materialize node:', e);
+          // Don't block the UI on materialization errors
+        }
+      }
+    } catch (e) {
+      console.error('Failed to run query:', e);
+      // Set error state on the node
+      if (!node.state.issues) {
+        node.state.issues = new NodeIssues();
+      }
+      node.state.issues.queryError =
+        e instanceof Error ? e : new Error(String(e));
+    } finally {
       this.isQueryRunning = false;
       m.redraw();
-    });
+    }
   }
 }

ui/src/plugins/dev.perfetto.ExplorePage/query_builder/data_explorer.ts

@@ -36,6 +36,8 @@ import {QueryService} from './query_service';
 import {Intent} from '../../../widgets/common';
 import {Icons} from '../../../base/semantic_icons';
 import {MenuItem, PopupMenu} from '../../../widgets/menu';
+import {Icon} from '../../../widgets/icon';
+import {Tooltip} from '../../../widgets/tooltip';
 
 import {findErrors} from './query_builder_utils';
 export interface DataExplorerAttrs {
@@ -109,6 +111,18 @@ export class DataExplorer implements m.ClassComponent<DataExplorerAttrs> {
       },
     });
 
+    // Add materialization indicator icon with tooltip
+    const materializationIndicator =
+      attrs.node.state.materialized && attrs.node.state.materializationTableName
+        ? m(
+            Tooltip,
+            {
+              trigger: m(Icon, {icon: 'database'}),
+            },
+            `Materialized as ${attrs.node.state.materializationTableName}`,
+          )
+        : null;
+
     const positionMenu = m(
       PopupMenu,
       {
@@ -124,7 +138,13 @@ export class DataExplorer implements m.ClassComponent<DataExplorerAttrs> {
       ],
     );
 
-    return [runButton, statusIndicator, autoExecuteSwitch, positionMenu];
+    return [
+      runButton,
+      statusIndicator,
+      materializationIndicator,
+      autoExecuteSwitch,
+      positionMenu,
+    ];
   }
 
   private renderContent(

ui/src/plugins/dev.perfetto.ExplorePage/query_builder/materialization_service.ts

@@ -0,0 +1,122 @@
+// Copyright (C) 2025 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {Engine} from '../../../trace_processor/engine';
+import {Query, QueryNode} from '../query_node';
+
+/**
+ * Service for managing materialized tables for Explore Page nodes.
+ * Materialization creates persistent tables using CREATE OR REPLACE PERFETTO TABLE.
+ */
+export class MaterializationService {
+  constructor(private engine: Engine) {}
+
+  /**
+   * Materializes a node's query into a table.
+   * If the table already exists, it will be replaced.
+   *
+   * @param node The node to materialize
+   * @param query The validated query to materialize
+   * @returns The name of the created materialized table
+   */
+  async materializeNode(node: QueryNode, query: Query): Promise<string> {
+    const tableName = this.getTableName(node);
+
+    // Build the full SQL with includes and preambles
+    const includes = query.modules.map((c) => `INCLUDE PERFETTO MODULE ${c};`);
+    const parts: string[] = [];
+    if (includes.length > 0) {
+      parts.push(includes.join('\n'));
+    }
+    if (query.preambles.length > 0) {
+      parts.push(query.preambles.join('\n'));
+    }
+
+    // Execute the includes and preambles first
+    if (parts.length > 0) {
+      const fullSql = parts.join('\n');
+      await this.engine.query(fullSql);
+    }
+
+    // Create or replace the materialized table
+    const createTableSql = `CREATE OR REPLACE PERFETTO TABLE ${tableName} AS ${query.sql}`;
+    await this.engine.query(createTableSql);
+
+    // Update node state
+    node.state.materialized = true;
+    node.state.materializationTableName = tableName;
+
+    return tableName;
+  }
+
+  /**
+   * Drops a materialized table for a node.
+   *
+   * @param node The node whose materialized table should be dropped
+   */
+  async dropMaterialization(node: QueryNode): Promise<void> {
+    if (!node.state.materializationTableName) {
+      return;
+    }
+
+    const tableName = node.state.materializationTableName;
+    // Use query() not tryQuery() - we want to know if drop fails
+    await this.engine.query(`DROP TABLE IF EXISTS ${tableName}`);
+
+    // Only update state if drop succeeded
+    node.state.materialized = false;
+    node.state.materializationTableName = undefined;
+  }
+
+  /**
+   * Generates a unique table name for a node's materialization.
+   *
+   * @param node The node to generate a table name for
+   * @returns A unique table name
+   */
+  private getTableName(node: QueryNode): string {
+    // Sanitize nodeId to prevent SQL injection and ensure valid identifier
+    // Only allow alphanumeric characters and underscores
+    const sanitizedId = node.nodeId.replace(/[^a-zA-Z0-9_]/g, '_');
+
+    // Warn if sanitization changed the nodeId, as this could lead to collisions
+    if (sanitizedId !== node.nodeId) {
+      console.warn(
+        `Node ID "${node.nodeId}" was sanitized to "${sanitizedId}" for table name.`,
+      );
+    }
+
+    return `_exp_materialized_${sanitizedId}`;
+  }
+
+  /**
+   * Checks if a node is currently materialized.
+   *
+   * @param node The node to check
+   * @returns True if the node is materialized
+   */
+  isMaterialized(node: QueryNode): boolean {
+    return node.state.materialized ?? false;
+  }
+
+  /**
+   * Gets the materialized table name for a node if it exists.
+   *
+   * @param node The node to get the table name for
+   * @returns The table name or undefined
+   */
+  getMaterializedTableName(node: QueryNode): string | undefined {
+    return node.state.materializationTableName;
+  }
+}

ui/src/plugins/dev.perfetto.ExplorePage/query_node.ts

@@ -92,6 +92,10 @@ export interface QueryNodeState {
   // If false, the user must manually click "Run" to execute queries.
   // Set by the node registry when the node is created.
   autoExecute?: boolean;
+
+  // Materialization state
+  materialized?: boolean;
+  materializationTableName?: string;
 }
 
 export interface BaseNode {