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// Basic CRUD operations 30package Mysqlx.Crud; 31option java_package = "com.mysql.cj.x.protobuf"; 32 33import "mysqlx_expr.proto"; 34import "mysqlx_datatypes.proto"; 35 36// column definition 37message Column { 38 optional string name = 1; 39 optional string alias = 2; 40 repeated Mysqlx.Expr.DocumentPathItem document_path = 3; 41} 42 43// a projection 44// 45// :param source: the expression identifying an element from the source data 46// which can include a column identifier or any expression 47// :param alias: optional alias. Required for DOCUMENTs (clients may use 48// the source string as default) 49message Projection { 50 required Mysqlx.Expr.Expr source = 1; 51 optional string alias = 2; 52} 53 54// DataModel to use for filters, names, ... 55enum DataModel { 56 DOCUMENT = 1; 57 TABLE = 2; 58}; 59 60// collection 61message Collection { 62 required string name = 1; 63 optional string schema = 2; 64} 65 66// limit 67// 68// :param row_count: maximum rows to filter 69// :param offset: maximum rows to skip before applying the row_count 70message Limit { 71 required uint64 row_count = 1; 72 optional uint64 offset = 2; 73} 74 75// sort order 76message Order { 77 enum Direction { 78 ASC = 1; 79 DESC = 2; 80 }; 81 82 required Mysqlx.Expr.Expr expr = 1; 83 optional Direction direction = 2 [ default=ASC ]; 84} 85 86// update operations 87// 88// :param source: specification of the value to be updated 89// if data_model is TABLE, a column name may be specified and also a document path, if the column has type JSON 90// if data_model is DOCUMENT, only document paths are allowed 91// in both cases, schema and table must be not set 92// :param operation: the type of operation to be performed 93// :param value: an expression to be computed as the new value for the operation 94message UpdateOperation { 95 enum UpdateType { 96 SET = 1; // only allowed for TABLE 97 ITEM_REMOVE = 2; // no value (removes the identified path from a object or array) 98 ITEM_SET = 3; // sets the new value on the identified path 99 ITEM_REPLACE = 4; // replaces a value if the path exists 100 ITEM_MERGE = 5; // source and value must be documents 101 ARRAY_INSERT = 6; // insert the value in the array at the index identified in the source path 102 ARRAY_APPEND = 7; // append the value on the array at the identified path 103 } 104 required Mysqlx.Expr.ColumnIdentifier source = 1; 105 required UpdateType operation = 2; 106 optional Mysqlx.Expr.Expr value = 3; 107} 108 109// Find Documents/Rows in a Collection/Table 110// 111// .. uml:: 112// 113// client -> server: Find 114// ... one or more Resultset ... 115// 116// :param collection: collection to insert into 117// :param data_model: datamodel that the operations refer to 118// :param projection: list of column projections that shall be returned 119// :param args: values for parameters used in filter expression 120// :param criteria: filter criteria 121// :param limit: numbers of rows that shall be skipped and returned 122// :param order: sort-order in which the rows/document shall be returned in 123// :param grouping: column expression list for aggregation (GROUP BY) 124// :param grouping_criteria: filter criteria for aggregated groups 125// :Returns: :protobuf:msg:`Mysqlx.Resultset::` 126message Find { 127 required Collection collection = 2; 128 129 optional DataModel data_model = 3; 130 repeated Projection projection = 4; 131 optional Mysqlx.Expr.Expr criteria = 5; 132 repeated Mysqlx.Datatypes.Scalar args = 11; 133 optional Limit limit = 6; 134 repeated Order order = 7; 135 repeated Mysqlx.Expr.Expr grouping = 8; 136 optional Mysqlx.Expr.Expr grouping_criteria = 9; 137}; 138 139// Insert documents/rows into a collection/table 140// 141// :param collection: collection to insert into 142// :param data_model: datamodel that the operations refer to 143// :param projection: name of the columns to insert data into (empty if data_model is DOCUMENT) 144// :param row: set of rows to insert into the collection/table (a single expression with a JSON document literal or an OBJECT expression) 145// :param args: values for parameters used in row expressions 146// :Returns: :protobuf:msg:`Mysqlx.Resultset::` 147message Insert { 148 required Collection collection = 1; 149 150 optional DataModel data_model = 2; 151 repeated Column projection = 3; 152 153 message TypedRow { 154 repeated Mysqlx.Expr.Expr field = 1; 155 }; 156 repeated TypedRow row = 4; 157 repeated Mysqlx.Datatypes.Scalar args = 5; 158}; 159 160// Update documents/rows in a collection/table 161// 162// :param collection: collection to change 163// :param data_model: datamodel that the operations refer to 164// :param criteria: filter expression to match rows that the operations will apply on 165// :param args: values for parameters used in filter expression 166// :param limit: limits the number of rows to match 167// :param order: specifies order of matched rows 168// :param operation: list of operations to be applied. Valid operations will depend on the data_model. 169// :Returns: :protobuf:msg:`Mysqlx.Resultset::` 170message Update { 171 required Collection collection = 2; 172 173 optional DataModel data_model = 3; 174 optional Mysqlx.Expr.Expr criteria = 4; 175 repeated Mysqlx.Datatypes.Scalar args = 8; 176 optional Limit limit = 5; 177 repeated Order order = 6; 178 179 repeated UpdateOperation operation = 7; 180}; 181 182// Delete documents/rows from a Collection/Table 183// 184// :param collection: collection to change 185// :param data_model: datamodel that the operations refer to 186// :param criteria: filter expression to match rows that the operations will apply on 187// :param args: values for parameters used in filter expression 188// :param limit: limits the number of rows to match 189// :param order: specifies order of matched rows 190// :Returns: :protobuf:msg:`Mysqlx.Resultset::` 191message Delete { 192 required Collection collection = 1; 193 194 optional DataModel data_model = 2; 195 optional Mysqlx.Expr.Expr criteria = 3; 196 repeated Mysqlx.Datatypes.Scalar args = 6; 197 optional Limit limit = 4; 198 repeated Order order = 5; 199}; 200 201 202// ViewAlgorithm defines how MySQL Server processes the view 203enum ViewAlgorithm { 204 UNDEFINED =1; // MySQL chooses which algorithm to use 205 MERGE = 2; // the text of a statement that refers to the view and the view definition are merged 206 TEMPTABLE = 3; // the view are retrieved into a temporary table 207} 208 209// ViewSqlSecurity defines the security context in which the view is going to be 210// executed, this means that VIEW can be executed with current user permissions or 211// with permissions of the uses who defined the VIEW 212enum ViewSqlSecurity { 213 INVOKER = 1; 214 DEFINER = 2; 215} 216 217 218// ViewCheckOption limits the write operations done on a `VIEW` 219// (`INSERT`, `UPDATE`, `DELETE`) to rows in which the `WHERE` clause is `TRUE` 220enum ViewCheckOption { 221 LOCAL = 1; // the view WHERE clause is checked, but no underlying views are checked 222 CASCADED = 2; // the view WHERE clause is checked, then checking recurses to underlying views 223} 224 225 226// CreateView create view based on indicated Mysqlx.Crud.Find message 227// 228// param collection: name of the VIEW object, which should be created 229// param definer: user name of the definer, if the value isn't set then the definer is current user 230// param algorithm: defines how MySQL Server processes the view 231// param security: defines the security context in which the view is going be executed 232// param check: limits the write operations done on a VIEW 233// param column: defines the list of aliases for column names specified in `stmt` 234// param stmt: Mysqlx.Crud.Find message from which the SELECT statement is going to be build 235// param replace_existing: if true then suppress error when created view already exists; just replace it 236 237message CreateView { 238 required Collection collection = 1; 239 240 optional string definer = 2; 241 optional ViewAlgorithm algorithm = 3 [default = UNDEFINED]; 242 optional ViewSqlSecurity security = 4 [default = DEFINER]; 243 optional ViewCheckOption check = 5; 244 245 repeated string column = 6; 246 required Find stmt = 7; 247 optional bool replace_existing = 8 [default = false]; 248} 249 250 251// ModifyView modify existing view based on indicated Mysqlx.Crud.Find message 252// 253// param collection: name of the VIEW object, which should be modified 254// param definer: user name of the definer, if the value isn't set then the definer is current user 255// param algorithm: defined how MySQL Server processes the view 256// param security: defines the security context in which the view is going be executed 257// param check: limits the write operations done on a VIEW 258// param column: defines the list of aliases for column names specified in `stmt` 259// param stmt: Mysqlx.Crud.Find message from which the SELECT statement is going to be build 260 261message ModifyView { 262 required Collection collection = 1; 263 264 optional string definer = 2; 265 optional ViewAlgorithm algorithm = 3; 266 optional ViewSqlSecurity security = 4; 267 optional ViewCheckOption check = 5; 268 269 repeated string column = 6; 270 optional Find stmt = 7; 271} 272 273 274// DropView removing existing view 275// 276// param collection: name of the VIEW object, which should be deleted 277// param if_exists: if true then suppress error when deleted view does not exists 278 279message DropView { 280 required Collection collection = 1; 281 optional bool if_exists = 2 [ default = false ]; 282} 283