text: /*
   * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
   *
   * This program is free software; you can redistribute it and/or modify
   * it under the terms of the GNU General Public License, version 2.0,
   * as published by the Free Software Foundation.
   *
   * This program is also distributed with certain software (including
   * but not limited to OpenSSL) that is licensed under separate terms,
   * as designated in a particular file or component or in included license
   * documentation.  The authors of MySQL hereby grant you an additional
   * permission to link the program and your derivative works with the
   * separately licensed software that they have included with MySQL.
   *  
   * This program is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU General Public License, version 2.0, for more details.
   *
   * You should have received a copy of the GNU General Public License
   * along with this program; if not, write to the Free Software
   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
   */
  syntax = "proto2";
  
  
  // ifdef PROTOBUF_LITE: option optimize_for = LITE_RUNTIME;
  
  // Basic CRUD operations
  package Mysqlx.Crud;
  option java_package = "com.mysql.cj.x.protobuf";
  
  import "mysqlx.proto"; // comment_out_if PROTOBUF_LITE
  import "mysqlx_expr.proto";
  import "mysqlx_datatypes.proto";
  
  // column definition
  message Column {
    optional string name = 1;
    optional string alias = 2;
    repeated Mysqlx.Expr.DocumentPathItem document_path = 3;
  }
  
  // a projection
  //
  // :param source: the expression identifying an element from the source data
  //                which can include a column identifier or any expression
  // :param alias: optional alias. Required for DOCUMENTs (clients may use 
  //              the source string as default)
  message Projection {
      required Mysqlx.Expr.Expr source = 1;
      optional string alias = 2;
  }
  
  // DataModel to use for filters, names, ...
  enum DataModel {
    DOCUMENT = 1;
    TABLE = 2;
  };
  
  // collection
  message Collection {
    required string name = 1;
    optional string schema = 2;
  }
  
  // limit
  //
  // :param row_count: maximum rows to filter
  // :param offset: maximum rows to skip before applying the row_count
  message Limit {
    required uint64 row_count = 1 /* ifdef PROTOBUF3 [jstype = JS_STRING] */;
    optional uint64 offset = 2 /* ifdef PROTOBUF3 [jstype = JS_STRING] */;
  }
  
  // limit expression
  //
  // LimitExpr in comparison to Limit, is able to specify that row_count and
  // offset are placeholders.
  // This message support expressions of following types Expr/literal/UINT,
  // Expr/PLACEHOLDER.
  //
  // :param row_count: maximum rows to filter
  // :param offset: maximum rows to skip before applying the row_count
  message LimitExpr {
    required Mysqlx.Expr.Expr row_count = 1;
    optional Mysqlx.Expr.Expr offset = 2;
  }
  
  // sort order
  message Order {
    enum Direction {
      ASC = 1;
      DESC = 2;
    };
  
    required Mysqlx.Expr.Expr expr = 1;
    optional Direction direction = 2 [ default=ASC ];
  }
  
  // update operations
  //
  // :param source: specification of the value to be updated
  //      if data_model is TABLE, a column name may be specified and also a document path, if the column has type JSON
  //      if data_model is DOCUMENT, only document paths are allowed
  //      in both cases, schema and table must be not set
  // :param operation: the type of operation to be performed
  // :param value: an expression to be computed as the new value for the operation
  message UpdateOperation {
    enum UpdateType {
      SET = 1;            // only allowed for TABLE
      ITEM_REMOVE = 2;    // no value (removes the identified path from a object or array)
      ITEM_SET = 3;       // sets the new value on the identified path
      ITEM_REPLACE = 4;   // replaces a value if the path exists
      ITEM_MERGE = 5;     // source and value must be documents
      ARRAY_INSERT = 6;   // insert the value in the array at the index identified in the source path
      ARRAY_APPEND = 7;   // append the value on the array at the identified path
      MERGE_PATCH = 8;    // merge JSON object value with the provided patch expression
    }
    required Mysqlx.Expr.ColumnIdentifier source = 1;
    required UpdateType operation = 2;
    optional Mysqlx.Expr.Expr value = 3;
  }
  
  // Find Documents/Rows in a Collection/Table
  //
  // .. uml::
  //
  //   client -> server: Find
  //   ... one or more Resultset ...
  //
  // :param collection: collection to insert into
  // :param data_model: datamodel that the operations refer to
  // :param projection: list of column projections that shall be returned
  // :param args: values for parameters used in filter expression
  // :param criteria: filter criteria
  // :param limit: numbers of rows that shall be skipped and returned (user can set one of: limit, limit_expr)
  // :param order: sort-order in which the rows/document shall be returned in
  // :param grouping: column expression list for aggregation (GROUP BY)
  // :param grouping_criteria: filter criteria for aggregated groups
  // :param locking: perform row locking on matches
  // :param locking_options: additional options how to handle locked rows
  // :param limit_expr: numbers of rows that shall be skipped and returned (user can set one of: limit, limit_expr)
  // :Returns: :protobuf:msg:`Mysqlx.Resultset::`
  message Find {
    enum RowLock {
      SHARED_LOCK = 1;   // Lock matching rows against updates
      EXCLUSIVE_LOCK = 2;  // Lock matching rows so no other transaction can read or write to it
    };
  
    enum RowLockOptions {
      NOWAIT = 1;   // Do not wait to acquire row lock, fail with an error if a requested row is locked
      SKIP_LOCKED = 2;  // Do not wait to acquire a row lock, remove locked rows from the result set
    };
  
    required Collection collection = 2;
  
    optional DataModel data_model = 3;
    repeated Projection projection = 4;
    optional Mysqlx.Expr.Expr criteria = 5;
    repeated Mysqlx.Datatypes.Scalar args = 11;
    repeated Order order = 7;
    repeated Mysqlx.Expr.Expr grouping = 8;
    optional Mysqlx.Expr.Expr grouping_criteria = 9;
    optional RowLock locking = 12;
    optional RowLockOptions locking_options = 13;
    optional Limit limit = 6;
    optional LimitExpr limit_expr = 14;
  
    option (client_message_id) = CRUD_FIND; // comment_out_if PROTOBUF_LITE
  };
  
  // Insert documents/rows into a collection/table
  //
  // :param collection: collection to insert into
  // :param data_model: datamodel that the operations refer to
  // :param projection: name of the columns to insert data into (empty if data_model is DOCUMENT)
  // :param row: set of rows to insert into the collection/table (a single expression with a JSON document literal or an OBJECT expression)
  // :param args: values for parameters used in row expressions
  // :param upsert: true if this should be treated as an Upsert (that is, update on duplicate key)
  // :Returns: :protobuf:msg:`Mysqlx.Resultset::`
  message Insert {
    required Collection collection = 1;
  
    optional DataModel data_model = 2;
    repeated Column projection = 3;
  
    message TypedRow {
      repeated Mysqlx.Expr.Expr field = 1;
    };
    repeated TypedRow row = 4;
    repeated Mysqlx.Datatypes.Scalar args = 5;
    optional bool upsert = 6 [default = false];
  
    option (client_message_id) = CRUD_INSERT; // comment_out_if PROTOBUF_LITE
  };
  
  // Update documents/rows in a collection/table
  //
  // :param collection: collection to change
  // :param data_model: datamodel that the operations refer to
  // :param criteria: filter expression to match rows that the operations will apply on
  // :param args: values for parameters used in filter expression
  // :param limit: limits the number of rows to match (user can set one of: limit, limit_expr)
  // :param order: specifies order of matched rows
  // :param operation: list of operations to be applied. Valid operations will depend on the data_model.
  // :param limit_expr: limits the number of rows to match (user can set one of: limit, limit_expr)
  // :Returns: :protobuf:msg:`Mysqlx.Resultset::`
  message Update {
    required Collection collection = 2;
  
    optional DataModel data_model = 3;
    optional Mysqlx.Expr.Expr criteria = 4;
    repeated Mysqlx.Datatypes.Scalar args = 8;
    repeated Order order = 6;
  
    repeated UpdateOperation operation = 7;
  
    optional Limit limit = 5;
    optional LimitExpr limit_expr = 9;
  
    option (client_message_id) = CRUD_UPDATE; // comment_out_if PROTOBUF_LITE
  };
  
  // Delete documents/rows from a Collection/Table
  //
  // :param collection: collection to change
  // :param data_model: datamodel that the operations refer to
  // :param criteria: filter expression to match rows that the operations will apply on
  // :param args: values for parameters used in filter expression
  // :param limit: limits the number of rows to match (user can set one of: limit, limit_expr)
  // :param order: specifies order of matched rows
  // :param limit_expr: limits the number of rows to match (user can set one of: limit, limit_expr)
  // :Returns: :protobuf:msg:`Mysqlx.Resultset::`
  message Delete {
    required Collection collection = 1;
  
    optional DataModel data_model = 2;
    optional Mysqlx.Expr.Expr criteria = 3;
    repeated Mysqlx.Datatypes.Scalar args = 6;
    repeated Order order = 5;
  
    optional Limit limit = 4;
    optional LimitExpr limit_expr = 7;
  
    option (client_message_id) = CRUD_DELETE; // comment_out_if PROTOBUF_LITE
  };
  
  
  // ViewAlgorithm defines how MySQL Server processes the view
  enum ViewAlgorithm {
    UNDEFINED =1;   // MySQL chooses which algorithm to use
    MERGE = 2;      // the text of a statement that refers to the view and the view definition are merged
    TEMPTABLE = 3;  // the view are retrieved into a temporary table
  }
  
  // ViewSqlSecurity defines the security context in which the view is going to be
  // executed, this means that VIEW can be executed with current user permissions or
  // with permissions of the uses who defined the VIEW
  enum ViewSqlSecurity {
    INVOKER = 1;
    DEFINER = 2;
  }
  
  
  // ViewCheckOption limits the write operations done on a `VIEW`
  // (`INSERT`, `UPDATE`, `DELETE`) to rows in which the `WHERE` clause is `TRUE`
  enum ViewCheckOption {
    LOCAL = 1;     // the view WHERE clause is checked, but no underlying views are checked
    CASCADED = 2;  // the view WHERE clause is checked, then checking recurses to underlying views
  }
  
  
  // CreateView create view based on indicated Mysqlx.Crud.Find message
  //
  // param collection: name of the VIEW object, which should be created
  // param definer: user name of the definer, if the value isn't set then the definer is current user
  // param algorithm: defines how MySQL Server processes the view
  // param security: defines the security context in which the view is going be executed
  // param check: limits the write operations done on a VIEW
  // param column: defines the list of aliases for column names specified in `stmt`
  // param stmt: Mysqlx.Crud.Find message from which the SELECT statement is going to be build
  // param replace_existing: if true then suppress error when created view already exists; just replace it
  
  message CreateView {
    required Collection collection = 1;
  
    optional string definer = 2;
    optional ViewAlgorithm algorithm = 3 [default = UNDEFINED];
    optional ViewSqlSecurity security = 4 [default = DEFINER];
    optional ViewCheckOption check = 5;
  
    repeated string column = 6;
    required Find stmt = 7;
    optional bool replace_existing = 8 [default = false];
  
    option (client_message_id) = CRUD_CREATE_VIEW; // comment_out_if PROTOBUF_LITE
  }
  
  
  // ModifyView modify existing view based on indicated Mysqlx.Crud.Find message
  //
  // param collection: name of the VIEW object, which should be modified
  // param definer: user name of the definer, if the value isn't set then the definer is current user
  // param algorithm: defined how MySQL Server processes the view
  // param security: defines the security context in which the view is going be executed
  // param check: limits the write operations done on a VIEW
  // param column: defines the list of aliases for column names specified in `stmt`
  // param stmt: Mysqlx.Crud.Find message from which the SELECT statement is going to be build
  
  message ModifyView {
    required Collection collection = 1;
  
    optional string definer = 2;
    optional ViewAlgorithm algorithm = 3;
    optional ViewSqlSecurity security = 4;
    optional ViewCheckOption check = 5;
  
    repeated string column = 6;
    optional Find stmt = 7;
  
    option (client_message_id) = CRUD_MODIFY_VIEW; // comment_out_if PROTOBUF_LITE
  }
  
  
  // DropView removing existing view
  //
  // param collection: name of the VIEW object, which should be deleted
  // param if_exists: if true then suppress error when deleted view does not exists
  
  message DropView {
    required Collection collection = 1;
    optional bool if_exists = 2 [ default = false ];
  
    option (client_message_id) = CRUD_DROP_VIEW; // comment_out_if PROTOBUF_LITE
  }
  