google/bigtable/admin/v2/types.proto

// Copyright 2024 Google LLC
//
// Licensed 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.

syntax = "proto3";

package google.bigtable.admin.v2;

import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Cloud.Bigtable.Admin.V2";
option go_package = "google.golang.org/genproto/googleapis/bigtable/admin/v2;admin";
option java_multiple_files = true;
option java_outer_classname = "TypesProto";
option java_package = "com.google.bigtable.admin.v2";
option php_namespace = "Google\\Cloud\\Bigtable\\Admin\\V2";
option ruby_package = "Google::Cloud::Bigtable::Admin::V2";

// `Type` represents the type of data that is written to, read from, or stored
// in Bigtable. It is heavily based on the GoogleSQL standard to help maintain
// familiarity and consistency across products and features.
//
// For compatibility with Bigtable's existing untyped APIs, each `Type` includes
// an `Encoding` which describes how to convert to/from the underlying data.
// This might involve composing a series of steps into an "encoding chain," for
// example to convert from INT64 -> STRING -> raw bytes. In most cases, a "link"
// in the encoding chain will be based an on existing GoogleSQL conversion
// function like `CAST`.
//
// Each link in the encoding chain also defines the following properties:
//  * Natural sort: Does the encoded value sort consistently with the original
//    typed value? Note that Bigtable will always sort data based on the raw
//    encoded value, *not* the decoded type.
//     - Example: BYTES values sort in the same order as their raw encodings.
//     - Counterexample: Encoding INT64 to a fixed-width STRING does *not*
//       preserve sort order when dealing with negative numbers.
//       INT64(1) > INT64(-1), but STRING("-00001") > STRING("00001).
//     - The overall encoding chain has this property if *every* link does.
//  * Self-delimiting: If we concatenate two encoded values, can we always tell
//    where the first one ends and the second one begins?
//     - Example: If we encode INT64s to fixed-width STRINGs, the first value
//       will always contain exactly N digits, possibly preceded by a sign.
//     - Counterexample: If we concatenate two UTF-8 encoded STRINGs, we have
//       no way to tell where the first one ends.
//     - The overall encoding chain has this property if *any* link does.
//  * Compatibility: Which other systems have matching encoding schemes? For
//    example, does this encoding have a GoogleSQL equivalent? HBase? Java?
message Type {
  // Bytes
  // Values of type `Bytes` are stored in `Value.bytes_value`.
  message Bytes {
    // Rules used to convert to/from lower level types.
    message Encoding {
      // Leaves the value "as-is"
      // * Natural sort? Yes
      // * Self-delimiting? No
      // * Compatibility? N/A
      message Raw {}

      // Which encoding to use.
      oneof encoding {
        // Use `Raw` encoding.
        Raw raw = 1;
      }
    }

    // The encoding to use when converting to/from lower level types.
    Encoding encoding = 1;
  }

  // String
  // Values of type `String` are stored in `Value.string_value`.
  message String {
    // Rules used to convert to/from lower level types.
    message Encoding {
      // UTF-8 encoding
      // * Natural sort? No (ASCII characters only)
      // * Self-delimiting? No
      // * Compatibility?
      //    - BigQuery Federation `TEXT` encoding
      //    - HBase `Bytes.toBytes`
      //    - Java `String#getBytes(StandardCharsets.UTF_8)`
      message Utf8Raw {}

      // Which encoding to use.
      oneof encoding {
        // Use `Utf8Raw` encoding.
        Utf8Raw utf8_raw = 1;
      }
    }

    // The encoding to use when converting to/from lower level types.
    Encoding encoding = 1;
  }

  // Int64
  // Values of type `Int64` are stored in `Value.int_value`.
  message Int64 {
    // Rules used to convert to/from lower level types.
    message Encoding {
      // Encodes the value as an 8-byte big endian twos complement `Bytes`
      // value.
      // * Natural sort? No (positive values only)
      // * Self-delimiting? Yes
      // * Compatibility?
      //    - BigQuery Federation `BINARY` encoding
      //    - HBase `Bytes.toBytes`
      //    - Java `ByteBuffer.putLong()` with `ByteOrder.BIG_ENDIAN`
      message BigEndianBytes {
        // The underlying `Bytes` type, which may be able to encode further.
        Bytes bytes_type = 1;
      }

      // Which encoding to use.
      oneof encoding {
        // Use `BigEndianBytes` encoding.
        BigEndianBytes big_endian_bytes = 1;
      }
    }

    // The encoding to use when converting to/from lower level types.
    Encoding encoding = 1;
  }

  // A value that combines incremental updates into a summarized value.
  //
  // Data is never directly written or read using type `Aggregate`. Writes will
  // provide either the `input_type` or `state_type`, and reads will always
  // return the `state_type` .
  message Aggregate {
    // Computes the sum of the input values.
    // Allowed input: `Int64`
    // State: same as input
    message Sum {}

    // Type of the inputs that are accumulated by this `Aggregate`, which must
    // specify a full encoding.
    // Use `AddInput` mutations to accumulate new inputs.
    Type input_type = 1;

    // Output only. Type that holds the internal accumulator state for the
    // `Aggregate`. This is a function of the `input_type` and `aggregator`
    // chosen, and will always specify a full encoding.
    Type state_type = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Which aggregator function to use. The configured types must match.
    oneof aggregator {
      // Sum aggregator.
      Sum sum = 4;
    }
  }

  // The kind of type that this represents.
  oneof kind {
    // Bytes
    Bytes bytes_type = 1;

    // String
    String string_type = 2;

    // Int64
    Int64 int64_type = 5;

    // Aggregate
    Aggregate aggregate_type = 6;
  }
}