github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/sql/execinfrapb/data.proto

// Copyright 2016 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.
//
// Data structures and basic infrastructure for distributed SQL APIs. See
// docs/RFCS/distributed_sql.md.
// All the concepts here are "physical plan" concepts.

syntax = "proto2";
// Beware! This package name must not be changed, even though it doesn't match
// the Go package name, because it defines the Protobuf message names which
// can't be changed without breaking backward compatibility.
package cockroach.sql.distsqlrun;
option go_package = "execinfrapb";

import "jobs/jobspb/jobs.proto";
import "roachpb/api.proto";
import "roachpb/data.proto";
import "roachpb/errors.proto";
import "errorspb/errors.proto";
import "sql/pgwire/pgerror/errors.proto";
import "sql/sqlbase/structured.proto";
import "sql/sqlbase/encoded_datum.proto";
import "sql/types/types.proto";
import "util/tracing/recorded_span.proto";
import "gogoproto/gogo.proto";

// Error is a generic representation including a string message.
message Error {
  option (gogoproto.goproto_stringer) = false;

  reserved 1,2;

  // full_error contains a structured errors with possibly multiple
  // wrapping layers implementing the errors.Cause() interface.
  optional errorspb.EncodedError full_error = 3;
}

message Expression {
  // Don't generate a typedecl, so we can add the LocalExpr field.
  option (gogoproto.typedecl) = false;
  option (gogoproto.goproto_stringer) = false;

  // TODO(radu): TBD how this will be used
  optional string version = 1 [(gogoproto.nullable) = false];

  // SQL expressions are passed as a string, with ordinal references
  // (@1, @2, @3 ..) used for "input" variables.
  optional string expr = 2 [(gogoproto.nullable) = false];
}

// Ordering defines an order - specifically a list of column indices and
// directions. See sqlbase.ColumnOrdering.
message Ordering {
  option (gogoproto.equal) = true;

  message Column {
    option (gogoproto.equal) = true;

    // The direction of the desired ordering for a column.
    enum Direction {
      ASC = 0;
      DESC = 1;
    }
    optional uint32 col_idx = 1 [(gogoproto.nullable) = false];
    optional Direction direction = 2 [(gogoproto.nullable) = false];
  }
  repeated Column columns = 1 [(gogoproto.nullable) = false];
}

// StreamEndpointSpec describes one of the endpoints (input or output) of a physical
// stream.
message StreamEndpointSpec {
  enum Type {
    // Stream that is part of the local flow.
    LOCAL = 0;
    // Stream that has the other endpoint on a different node.
    REMOTE = 1;
    // Special stream used when in "sync flow" mode. In this mode, we return
    // results directly as part of the RPC call that set up the flow. This saves
    // overhead (extra RPCs) compared to the normal mode where the RPC just sets
    // up the flow. This type can only be used with outbound endpoints.
    SYNC_RESPONSE = 2;
  }
  optional Type type = 1 [(gogoproto.nullable) = false];

  // The ID of this stream.
  //
  // For LOCAL streams, both ends of the stream are part of the flow on this
  // machine (and there must be a corresponding endpoint with the same ID).
  //
  // For REMOTE streams, this ID is used in the ProducerHeader when connecting to
  // the other host.
  //
  // For SYNC_RESPONSE streams, the ID is unused.
  optional int32 stream_id = 2 [(gogoproto.nullable) = false,
                                (gogoproto.customname) = "StreamID",
                                (gogoproto.casttype) = "StreamID"];
  // Node ID of the target host, only used for outgoing REMOTE streams.
  optional int32 target_node_id = 4 [(gogoproto.nullable) = false,
                                     (gogoproto.customname) = "TargetNodeID",
                                     (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
  reserved 3;
}

// InputSyncSpec is the specification for an input synchronizer; it decides how
// to interleave rows from multiple input streams.
message InputSyncSpec {
  enum Type {
    // Rows from the input streams are interleaved arbitrarily.
    UNORDERED = 0;
    // The input streams are guaranteed to be ordered according to the column
    // ordering field; rows from the streams are interleaved to preserve that
    // ordering.
    ORDERED = 1;
  }
  optional Type type = 1 [(gogoproto.nullable) = false];

  optional Ordering ordering = 2 [(gogoproto.nullable) = false];

  repeated StreamEndpointSpec streams = 3 [(gogoproto.nullable) = false];

  // Schema for the streams entering this synchronizer.
  repeated sql.sem.types.T column_types = 4;
}

// OutputRouterSpec is the specification for the output router of a processor;
// it decides how to send results to multiple output streams.
message OutputRouterSpec {
  enum Type {
    // Single output stream.
    PASS_THROUGH = 0;
    // Each row is sent to all output streams.
    MIRROR = 1;
    // Each row is sent to one stream, chosen by hashing certain columns of
    // the row (specified by the hash_columns field).
    BY_HASH = 2;
    // Each row is sent to one stream, chosen according to preset boundaries
    // for the values of certain columns of the row.
    BY_RANGE = 3;
  }
  optional Type type = 1 [(gogoproto.nullable) = false];
  repeated StreamEndpointSpec streams = 2 [(gogoproto.nullable) = false];

  // Only used for the BY_HASH type; these are the indexes of the columns we are
  // hashing.
  repeated uint32 hash_columns = 3;

  message RangeRouterSpec {
    message ColumnEncoding {
      // column is the index of a column to encode.
      optional uint32 column = 1 [(gogoproto.nullable) = false];
      // encoding specifies how a particular column is to be encoded for
      // generating the sort key for a row. This needs to correspond to the way
      // the Span.{start,end} keys have been generated.
      optional sqlbase.DatumEncoding encoding = 2 [(gogoproto.nullable) = false];
    }
    // Span matches bytes in [start, end).
    message Span {
      optional bytes start = 1;
      optional bytes end = 2;
      // stream is the index of the destination stream.
      optional int32 stream = 3 [(gogoproto.nullable) = false];
    }

    // spans is a slice of Span. Input matching a span will be routed to its
    // specified stream.
    repeated Span spans = 1 [(gogoproto.nullable) = false];
    // default_dest, if not nil, is the index of the stream to send rows that do
    // not match any span. If nil, a row that does not match a span will produce
    // an error in the router.
    optional int32 default_dest = 2;
    // encodings is a slice of columns and encodings. Each will be appended to a
    // []byte, which is used as input to the spans. Columns from the input rows
    // potentially need to be recoded to match the encoding used for the spans.
    repeated ColumnEncoding encodings = 3 [(gogoproto.nullable) = false];
  }
  optional RangeRouterSpec range_router_spec = 4 [(gogoproto.nullable) = false];

  // disable_buffering disables output buffering. Generally buffering should be
  // enabled to prevent deadlocks. However some plans are known not to deadlock,
  // and so can set this flag to prevent unbounded buffering causing OOMs.
  optional bool disable_buffering = 5 [(gogoproto.nullable) = false];
}

message DatumInfo {
  optional sqlbase.DatumEncoding encoding = 1 [(gogoproto.nullable) = false];
  optional sql.sem.types.T type = 2;
}

// ProducerHeader is a message that is sent once at the beginning of a stream.
message ProducerHeader {
  optional bytes flow_id = 1 [(gogoproto.nullable) = false,
                              (gogoproto.customname) = "FlowID",
                              (gogoproto.customtype) = "FlowID"];

  optional int32 stream_id = 2 [(gogoproto.nullable) = false,
                                (gogoproto.customname) = "StreamID",
                                (gogoproto.casttype) = "StreamID"];
}

// ProducerData is a message that can be sent multiple times as part of a stream
// from a producer to a consumer. It contains 0 or more rows and/or 0 or more
// metadata messages.
message ProducerData {
  // A bunch of rows, encoded. Each datum is encoded according to the
  // corresponding DatumInfo.
  optional bytes raw_bytes = 1;

  // In the special case when the stream contains empty rows, the count is
  // passed instead.
  optional int32 num_empty_rows = 3 [(gogoproto.nullable) = false];

  // A bunch of metadata messages.
  repeated RemoteProducerMetadata metadata = 2 [(gogoproto.nullable) = false];
}

message ProducerMessage {
  optional ProducerHeader header = 1;

  // Typing information. There will be one DatumInfo for each element in a row.
  // This field has to be populated on, or before, a ProducerMessage with data
  // in it, and can only be populated once. It can be nil if only zero length
  // rows will be sent.
  // TODO(andrei): It'd be nice if the typing information for streams would be
  // configured statically at plan creation time, instead of being discovered
  // dynamically through the first rows that flow.
  repeated DatumInfo typing = 2 [(gogoproto.nullable) = false];

  optional ProducerData data = 3 [(gogoproto.nullable) = false];
}

// RemoteProducerMetadata represents records that a producer wants to pass to
// a consumer, other than data rows. It's named RemoteProducerMetadata to not
// clash with ProducerMetadata, which is used internally within a node and has
// a different go error instead of a proto error inside.
message RemoteProducerMetadata {
  message RangeInfos {
    repeated roachpb.RangeInfo range_info = 1 [(gogoproto.nullable) = false];
  }
  message TraceData {
    repeated util.tracing.RecordedSpan collected_spans = 1 [(gogoproto.nullable) = false];
  }
  // RowNum is used to count the rows sent from a processor. It is used in tests
  // to check that metadata is propagated correctly.
  message RowNum {
    // The ID of the processor that is producing rows.
    optional string sender_id = 1 [(gogoproto.nullable) = false,
                                   (gogoproto.customname) = "SenderID"];
    // A running count of the number of rows emitted from the sender so far.
    optional int32 row_num = 2 [(gogoproto.nullable) = false];
    // When set, indicates that the row count contains the expected number of
    // RowNum messages with this ID.
    optional bool last_msg = 3 [(gogoproto.nullable) = false];
  }
  message SamplerProgress {
    // The number of rows processed by the sampler processor since the last
    // update.
    optional uint64 rows_processed = 1 [(gogoproto.nullable) = false];
    // Indicates that sample collection for histograms should be disabled,
    // likely because the sampler processor ran out of memory.
    optional bool histogram_disabled = 2 [(gogoproto.nullable) = false];
  }
  message BulkProcessorProgress {
     repeated roachpb.Span completed_spans = 1 [(gogoproto.nullable) = false];
     map<int32, float> completed_fraction = 2;
     map<int32, int64> resume_pos = 3;
  }
  // Metrics are unconditionally emitted by table readers.
  message Metrics {
    // Total number of bytes read while executing a statement.
    optional int64 bytes_read = 1 [(gogoproto.nullable) = false];
    // Total number of rows read while executing a statement.
    optional int64 rows_read = 2 [(gogoproto.nullable) = false];
  }
  oneof value {
    RangeInfos range_info = 1;
    Error error = 2;
    TraceData trace_data = 3;
    roachpb.LeafTxnFinalState leaf_txn_final_state = 4;
    RowNum row_num = 5;
    SamplerProgress sampler_progress = 7;
    Metrics metrics = 8;
    BulkProcessorProgress bulk_processor_progress = 9;
  }
  reserved 6;
}

// DistSQLVersionGossipInfo represents the DistSQL server version information
// that gets gossiped for each node. This is used by planners to avoid planning
// on nodes with incompatible version during rolling cluster updates.
//
// For the meaning of the fields, see the corresponding constants in
// distsqlrun/server.go.
message DistSQLVersionGossipInfo {
  optional uint32 version = 1 [(gogoproto.nullable) = false,
                               (gogoproto.casttype) = "DistSQLVersion"];

  optional uint32 min_accepted_version = 2 [(gogoproto.nullable) = false,
                                            (gogoproto.casttype) = "DistSQLVersion"];
}

// DistSQLDrainingInfo represents the DistSQL draining state that gets gossiped
// for each node. This is used by planners to avoid planning on nodes that are
// known to be draining.
message DistSQLDrainingInfo {
  optional bool draining = 1 [(gogoproto.nullable) = false];
}