1// Licensed to the Apache Software Foundation (ASF) under one 2// or more contributor license agreements. See the NOTICE file 3// distributed with this work for additional information 4// regarding copyright ownership. The ASF licenses this file 5// to you under the Apache License, Version 2.0 (the 6// "License"); you may not use this file except in compliance 7// with the License. You may obtain a copy of the License at 8// 9// http://www.apache.org/licenses/LICENSE-2.0 10// 11// Unless required by applicable law or agreed to in writing, 12// software distributed under the License is distributed on an 13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 14// KIND, either express or implied. See the License for the 15// specific language governing permissions and limitations 16// under the License. 17 18include "../../format/Schema.fbs"; 19include "Literal.fbs"; 20 21namespace org.apache.arrow.computeir.flatbuf; 22 23/// Access a value for a given map key 24table MapKey { 25 /// Any expression can be a map key. 26 key: Expression (required); 27} 28 29/// Struct field access 30table StructField { 31 /// The position of the field in the struct schema 32 position: uint32; 33} 34 35/// Zero-based array index 36table ArraySubscript { 37 position: uint32; 38} 39 40/// Zero-based range of elements in an array 41table ArraySlice { 42 /// The start of an array slice, inclusive 43 start_inclusive: uint32; 44 /// The end of an array slice, exclusive 45 end_exclusive: uint32; 46} 47 48/// Field name in a relation, in ordinal position of the relation's schema. 49table FieldIndex { 50 position: uint32; 51} 52 53/// A union of possible dereference operations 54union Deref { 55 /// Access a value for a given map key 56 MapKey, 57 /// Access the value at a struct field 58 StructField, 59 /// Access the element at a given index in an array 60 ArraySubscript, 61 /// Access a range of elements in an array 62 ArraySlice, 63 /// Access a field of a relation 64 FieldIndex, 65} 66 67/// Access the data of a field 68table FieldRef { 69 ref: Deref (required); 70 /// For Expressions which might reference fields in multiple Relations, 71 /// this index may be provided to indicate which Relation's fields 72 /// `ref` points into. For example in the case of a join, 73 /// 0 refers to the left relation and 1 to the right relation. 74 relation_index: int = 0; 75} 76 77/// A function call expression 78table Call { 79 /// The function to call 80 name: string (required); 81 82 /// The arguments passed to `name`. 83 arguments: [Expression] (required); 84 85 /// Possible ordering of input. These are useful 86 /// in aggregates where ordering in meaningful such as 87 /// string concatenation 88 orderings: [SortKey]; 89} 90 91/// A single WHEN x THEN y fragment. 92table CaseFragment { 93 match: Expression (required); 94 result: Expression (required); 95} 96 97/// Conditional case statement expression 98table ConditionalCase { 99 /// List of conditions to evaluate 100 conditions: [CaseFragment] (required); 101 /// The default value if no cases match. This is typically NULL in SQL 102 /// implementations. 103 /// 104 /// Defaulting to NULL is a frontend choice, so producers must specify NULL 105 /// if that's their desired behavior. 106 else: Expression (required); 107} 108 109/// Switch-style case expression 110table SimpleCase { 111 /// The expression whose value will be matched 112 expression: Expression (required); 113 /// Matches for `expression` 114 matches: [CaseFragment] (required); 115 /// The default value if no cases match 116 else: Expression (required); 117} 118 119/// Whether lesser values should precede greater or vice versa, 120/// also whether nulls should preced or follow values 121enum Ordering : uint8 { 122 ASCENDING_THEN_NULLS, 123 DESCENDING_THEN_NULLS, 124 NULLS_THEN_ASCENDING, 125 NULLS_THEN_DESCENDING, 126} 127 128/// An expression with an order 129table SortKey { 130 expression: Expression (required); 131 ordering: Ordering = ASCENDING_THEN_NULLS; 132} 133 134/// An unbounded window bound 135table Unbounded {} 136 137/// A concrete bound, which can be an expression or unbounded 138union ConcreteBoundImpl { 139 Expression, 140 Unbounded, 141} 142 143/// Boundary is preceding rows, determined by the contained expression 144table Preceding { 145 impl: ConcreteBoundImpl (required); 146} 147 148/// Boundary is following rows, determined by the contained expression 149table Following { 150 impl: ConcreteBoundImpl (required); 151} 152 153/// Boundary is the current row 154table CurrentRow {} 155 156union Bound { 157 Preceding, 158 Following, 159 CurrentRow, 160} 161 162/// The kind of window function to be executed 163enum Frame : uint8 { 164 Rows, 165 Range, 166} 167 168/// An expression representing a window function call. 169table WindowCall { 170 /// The expression to operate over 171 expression: Expression (required); 172 /// The kind of window frame 173 kind: Frame; 174 /// Partition keys 175 partitions: [Expression] (required); 176 /// Sort keys 177 orderings: [SortKey] (required); 178 /// Lower window bound 179 lower_bound: Bound (required); 180 /// Upper window bound 181 upper_bound: Bound (required); 182} 183 184/// A cast expression 185table Cast { 186 /// The expression to cast 187 operand: Expression (required); 188 /// The type to cast to. This value is a `Field` to allow complete representation 189 /// of arrow types. 190 /// 191 /// `Type` is unable to completely represent complex types like lists and 192 /// maps. 193 to: org.apache.arrow.flatbuf.Field (required); 194} 195 196/// Various expression types 197/// 198/// WindowCall is a separate variant 199/// due to special options for each that don't apply to generic 200/// function calls. Again this is done to make it easier 201/// for consumers to deal with the structure of the operation 202union ExpressionImpl { 203 Literal, 204 FieldRef, 205 Call, 206 ConditionalCase, 207 SimpleCase, 208 WindowCall, 209 Cast, 210} 211 212/// Expression types 213/// 214/// Expressions have a concrete `impl` value, which is a specific operation. 215/// 216/// This is a workaround for flatbuffers' lack of support for direct use of 217/// union types. 218table Expression { 219 impl: ExpressionImpl (required); 220} 221 222root_type Expression; 223