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