tp: Add Experimental AddColumn join (#3494)

Adds a new experimental ExperimentalAddColumns operation to the
structured query system that enriches a core query with additional
columns from an input query using LEFT
  JOIN semantics.

  Key features:
- Takes a core query (returns all its columns) + input query (source of
additional columns)
  - Joins them using equality conditions or freeform SQL expressions
- Use case: e.g., add process name to slice data by joining on process
ID

Author: aMayzner

protos/perfetto/perfetto_sql/structured_query.proto

@@ -251,6 +251,54 @@ message PerfettoSqlStructuredQuery {
     optional bool use_union_all = 2;
   }
 
+  // DON'T USE. EXPERIMENTAL.
+  // Adds columns from an input query to a core query using a join condition.
+  //
+  // This operation returns all columns from the core query plus specified
+  // columns from the input query, joined using a condition similar to
+  // ExperimentalJoin.
+  //
+  // Examples:
+  //  1) Add process name to slices:
+  //    * core_query contains slice data (id, ts, dur, name)
+  //    * input_query contains process data (id, name, pid)
+  //    * input_columns = ["name"] (aliased appropriately)
+  //    * equality_columns matches process id
+  //  2) Enrich counter data with additional metadata:
+  //    * core_query contains counter values
+  //    * input_query contains metadata table
+  //    * input_columns specifies which metadata columns to add
+  //
+  // Schema:
+  //  1) The input_columns list must contain at least one column name.
+  //  2) All column names in input_columns must exist in the input_query result.
+  //  3) One of equality_columns or freeform_condition must be specified.
+  message ExperimentalAddColumns {
+    // The core query. All columns from this query will be returned. Required.
+    optional PerfettoSqlStructuredQuery core_query = 1;
+
+    // The input query. Source of additional columns. Required.
+    optional PerfettoSqlStructuredQuery input_query = 2;
+
+    // List of column names to add from the input query. At least one required.
+    repeated string input_columns = 3;
+
+    // The condition for the join. One of the following is required.
+    oneof condition {
+      // Columns from both queries which must be equal for the join.
+      // Reuses the EqualityColumns message from ExperimentalJoin, where
+      // left_column refers to core_query and right_column refers to
+      // input_query.
+      ExperimentalJoin.EqualityColumns equality_columns = 4;
+
+      // A freeform SQL expression representing the join condition.
+      // Reuses the FreeformCondition message from ExperimentalJoin, where
+      // left_query_alias refers to core_query and right_query_alias refers
+      // to input_query.
+      ExperimentalJoin.FreeformCondition freeform_condition = 5;
+    }
+  }
+
   // An opaque id field for the query. The convention is to use underscores
   // and lower case (foo_bar) but this is not enforced. Optional in the general
   // case but strongly recommended for good error messages. Required in cases
@@ -300,8 +348,25 @@ message PerfettoSqlStructuredQuery {
 
     // DON'T USE. EXPERIMENTAL.
     ExperimentalUnion experimental_union = 101;
+
+    // DON'T USE. EXPERIMENTAL.
+    ExperimentalAddColumns experimental_add_columns = 102;
   }
 
+  // Evaluation order of operations:
+  // The fields below are evaluated in a specific order following SQL semantics.
+  // The logical evaluation order is:
+  //   1. FROM (source) - determine the source data
+  //   2. WHERE (filters) - filter rows from the source
+  //   3. GROUP BY (group_by) - group rows and compute aggregations
+  //   4. SELECT (select_columns) - select and transform columns
+  //   5. ORDER BY (order_by) - sort the result set
+  //   6. LIMIT/OFFSET (limit, offset) - restrict the number of rows returned
+  //
+  // This follows the standard SQL evaluation order as defined in the SQL
+  // standard (ISO/IEC 9075). For more details, see:
+  // https://www.sqlite.org/lang_select.html
+
   // Represents a single filter on a column.
   message Filter {
     // The column name to be filtered. Required.

python/perfetto/trace_processor/trace_processor.descriptor

@@ -175,6 +175,9 @@ class GeneratorImpl {
   base::StatusOr<std::string> Union(
       const StructuredQuery::ExperimentalUnion::Decoder&);
 
+  base::StatusOr<std::string> AddColumns(
+      const StructuredQuery::ExperimentalAddColumns::Decoder&);
+
   // Filtering.
   static base::StatusOr<std::string> Filters(RepeatedProto filters);
 
@@ -263,6 +266,11 @@ base::StatusOr<std::string> GeneratorImpl::GenerateImpl() {
       StructuredQuery::ExperimentalUnion::Decoder union_decoder(
           q.experimental_union());
       ASSIGN_OR_RETURN(source, Union(union_decoder));
+
+    } else if (q.has_experimental_add_columns()) {
+      StructuredQuery::ExperimentalAddColumns::Decoder add_columns_decoder(
+          q.experimental_add_columns());
+      ASSIGN_OR_RETURN(source, AddColumns(add_columns_decoder));
     } else if (q.has_sql()) {
       StructuredQuery::Sql::Decoder sql_source(q.sql());
       ASSIGN_OR_RETURN(source, SqlSource(sql_source));
@@ -575,6 +583,103 @@ base::StatusOr<std::string> GeneratorImpl::Union(
   return sql;
 }
 
+base::StatusOr<std::string> GeneratorImpl::AddColumns(
+    const StructuredQuery::ExperimentalAddColumns::Decoder& add_columns) {
+  // Validate required fields
+  if (!add_columns.has_core_query()) {
+    return base::ErrStatus("AddColumns must specify a core query");
+  }
+  if (!add_columns.has_input_query()) {
+    return base::ErrStatus("AddColumns must specify an input query");
+  }
+  if (!add_columns.has_equality_columns() &&
+      !add_columns.has_freeform_condition()) {
+    return base::ErrStatus(
+        "AddColumns must specify either equality_columns or "
+        "freeform_condition");
+  }
+
+  // Validate input_columns
+  auto input_columns = add_columns.input_columns();
+  if (!input_columns) {
+    return base::ErrStatus("AddColumns must specify at least one input column");
+  }
+  size_t column_count = 0;
+  for (auto it = input_columns; it; ++it) {
+    column_count++;
+  }
+  if (column_count == 0) {
+    return base::ErrStatus("AddColumns must specify at least one input column");
+  }
+
+  // Generate nested sources
+  std::string core_table = NestedSource(add_columns.core_query());
+  std::string input_table = NestedSource(add_columns.input_query());
+
+  // Build the SELECT clause with all core columns plus input columns
+  std::string select_clause = "core.*";
+  for (auto it = add_columns.input_columns(); it; ++it) {
+    protozero::ConstChars col_name(*it);
+    if (col_name.size == 0) {
+      return base::ErrStatus("Input column name cannot be empty");
+    }
+    select_clause += ", input." + col_name.ToStdString();
+  }
+
+  // Build the join condition
+  std::string condition;
+  if (add_columns.has_equality_columns()) {
+    StructuredQuery::ExperimentalJoin::EqualityColumns::Decoder eq_cols(
+        add_columns.equality_columns());
+    if (!eq_cols.has_left_column()) {
+      return base::ErrStatus("EqualityColumns must specify a left column");
+    }
+    if (!eq_cols.has_right_column()) {
+      return base::ErrStatus("EqualityColumns must specify a right column");
+    }
+    condition = "core." + eq_cols.left_column().ToStdString() + " = input." +
+                eq_cols.right_column().ToStdString();
+  } else {
+    StructuredQuery::ExperimentalJoin::FreeformCondition::Decoder free_cond(
+        add_columns.freeform_condition());
+    if (!free_cond.has_left_query_alias()) {
+      return base::ErrStatus(
+          "FreeformCondition must specify a left query alias");
+    }
+    if (!free_cond.has_right_query_alias()) {
+      return base::ErrStatus(
+          "FreeformCondition must specify a right query alias");
+    }
+    if (!free_cond.has_sql_expression()) {
+      return base::ErrStatus("FreeformCondition must specify a sql expression");
+    }
+
+    std::string left_alias = free_cond.left_query_alias().ToStdString();
+    std::string right_alias = free_cond.right_query_alias().ToStdString();
+
+    // Validate that aliases match "core" and "input"
+    if (left_alias != "core") {
+      return base::ErrStatus(
+          "FreeformCondition left_query_alias must be 'core', got '%s'",
+          left_alias.c_str());
+    }
+    if (right_alias != "input") {
+      return base::ErrStatus(
+          "FreeformCondition right_query_alias must be 'input', got '%s'",
+          right_alias.c_str());
+    }
+
+    condition = free_cond.sql_expression().ToStdString();
+  }
+
+  // Generate the final SQL using LEFT JOIN to keep all core rows
+  std::string sql = "(SELECT " + select_clause + " FROM " + core_table +
+                    " AS core LEFT JOIN " + input_table + " AS input ON " +
+                    condition + ")";
+
+  return sql;
+}
+
 base::StatusOr<std::string> GeneratorImpl::ReferencedSharedQuery(
     protozero::ConstChars raw_id) {
   std::string id = raw_id.ToStdString();