feat: add unbound type for partially bound plans

dialects/tests/types_test.yaml

@@ -9,6 +9,7 @@ dependencies:
 supported_types:
   - I8
   - I16
+  - type: UNBOUND
   - type: I32
     metadata:
       storage_bytes: 4

proto/substrait/type.proto

@@ -46,6 +46,13 @@ message Type {
     Map map = 28;
     Func func = 38;
 
+    // A placeholder type whose concrete type has not yet been bound.
+    // Unbound may be used where a concrete type would normally appear in
+    // partially bound plans and expressions, and must be bound to a
+    // concrete type before execution. Substrait defines no runtime semantics
+    // for values whose type is unbound.
+    Unbound unbound = 39;
+
     UserDefined user_defined = 30;
 
     // Deprecated in favor of user_defined, which allows nullability and
@@ -209,6 +216,8 @@ message Type {
     Nullability nullability = 4;
   }
 
+  message Unbound {}
+
   // A function type for higher-order functions.
   // Represents a function that takes parameters of specified types and
   // returns a value of a specified type.

site/docs/types/type_classes.md

@@ -24,6 +24,20 @@ Simple type classes are those that don't support any form of configuration. For
 | date            | A date within [1000-01-01..9999-12-31].                      | `int32` days since `1970-01-01`
 | interval_year   | Interval year to month. Supports a range of [-10,000..10,000] years with month precision (= [-120,000..120,000] months). Usually stored as separate integers for years and months, but only the total number of months is significant, i.e. `1y 0m` is considered equal to `0y 12m` or `1001y -12000m`. | `int32` years and `int32` months, with the added constraint that each component can never independently specify more than 10,000 years, even if the components have opposite signs (e.g. `-10000y 200000m` is **not** allowed)
 | uuid            | A universally-unique identifier composed of 128 bits. Typically presented to users in the following hexadecimal format: `c48ffa9e-64f4-44cb-ae47-152b4e60e77b`. Any 128-bit value is allowed, without specific adherence to RFC4122. | 16-byte `binary`
+| unbound         | A placeholder for a type that has not yet been bound to a concrete type. May only appear in partially bound plans, which must be bound before execution. | n/a
+
+### Unbound Type
+
+The `unbound` type class is a placeholder for a type that has not yet been bound to a concrete type. It may appear wherever a concrete type would normally appear, for example as a field type within `ReadRel.base_schema`. This allows a producer to serialize the shape of a plan — its relations and the names and ordering of its fields — before the concrete types of those fields are known. A downstream binder later replaces each occurrence of `unbound` with a concrete type once the necessary schema or catalog information is available.
+
+A plan that contains `unbound` anywhere within it is *partially bound*. Partially bound plans may be serialized and exchanged, but they are not executable, and Substrait defines no runtime semantics for values of unbound type. Specifically:
+
+- `unbound` is not a wildcard: it does not unify with, or implicitly coerce to, any other type. In particular, `unbound` is distinct from `any`: `any` is a function-signature wildcard that participates in overload matching, while `unbound` is a plan-level placeholder for a type that is not yet known.
+- `unbound` carries no nullability and accepts no parameters; those properties are determined when the type is bound to a concrete type.
+- There is no literal of type `unbound`.
+- Substrait prescribes no resolution policy for `unbound`. A function invocation whose argument types are unbound is part of a partially bound plan; how a binder assigns concrete types, and how it subsequently resolves function bindings, is left entirely to the system performing the binding.
+
+Consumers that do not support partially bound plans should reject any plan containing `unbound`.
 
 ### Compound Types
 

site/docs/types/type_system.md

@@ -15,3 +15,5 @@ Refer to [Type Parsing](type_parsing.md) for a description of the syntax used to
 
 !!! note "Note"
     Substrait employs a strict type system without any coercion rules. All changes in types must be made explicit via [cast expressions](../expressions/specialized_record_expressions.md).
+
+    Partially bound plans and expressions may use the [`unbound`](type_classes.md#unbound-type) type as a placeholder until a downstream binder assigns a concrete type.

text/dialect_schema.yaml

@@ -54,6 +54,7 @@ properties:
           - INTERVAL_DAY
           - INTERVAL_YEAR
           - UUID
+          - UNBOUND
           - DECIMAL
           - STRUCT
           - LIST
@@ -78,6 +79,7 @@ properties:
         - $ref: "#/definitions/type_interval_day"
         - $ref: "#/definitions/type_interval_year"
         - $ref: "#/definitions/type_uuid"
+        - $ref: "#/definitions/type_unbound"
         - $ref: "#/definitions/type_decimal"
         - $ref: "#/definitions/type_struct"
         - $ref: "#/definitions/type_list"
@@ -640,6 +642,18 @@ definitions:
         description: Arbitrary data created by the dialect author.
       system_metadata:
         $ref: "#/definitions/system_type_metadata"
+  type_unbound:
+    type: object
+    additionalProperties: false
+    required: [type]
+    properties:
+      type:
+        const: UNBOUND
+      metadata:
+        type: object
+        description: Arbitrary data created by the dialect author.
+      system_metadata:
+        $ref: "#/definitions/system_type_metadata"
   type_decimal:
     type: object
     additionalProperties: false