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