1/*
2 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License as
6 * published by the Free Software Foundation; version 2 of the
7 * License.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
17 * 02110-1301  USA
18 */
19syntax = "proto2";
20
21option optimize_for = LITE_RUNTIME;
22
23// Expression syntax
24//
25// expr is the fundamental structure in various places
26// of the SQL language:
27//
28// * ``SELECT <expr> AS ...``
29// * ``WHERE <expr>``
30//
31// The structures can be used to:
32//
33// * build an Item-tree in the MySQL Server
34// * generate SQL from it
35// * use as filter condition in CRUD's Find(), Update() and Delete() calls.
36package Mysqlx.Expr;
37option java_package = "com.mysql.cj.mysqlx.protobuf";
38
39import "mysqlx_datatypes.proto";
40
41// Expressions
42//
43// the "root" of the expression tree
44//
45// .. productionlist::
46//   expr: `operator` |
47//       : `identifier` |
48//       : `function_call` |
49//       : variable |
50//       : `literal` |
51//       : placeholder
52//
53// If expression type is PLACEHOLDER then it refers to the value of a parameter
54// specified when executing a statement (see `args` field of `StmtExecute` command).
55// Field `position` (which must be present for such an expression) gives 0-based
56// position of the parameter in the parameter list.
57//
58message Expr {
59  enum Type {
60    IDENT          = 1;
61    LITERAL        = 2;
62    VARIABLE       = 3;
63    FUNC_CALL      = 4;
64    OPERATOR       = 5;
65    PLACEHOLDER    = 6;
66    OBJECT         = 7;
67    ARRAY          = 8;
68  };
69
70  required Type type = 1;
71
72  optional ColumnIdentifier identifier = 2;
73  optional string       variable = 3;
74  optional Mysqlx.Datatypes.Scalar literal = 4;
75  optional FunctionCall function_call = 5;
76  optional Operator     operator = 6;
77  optional uint32       position = 7;
78  optional Object       object = 8;
79  optional Array        array = 9;
80}
81
82// identifier: name, schame.name
83//
84// .. productionlist::
85//   identifier: string "." string |
86//             : string
87message Identifier {
88  required string name = 1;
89  optional string schema_name = 2;
90}
91
92// DocumentPathItem
93//
94// .. productionlist::
95//    document_path: path_item | path_item document_path
96//    path_item    : member | array_index | "**"
97//    member       : "." string | "." "*"
98//    array_index  : "[" number "]" | "[" "*" "]"
99//
100message DocumentPathItem {
101  enum Type {
102    MEMBER = 1;             // .member
103    MEMBER_ASTERISK = 2;    // .*
104    ARRAY_INDEX = 3;        // [index]
105    ARRAY_INDEX_ASTERISK = 4; // [*]
106    DOUBLE_ASTERISK = 5;    // **
107  };
108  required Type type = 1;
109  optional string value = 2;
110  optional uint32 index = 3;
111}
112
113
114// col_identifier (table): col@doc_path, tbl.col@doc_path col, tbl.col, schema.tbl.col
115// col_identifier (document): doc_path
116//
117// .. productionlist::
118//   col_identifier: string "." string "." string |
119//             : string "." string |
120//             : string |
121//             : string "." string "." string "@" document_path |
122//             : string "." string "@" document_path |
123//             : string "@" document_path |
124//             : document_path
125//    document_path: member | arrayLocation | doubleAsterisk
126//    member = "." string | "." "*"
127//    arrayLocation = "[" index "]" | "[" "*" "]"
128//    doubleAsterisk = "**"
129//
130message ColumnIdentifier {
131  repeated Mysqlx.Expr.DocumentPathItem document_path = 1;
132  optional string name = 2;
133  optional string table_name = 3;
134  optional string schema_name = 4;
135}
136
137// function call: ``func(a, b, "1", 3)``
138//
139// .. productionlist::
140//   function_call: `identifier` "(" [ `expr` ["," `expr` ]* ] ")"
141message FunctionCall {
142  required Identifier name = 1;
143  repeated Expr param = 2;
144}
145
146// operator: ``<<(a, b)``
147//
148// .. note::
149//
150//   Non-authoritative list of operators implemented (case sensitive):
151//
152//   Nullary
153//     * ``*``
154//     * ``default``
155//
156//   Unary
157//     * ``!``
158//     * ``sign_plus``
159//     * ``sign_minus``
160//     * ``~``
161//
162//   Binary
163//     * ``&&``
164//     * ``||``
165//     * ``xor``
166//     * ``==``
167//     * ``!=``
168//     * ``>``
169//     * ``>=``
170//     * ``<``
171//     * ``<=``
172//     * ``&``
173//     * ``|``
174//     * ``^``
175//     * ``<<``
176//     * ``>>``
177//     * ``+``
178//     * ``-``
179//     * ``*``
180//     * ``/``
181//     * ``div``
182//     * ``%``
183//     * ``is``
184//     * ``is_not``
185//     * ``regexp``
186//     * ``not_regexp``
187//     * ``like``
188//     * ``not_like``
189//     * ``cast``
190//
191//   Using special representation, with more than 2 params
192//     * ``in`` (param[0] IN (param[1], param[2], ...))
193//     * ``not_in`` (param[0] NOT IN (param[1], param[2], ...))
194//
195//   Ternary
196//     * ``between``
197//     * ``between_not``
198//     * ``date_add``
199//     * ``date_sub``
200//
201//   Units for date_add/date_sub
202//     * ``MICROSECOND``
203//     * ``SECOND``
204//     * ``MINUTE``
205//     * ``HOUR``
206//     * ``DAY``
207//     * ``WEEK``
208//     * ``MONTH``
209//     * ``QUARTER``
210//     * ``YEAR``
211//     * ``SECOND_MICROSECOND``
212//     * ``MINUTE_MICROSECOND``
213//     * ``MINUTE_SECOND``
214//     * ``HOUR_MICROSECOND``
215//     * ``HOUR_SECOND``
216//     * ``HOUR_MINUTE``
217//     * ``DAY_MICROSECOND``
218//     * ``DAY_SECOND``
219//     * ``DAY_MINUTE``
220//     * ``DAY_HOUR``
221//
222//   Types for cast
223//     * ``BINARY[(N)]``
224//     * ``CHAR[(N)]``
225//     * ``DATE``
226//     * ``DATETIME``
227//     * ``DECIMAL[(M[,D])]``
228//     * ``JSON``
229//     * ``SIGNED [INTEGER]``
230//     * ``TIME``
231//     * ``UNSIGNED [INTEGER]``
232//
233// .. productionlist::
234//   operator: `name` "(" [ `expr` ["," `expr` ]* ] ")"
235message Operator {
236  required string name = 1;
237  repeated Expr param = 2;
238}
239
240// an object (with expression values)
241message Object {
242  message ObjectField {
243    required string key = 1;
244    required Expr value = 2;
245  }
246
247  repeated ObjectField fld = 1;
248}
249
250// a Array of expressions
251message Array {
252  repeated Expr value = 1;
253}
254