1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.bigtable.admin.v2; 18 19import "google/api/field_behavior.proto"; 20 21option csharp_namespace = "Google.Cloud.Bigtable.Admin.V2"; 22option go_package = "google.golang.org/genproto/googleapis/bigtable/admin/v2;admin"; 23option java_multiple_files = true; 24option java_outer_classname = "TypesProto"; 25option java_package = "com.google.bigtable.admin.v2"; 26option php_namespace = "Google\\Cloud\\Bigtable\\Admin\\V2"; 27option ruby_package = "Google::Cloud::Bigtable::Admin::V2"; 28 29// `Type` represents the type of data that is written to, read from, or stored 30// in Bigtable. It is heavily based on the GoogleSQL standard to help maintain 31// familiarity and consistency across products and features. 32// 33// For compatibility with Bigtable's existing untyped APIs, each `Type` includes 34// an `Encoding` which describes how to convert to/from the underlying data. 35// This might involve composing a series of steps into an "encoding chain," for 36// example to convert from INT64 -> STRING -> raw bytes. In most cases, a "link" 37// in the encoding chain will be based an on existing GoogleSQL conversion 38// function like `CAST`. 39// 40// Each link in the encoding chain also defines the following properties: 41// * Natural sort: Does the encoded value sort consistently with the original 42// typed value? Note that Bigtable will always sort data based on the raw 43// encoded value, *not* the decoded type. 44// - Example: STRING values sort in the same order as their UTF-8 encodings. 45// - Counterexample: Encoding INT64 to a fixed-width STRING does *not* 46// preserve sort order when dealing with negative numbers. 47// INT64(1) > INT64(-1), but STRING("-00001") > STRING("00001). 48// - The overall encoding chain sorts naturally if *every* link does. 49// * Self-delimiting: If we concatenate two encoded values, can we always tell 50// where the first one ends and the second one begins? 51// - Example: If we encode INT64s to fixed-width STRINGs, the first value 52// will always contain exactly N digits, possibly preceded by a sign. 53// - Counterexample: If we concatenate two UTF-8 encoded STRINGs, we have 54// no way to tell where the first one ends. 55// - The overall encoding chain is self-delimiting if *any* link is. 56// * Compatibility: Which other systems have matching encoding schemes? For 57// example, does this encoding have a GoogleSQL equivalent? HBase? Java? 58message Type { 59 // Bytes 60 // Values of type `Bytes` are stored in `Value.bytes_value`. 61 message Bytes { 62 // Rules used to convert to/from lower level types. 63 message Encoding { 64 // Leaves the value "as-is" 65 // * Natural sort? Yes 66 // * Self-delimiting? No 67 // * Compatibility? N/A 68 message Raw {} 69 70 // Which encoding to use. 71 oneof encoding { 72 // Use `Raw` encoding. 73 Raw raw = 1; 74 } 75 } 76 77 // The encoding to use when converting to/from lower level types. 78 Encoding encoding = 1; 79 } 80 81 // Int64 82 // Values of type `Int64` are stored in `Value.int_value`. 83 message Int64 { 84 // Rules used to convert to/from lower level types. 85 message Encoding { 86 // Encodes the value as an 8-byte big endian twos complement `Bytes` 87 // value. 88 // * Natural sort? No (positive values only) 89 // * Self-delimiting? Yes 90 // * Compatibility? 91 // - BigQuery Federation `BINARY` encoding 92 // - HBase `Bytes.toBytes` 93 // - Java `ByteBuffer.putLong()` with `ByteOrder.BIG_ENDIAN` 94 message BigEndianBytes { 95 // The underlying `Bytes` type, which may be able to encode further. 96 Bytes bytes_type = 1; 97 } 98 99 // Which encoding to use. 100 oneof encoding { 101 // Use `BigEndianBytes` encoding. 102 BigEndianBytes big_endian_bytes = 1; 103 } 104 } 105 106 // The encoding to use when converting to/from lower level types. 107 Encoding encoding = 1; 108 } 109 110 // A value that combines incremental updates into a summarized value. 111 // 112 // Data is never directly written or read using type `Aggregate`. Writes will 113 // provide either the `input_type` or `state_type`, and reads will always 114 // return the `state_type` . 115 message Aggregate { 116 // Computes the sum of the input values. 117 // Allowed input: `Int64` 118 // State: same as input 119 message Sum {} 120 121 // Type of the inputs that are accumulated by this `Aggregate`, which must 122 // specify a full encoding. 123 // Use `AddInput` mutations to accumulate new inputs. 124 Type input_type = 1; 125 126 // Output only. Type that holds the internal accumulator state for the 127 // `Aggregate`. This is a function of the `input_type` and `aggregator` 128 // chosen, and will always specify a full encoding. 129 Type state_type = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; 130 131 // Which aggregator function to use. The configured types must match. 132 oneof aggregator { 133 // Sum aggregator. 134 Sum sum = 4; 135 } 136 } 137 138 // The kind of type that this represents. 139 oneof kind { 140 // Bytes 141 Bytes bytes_type = 1; 142 143 // Int64 144 Int64 int64_type = 5; 145 146 // Aggregate 147 Aggregate aggregate_type = 6; 148 } 149} 150