chore: remove features that shouldn't be in this PR, rewrite docs

Removed/reverted: - parameterizable type variations - changes to how types are referred to in the YAML - the word "parameterizable" in this context Changed: - rename "type" metatype to "dataType" to disambiguate a bit better Fixed: - doc examples using "enum" instead of "enumeration"
substrait-io · Jun 27, 2022 · 27e18f7 · 27e18f7
1 parent df1df3c
commit 27e18f7
Show file tree

Hide file tree

Showing 5 changed files with 15 additions and 79 deletions.
diff --git a/proto/substrait/algebra.proto b/proto/substrait/algebra.proto
@@ -422,10 +422,6 @@ message Expression {
     // directly declare the type variation).
     uint32 type_variation_reference = 51;
 
-    // The parameters to be bound to the type variation, if a type variation is
-    // specified and it is defined to be parameterizable.
-    repeated Type.Parameter type_variation_parameters = 52;
-
     message VarChar {
       string value = 1;
       uint32 length = 2;

diff --git a/proto/substrait/type.proto b/proto/substrait/type.proto
@@ -55,158 +55,134 @@ message Type {
 
   message Boolean {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message I8 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message I16 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message I32 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message I64 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message FP32 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message FP64 {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message String {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message Binary {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message Timestamp {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message Date {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message Time {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message TimestampTZ {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message IntervalYear {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message IntervalDay {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   message UUID {
     uint32 type_variation_reference = 1;
-    repeated Parameter type_variation_parameters = 3;
     Nullability nullability = 2;
   }
 
   // Start compound types.
   message FixedChar {
     int32 length = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
   }
 
   message VarChar {
     int32 length = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
   }
 
   message FixedBinary {
     int32 length = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
   }
 
   message Decimal {
     int32 scale = 1;
     int32 precision = 2;
     uint32 type_variation_reference = 3;
-    repeated Parameter type_variation_parameters = 5;
     Nullability nullability = 4;
   }
 
   message Struct {
     repeated Type types = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
   }
 
   message List {
     Type type = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
   }
 
   message Map {
     Type key = 1;
     Type value = 2;
     uint32 type_variation_reference = 3;
-    repeated Parameter type_variation_parameters = 5;
     Nullability nullability = 4;
   }
 
   message UserDefined {
     uint32 type_reference = 1;
     uint32 type_variation_reference = 2;
-    repeated Parameter type_variation_parameters = 4;
     Nullability nullability = 3;
-    repeated Parameter type_parameters = 5;
+    repeated Parameter type_parameters = 4;
   }
 
   message Parameter {

diff --git a/site/docs/types/type_classes.md b/site/docs/types/type_classes.md
@@ -44,7 +44,7 @@ Compound type classes are type classes that need to be configured by means of a
 
 ## User-Defined Types
 
-User-defined type classes can be created using a combination of pre-defined types. User-defined types are defined as part of [simple extensions](../extensions/index.md#simple-extensions). An extension can declare an arbitrary number of user defined extension types. Initially, user defined types must be simple types (although they can be constructed of a number of inner compound and simple types).
+User-defined type classes can be created using a combination of pre-defined types. User-defined types are defined as part of [simple extensions](../extensions/index.md#simple-extensions). An extension can declare an arbitrary number of user defined extension types.
 
 A YAML example of an extension type is below:
 
@@ -59,9 +59,9 @@ This declares a new type (namespaced to the associated YAML file) called "point"
 
 Literals for user-defined types are represented using protobuf [Any](https://developers.google.com/protocol-buffers/docs/proto3#any) messages.
 
-### Parameterization
+### Compound User-Defined Types
 
-User-defined types may be parameterized, in the same way in which the built-in compound types are parameterizable. The supported "meta-types" for parameters are data types, booleans, integers, enumerations, and strings. Using parameters, we could redefine "point" with different types of coordinates. For example:
+User-defined types may be turned into compound types by requiring parameters to be passed to them. The supported "meta-types" for parameters are data types (like those used in `LIST`, `MAP`, and `STRUCT`), booleans, integers, enumerations, and strings. Using parameters, we could redefine "point" with different types of coordinates. For example:
 
 ```yaml
 name: point
@@ -70,7 +70,7 @@ parameters:
     description: |
       The type used for the longitude and latitude
       components of the point.
-    type: type
+    type: dataType
 ```
 
 or:
@@ -79,7 +79,7 @@ or:
 name: point
 parameters:
   - name: coordinate_type
-    type: enum
+    type: enumeration
     options:
       - integer
       - double
@@ -91,9 +91,9 @@ or:
 name: point
 parameters:
   - name: LONG
-    type: type
+    type: dataType
   - name: LAT
-    type: type
+    type: dataType
 ```
 
 We can't specify the internal structure in this case, because there is currently no support for derived types in the structure.
@@ -104,22 +104,22 @@ The allowed range can be limited for integer parameters. For example:
 name: vector
 parameters:
   - name: T
-    type: type
+    type: dataType
   - name: dimensions
     type: integer
     min: 2
     max: 3
 ```
 
-This specifies a vector that can be either 2- or 3-dimensional.
+This specifies a vector that can be either 2- or 3-dimensional. Note however that it's not currently possible to put constraints on data type, string, or (technically) boolean parameters.
 
 Similar to function arguments, the last parameter may be specified to be variadic, allowing it to be specified one or more times instead of only once. For example:
 
 ```yaml
 name: union
 parameters:
   - name: T
-    type: type
+    type: dataType
 variadic: true
 ```
 
@@ -129,7 +129,7 @@ This defines a type that can be parameterized with one or more other data types,
 name: tuple
 parameters:
   - name: T
-    type: type
+    type: dataType
     optional: true
 variadic: true
 ```

diff --git a/site/docs/types/type_variations.md b/site/docs/types/type_variations.md
@@ -10,4 +10,3 @@ All variations except the "system-preferred" variation (a.k.a. `[0]`, see [Type
 | Name              | The name used to reference this type. Should be unique within type variations for this parent type within a simple extension. |
 | Description       | A human description of the purpose of this type variation.   |
 | Function Behavior | **INHERITS** or **SEPARATE**: whether functions that support the system-preferred variation implicitly also support this variation, or whether functions should be resolved independently. For example, if one has the function `add(i8,i8)` defined and then defines an `i8` variation, this determines whether the `i8` variation can be bound to the base `add` operation (inherits) or whether a specialized version of `add` needs to be defined specifically for this variation (separate). Defaults to inherits. |
-| Parameterization  | Type variations can be parameterized. For example, an implementation may support storing `timestamp_tz` using any timezone, in which case it might not be convenient to create a variation for every possible timezone. Parameterizations for type variations work the same as parameterizations for [compound user-defined types](type_classes.md#parameterization). |
diff --git a/text/simple_extensions_schema.yaml b/text/simple_extensions_schema.yaml
@@ -37,10 +37,6 @@ properties:
         functions:
           type: string
           enum: [INHERITS, SEPARATE]
-        parameters:  # parameter list for compound type variations
-          $ref: "#/$defs/type_param_defs"
-        variadic:  # when set, last parameter may be specified one or more times
-          type: boolean
   scalar_functions:
     type: array
     items:
@@ -53,27 +49,9 @@ properties:
 $defs:
   type:
     oneOf:
-      - type: string  # shorthand form for when only name is needed
+      - type: string
       - type: object
-        properties:
-          name:  # name: a Substrait type name, or name of a type previously defined in this extension
-            type: string
-          nullable:  # set to true to make the type nullable
-            type: boolean
-          variation:  # type variation, if any
-            $ref: "#/$defs/variation"
-          parameters:  # parameters for compound types
-            $ref: "#/$defs/type_param_values"
-  variation:
-    oneOf:
-      - type: string  # shorthand form for when only name is needed
-      - type: object
-        properties:
-          name:  # name of a type variation previously defined in this extension
-            type: string
-          parameters:  # parameters for compound type variations
-            $ref: "#/$defs/type_param_values"
-  type_param_defs:  # an array of compound type (variation) parameter definitions
+  type_param_defs:  # an array of compound type parameter definitions
     type: array
     items:
       type: object
@@ -86,7 +64,7 @@ $defs:
         type:  # expected metatype for the parameter
           type: string
           enum:
-            - type
+            - dataType
             - boolean
             - integer
             - enumeration
@@ -103,19 +81,6 @@ $defs:
             type: string
         optional:  # when set to true, the parameter may be omitted at the end or skipped using null
           type: boolean
-  type_param_values:  # an array of compound type (variation) parameter definitions
-    type: array
-    items:
-      oneOf:
-        - type: "null"  # use to skip optional parameters
-        - type: boolean  # for boolean parameters
-        - type: number  # for integer parameters
-        - type: string  # for string and enum parameters
-        - type: object  # for data type parameters
-          required: [ type ]
-          properties:
-            type:
-              $ref: "#/$defs/type"
   arguments:  # an array of arguments
     type: array
     items: