src/kudu/client/client.proto

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

// Protobufs which are specific to client implementations.
syntax = "proto2";
package kudu.client;

option java_package = "org.apache.kudu.client";

import "kudu/common/common.proto";
import "kudu/security/token.proto";
import "kudu/util/pb_util.proto";

// Serialization format for client scan tokens. Scan tokens are serializable
// scan descriptors that are used by query engines to plan a set of parallizable
// scanners that are executed on remote task runners. The scan token protobuf
// format includes all of the information necessary to recreate a scanner in the
// remote task.
message ScanTokenPB {

  // Features used by the scan token message. Every time the ScanTokenPB message
  // is updated with a new feature, the feature should be added to this enum, so
  // that clients that lack the feature can recognize when they receive a token
  // that uses unknown features.
  enum Feature {
    Unknown = 0;
  }

  // The feature set used by this scan token.
  repeated Feature feature_flags = 1;

  // The table to scan. To remain backwards compatible, clients should set
  // both the table name and the table id, but should prefer to use the id
  // when rehydrating the scanner because the id cannot change.
  optional string table_id = 20;
  optional string table_name = 2;

  // Which columns to select.
  // if this is an empty list, no data will be returned, but the num_rows
  // field of the returned RowBlock will indicate how many rows passed
  // the predicates. Note that in some cases, the scan may still require
  // multiple round-trips, and the caller must aggregate the counts.
  repeated ColumnSchemaPB projected_columns = 3;

  // Any column predicates to enforce.
  repeated ColumnPredicatePB column_predicates = 4;

  // Encoded primary key to begin scanning at (inclusive).
  optional bytes lower_bound_primary_key = 5 [(kudu.REDACT) = true];

  // Encoded primary key to stop scanning at (exclusive).
  optional bytes upper_bound_primary_key = 6 [(kudu.REDACT) = true];

  // Encoded partition key to begin scanning at (inclusive).
  optional bytes lower_bound_partition_key = 7 [(kudu.REDACT) = true];

  // Encoded partition key to stop scanning at (exclusive).
  optional bytes upper_bound_partition_key = 8 [(kudu.REDACT) = true];

  // The maximum number of rows to scan.
  // The scanner will automatically stop yielding results and close
  // itself after reaching this number of result rows.
  optional uint64 limit = 9;

  // The read mode for this scan request.
  // See common.proto for further information about read modes.
  optional ReadMode read_mode = 10 [default = READ_LATEST];

  // The requested snapshot timestamp. This is only used
  // when the read mode is set to READ_AT_SNAPSHOT.
  optional fixed64 snap_timestamp = 11;

  // The requested snapshot start timestamp. This is only used
  // when the read mode is set to READ_AT_SNAPSHOT.
  // Setting this indicates the scan should be a diff scan, the
  // snap_timestamp will be used as the snapshot end timestamp.
  optional fixed64 snap_start_timestamp = 19;

  // Sent by clients which previously executed CLIENT_PROPAGATED writes.
  // This updates the server's time so that no transaction will be assigned
  // a timestamp lower than or equal to 'previous_known_timestamp'
  optional fixed64 propagated_timestamp = 12;

  // Whether data blocks will be cached when read from the files or discarded after use.
  // Disable this to lower cache churn when doing large scans.
  optional bool cache_blocks = 13 [default = true];

  // Whether the scan should be fault tolerant.
  optional bool fault_tolerant = 14 [default = false];

  // The maximum number of bytes to send in the response.
  // This is a hint, not a requirement: the server may send
  // arbitrarily fewer or more bytes than requested.
  optional uint32 batch_size_bytes = 15;

  // The replica selection policy for the scan request.
  // See common.proto for further information about replica selections.
  optional ReplicaSelection replica_selection = 16 [default = LEADER_ONLY];

  // The maximum length of time, in milliseconds, that each scan request to a
  // server can take. If not set, the default value is controlled by the client
  // scanner implementation.
  optional int64 scan_request_timeout_ms = 17;

  // The period, in milliseconds, at which to send keep-alive requests to the tablet
  // server to ensure this scanner won't time out.
  optional int64 keep_alive_period_ms = 18;
}

// All of the data necessary to authenticate to a cluster from a client with
// no Kerberos credentials.
message AuthenticationCredentialsPB {

  // A signed token with user credentials issued by the master.
  optional security.SignedTokenPB authn_token = 1;

  // The real user name, used for SASL PLAIN authentication.
  optional string real_user = 3;

  // Trusted root CA certificates.
  repeated bytes ca_cert_ders = 2;
}