| // 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/consensus/metadata.proto"; |
| import "kudu/security/token.proto"; |
| import "kudu/util/pb_util.proto"; |
| |
| // All of the metadata required to create a KuduTable object in the C++ |
| // and Java clients. |
| // TODO(KUDU-3135): Use for generic metadata tokens outside of the scan token. |
| message TableMetadataPB { |
| optional string table_id = 1; |
| optional string table_name = 2; |
| optional int32 num_replicas = 3; |
| |
| optional SchemaPB schema = 4; |
| optional PartitionSchemaPB partition_schema = 5; |
| |
| // The table's extra configuration properties. |
| map<string, string> extra_configs = 6; |
| |
| optional string owner = 7; |
| } |
| |
| // Metdata about a single server. |
| // This can be used on the client to update the local cache of where |
| // each server is located. |
| message ServerMetadataPB { |
| optional bytes uuid = 1; |
| |
| repeated HostPortPB rpc_addresses = 2; |
| |
| // The location assignment for this server. |
| optional string location = 3; |
| } |
| |
| // All of the metadata required to create a RemoteTablet object in the C++ |
| // and Java clients. |
| message TabletMetadataPB { |
| |
| optional string tablet_id = 1; |
| |
| optional PartitionPB partition = 2; |
| |
| // The servers that host the replicas. |
| repeated ServerMetadataPB tablet_servers = 3; |
| |
| message ReplicaMetadataPB { |
| // The index of the tablet server in tablet_servers. |
| required uint32 ts_idx = 1; |
| required consensus.RaftPeerPB.Role role = 2; |
| optional string dimension_label = 3; |
| } |
| |
| repeated ReplicaMetadataPB replicas = 4; |
| |
| // Cached table locations should not live longer than this timeout. |
| // Note: Some time will pass between serializing and deserializing |
| // the token. This means that that effective TTL would be longer |
| // than initially set. This shouldn't be a problem in normal usage |
| // given the time shouldn't be an extended period. Additionally, |
| // the client can retry if any failures occur due to outdated metadata. |
| optional uint64 ttl_millis = 5; |
| } |
| |
| // 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; |
| |
| // Optional table metadata. If provided the scan token can avoid |
| // an extra GetTableSchema RPC call to the master. |
| // If set, neither table_id or table_name above are required. |
| optional TableMetadataPB table_metadata = 21; |
| |
| // Optional tablet metadata. If provided the scan token can avoid |
| // an extra GetTableLocations RPC call to the master. |
| optional TabletMetadataPB tablet_metadata = 22; |
| |
| // The index of which columns in table_metadata to select. |
| // This can be used in place of projected_columns if this |
| // scan token has table_metadata. |
| repeated int32 projected_column_idx = 23; |
| |
| // 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 op 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; |
| |
| // An authorization token with which to authorize the scan requests. |
| optional security.SignedTokenPB authz_token = 24; |
| } |
| |
| // 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; |
| } |