feat: define sideband optimization hints

proto/substrait/algebra.proto

@@ -47,6 +47,12 @@ message RelCommon {
 
     substrait.extensions.AdvancedExtension advanced_extension = 10;
 
+    // Save or load a system-specific computation for use in optimizing a remote operation.
+    // The anchor refers to the source/destination of the computation.  The computation type
+    // and number refer to the current relation.
+    repeated SavedComputation saved_computations = 11;
+    repeated LoadedComputation loaded_computations = 12;
+
     // The statistics related to a hint (physical properties of records)
     message Stats {
       double row_count = 1;
@@ -59,6 +65,49 @@ message RelCommon {
 
       substrait.extensions.AdvancedExtension advanced_extension = 10;
     }
+
+    enum ComputationType {
+      COMPUTATION_TYPE_UNSPECIFIED = 0;
+      COMPUTATION_TYPE_HASHTABLE = 1;
+      COMPUTATION_TYPE_BLOOM_FILTER = 2;
+      COMPUTATION_TYPE_UNKNOWN = 9999;
+    }
+
+    message SavedComputation {
+      // The value corresponds to a plan unique number for that datastructure.  Any particular
+      // computation may be saved only once but it may be loaded multiple times.
+      int32 computation_id = 1;
+      // The type of this computation.  While a plan may use COMPUTATION_TYPE_UNKNOWN for all
+      // of its types it is recommended to use a more specific type so that the optimization
+      // is more portable.  The consumer should be able to decide if an unknown type here
+      // matches the same unknown type at a different plan and ignore the optimization if they
+      // are mismatched.
+      ComputationType type = 2;
+      // The instance of the given computation type on this relation.  For instance, a 2 here
+      // with computation type COMPUTATION_TYPE_BLOOM_FILTER refers to the second bloom filter.
+      // The local system can use any numbering system it wants but for better compatibility
+      // it is suggested to refer to computations in order of the input that they are derived
+      // from.  Computation numbers start at 1.
+      int32 number = 3;
+    }
+
+    message LoadedComputation {
+      // The value corresponds to a plan unique number for that datastructure.  Any particular
+      // computation may be saved only once but it may be loaded multiple times.
+      int32 computation_id_reference = 1;
+      // The type of this computation.  While a plan may use COMPUTATION_TYPE_UNKNOWN for all
+      // of its types it is recommended to use a more specific type so that the optimization
+      // is more portable.  The consumer should be able to decide if an unknown type here
+      // matches the same unknown type at a different plan and ignore the optimization if they
+      // are mismatched.
+      ComputationType type = 2;
+      // The instance of the given computation type on this relation.  For instance, a two here
+      // with computation type COMPUTATION_TYPE_BLOOM_FILTER refers to the second bloom filter.
+      // The local system can use any numbering system it wants but for better compatibility
+      // it is suggested to refer to computations in order of the input that they are derived
+      // from.  Computation numbers start at 1.
+      int32 number = 3;
+    }
   }
 }
 

site/docs/relations/_config

@@ -1,6 +1,7 @@
 arrange:
   - basics.md
+  - common_fields.md
   - logical_relations.md
   - physical_relations.md
   - user_defined_relations.md
-  - embedded_relations.md
+  - embedded_relations.md

site/docs/relations/common_fields.md

@@ -0,0 +1,28 @@
+# Common Fields
+
+Every relation contains a common section containing optional hints and emit behavior.
+
+
+## Emit
+
+A relation which has a direct emit kind outputs the relation's output without reordering or selection.  A relation that specifies an emit output mapping can output its output columns in any order and may leave output columns out.
+
+???+ info "Relation Output"
+
+    * Relations by default provide as their output the list of all of its input columns plus any generated columns as its output columns.  One notable exception is aggregations which only output new columns.
+
+
+## Hints
+
+Hints provide information that can improve performance but cannot be used to control the behavior.  Table statistics, runtime constraints, name hints, and saved computations all fall into this category.
+
+???+ info "Hint Design"
+
+    * If a hint is not present or has incorrect data the consumer should be able to arrive at the correct result.
+
+
+### Saved Computations
+
+Computations can be used to save on data structure to use elsewhere.  For instance, let's say we have a plan with a HashEquiJoin and an AggregateDistinct operation.  The HashEquiJoin could save its hash table as part of saved computation id number 1 and the AggregateDistinct could read in computation id number 1.
+
+Now let's try a more complicated example.  We have a relation that has constructs two hash tables and we'd like one of them to go to our aggregate relation still but the other to go elsewhere.  We can use the computation number to select which data structure goes where.  For instance computation number 1 could be hash table number 1 and computation number 2 could be hash table number 2.  The reciving entity just needs to know which of its data structures it needs to put that computation in.  So if it has 5 hash table datastructures the LoadedComputation record needs to point to the number that it intends for that incoming data to go.