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.

package kudu.client;

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

import "kudu/common/common.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.
  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;

  // Encoded primary key to stop scanning at (exclusive).
  optional bytes upper_bound_primary_key = 6;

  // Encoded partition key to begin scanning at (inclusive).
  optional bytes lower_bound_partition_key = 7;

  // Encoded partition key to stop scanning at (exclusive).
  optional bytes upper_bound_partition_key = 8;

  // 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;

  // 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];
}