github.com/cockroachdb/cockroachdb-parser@v0.23.3-0.20240213214944-911057d40c9a/pkg/sql/sessiondatapb/session_data.proto

// Copyright 2020 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.

syntax = "proto3";
package cockroach.sql.sessiondatapb;
option go_package = "github.com/cockroachdb/cockroach/pkg/sql/sessiondatapb";

import "sql/lex/encode.proto";
import "util/duration/duration.proto";
import "util/timeutil/pgdate/pgdate.proto";
import "gogoproto/gogo.proto";
import "google/protobuf/duration.proto";

// SessionData contains session parameters that are easily serializable and are
// required to be propagated to the remote nodes for the correct execution of
// DistSQL flows.
message SessionData {
  // Database indicates the "current" database for the purpose of resolving
  // names.
  string database = 1;
  // ApplicationName is the name of the application running the current
  // session. This can be used for logging and per-application statistics.
  string application_name = 2;
  // User is the name of the user logged into the session.
  string user_proto = 3 [(gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/security/username.SQLUsernameProto"];
  // DataConversion gives access to the data conversion configuration.
  DataConversionConfig data_conversion_config = 4 [(gogoproto.nullable) = false];
  // VectorizeMode indicates which kinds of queries to use vectorized execution
  // engine for.
  VectorizeExecMode vectorize_mode = 5;
  // TestingVectorizeInjectPanics indicates whether random panics are injected
  // into the vectorized flow execution. The goal of such behavior is making
  // sure that errors that are propagated as panics in the vectorized engine
  // are caught in all scenarios.
  bool testing_vectorize_inject_panics = 6;
  // DefaultIntSize specifies the size in bits or bytes (preferred) of how a
  // "naked" INT type should be parsed.
  int32 default_int_size = 7;
  // The name of the location according to whose current timezone we're going to
  // parse timestamps. Used to initialize sessiondata.SessionData.Location on
  // the remote nodes.
  //
  // Note that the current serialization of the time.Location objects as
  // strings has many drawbacks which could lead to unstable computation on the
  // remote nodes. See #36864 and
  // https://github.com/cockroachdb/cockroach/pull/55377#issuecomment-707794695
  // for more details.
  string location = 8;
  // SearchPath is a list of namespaces to search builtins in. Used to
  // initialize sessiondata.SessionData.SearchPath on the remote nodes.
  repeated string search_path = 9;
  string temporary_schema_name = 10;
  // SeqState gives access to the SQL sequences that have been manipulated by
  // the session.
  SequenceState seq_state = 11 [(gogoproto.nullable) = false];
  // WorkMemLimit determines how much RAM (in bytes) a single operation of a
  // single query can use before it has to spill to disk.
  int64 WorkMemLimit = 12;
  reserved 13;
  reserved 14;
  // LockTimeout is the maximum amount of time that a query will wait while
  // attempting to acquire a lock on a key or while blocking on an existing
  // lock in order to perform a non-locking read on a key.
  google.protobuf.Duration lock_timeout = 15 [(gogoproto.nullable) = false,
    (gogoproto.stdduration) = true];
  // Internal is true if this query came from InternalExecutor or an internal
  // planner.
  bool internal = 16;
  // OnUpdateRehomeRowEnabled controls whether the ON UPDATE rehome_row()
  // will actually trigger on row updates.
  bool on_update_rehome_row_enabled = 17;
  // JoinReaderOrderingStrategyBatchSize is the size limit on the input rows to
  // the joinReader processor (when ordering is required to be maintained) to
  // construct a single lookup KV batch.
  int64 join_reader_ordering_strategy_batch_size = 18;
  // ParallelizeMultiKeyLookupJoinsEnabled is true when the join reader should
  // parallelize lookup batches under all circumstances. Enabling this will
  // increase the speed of lookup joins when each input row might get multiple
  // looked up rows at the cost of increased memory usage.
  bool parallelize_multi_key_lookup_joins_enabled = 19;
  // TrigramSimilarityThreshold configures the value that's used to compare
  // trigram similarities to in order to evaluate the string % string overload.
  double trigram_similarity_threshold = 20;
  // Troubleshooting mode determines whether we refuse to do additional work
  // with the query (i.e. collect & emit telemetry data). Troubleshooting mode
  // is disabled by default.
  bool troubleshooting_mode = 21;
  // JoinReaderNoOrderingStrategyBatchSize is the size limit on the input rows
  // to the joinReader processor (when ordering is **not** required to be
  // maintained) to construct a single lookup KV batch.
  int64 join_reader_no_ordering_strategy_batch_size = 22;
  // JoinReaderIndexJoinStrategyBatchSize is the size limit on the input rows
  // to the joinReader processor (when performing index joins) to construct a
  // single lookup KV batch.
  int64 join_reader_index_join_strategy_batch_size = 23;
  // IndexJoinStreamerBatchSize is the size limit on the input rows to the
  // ColIndexJoin operator (when it is using the Streamer API) to construct a
  // single lookup KV batch.
  int64 index_join_streamer_batch_size = 24;
  // DirectColumnarScansEnabled indicates whether the COL_BATCH_RESPONSE scan
  // format should be used for ScanRequests and ReverseScanRequests whenever
  // possible.
  bool direct_columnar_scans_enabled = 25;
  // DefaultTextSearchConfig configures the default text search configuration
  // that is used for builtins like to_tsvector and to_tsquery if no
  // text search configuration is explicitly passed in.
  string default_text_search_config = 26;
  // StreamerAlwaysMaintainOrdering indicates that the SQL users of the Streamer
  // should always ask it to maintain the ordering, even when it might not be
  // strictly necessary for the query.
  //
  // This session variable is introduced as a possible workaround in case we
  // have more bugs like #113013.
  bool streamer_always_maintain_ordering = 27;
  // StreamerInOrderEagerMemoryUsageFraction controls the fraction of the
  // streamer's memory budget that might be used for issuing requests eagerly,
  // in the InOrder mode.
  double streamer_in_order_eager_memory_usage_fraction = 28;
  // StreamerOutOfOrderEagerMemoryUsageFraction controls the fraction of the
  // streamer's memory budget that might be used for issuing requests eagerly,
  // in the OutOfOrder mode.
  double streamer_out_of_order_eager_memory_usage_fraction = 29;
  // StreamerHeadOfLineOnlyFraction controls the fraction of the available
  // streamer's memory budget that will be used to set the TargetBytes limit on
  // head-of-the-line request in case the "eager" memory usage limit has been
  // exceeded.
  double streamer_head_of_line_only_fraction = 30;
  // DistSQLPlanGatewayBias controls the factor of times more partition spans
  // the gateway node is allowed to be assigned in the absence of a better
  // choice relative to the distribution of partition spans on other eligible
  // instances. Refer to `shouldPickGateway` for more details.
  //
  // This field is in SessionData because that is the format in which a job
  // serializes and stores session variables at the time of job creation. A job
  // could be adopted by any node in the cluster (not necessarily the gateway)
  // and so we will need this information available on all nodes.
  int64 distsql_plan_gateway_bias = 31;
}

// DataConversionConfig contains the parameters that influence the output
// of certain data types as strings or bytes.
message DataConversionConfig {
  // BytesEncodeFormat indicates how to encode byte arrays when converting to
  // string.
  BytesEncodeFormat bytes_encode_format = 1;
  // ExtraFloatDigits indicates the number of digits beyond the standard number
  // to use for float conversions.This must be set to a value between -15 and
  // 3, inclusive.
  int32 extra_float_digits = 2;
  // IntervalStyle indicates the style to parse and display intervals as.
  util.duration.IntervalStyle interval_style = 3;
  // DateStyle indicates the style to parse and display dates as.
  util.timeutil.pgdate.DateStyle date_style = 4 [(gogoproto.nullable) = false];
}

// VectorizeExecMode controls if an when the Executor executes queries using
// the columnar execution engine.
enum VectorizeExecMode {
  option (gogoproto.goproto_enum_prefix) = false;
  option (gogoproto.goproto_enum_stringer) = false;

  // VectorizeUnset means the VectorizeExecMode wasn't explicitly set. Having
  // the first enum value as zero is required by proto3. This is mapped to
  // VectorizeOn.
  unset = 0 [(gogoproto.enumvalue_customname) = "VectorizeUnset"];
  reserved 1;
  // VectorizeOn means that any supported queries will be run using the
  // columnar execution.
  on = 2 [(gogoproto.enumvalue_customname) = "VectorizeOn"];
  // VectorizeExperimentalAlways means that we attempt to vectorize all
  // queries; unsupported queries will fail. Mostly used for testing.
  experimental_always = 3 [(gogoproto.enumvalue_customname) = "VectorizeExperimentalAlways"];
  // VectorizeOff means that columnar execution is disabled.
  off = 4 [(gogoproto.enumvalue_customname) = "VectorizeOff"];
}

// SequenceState is used to marshall the sessiondata.SequenceState struct.
message SequenceState {
  // Seq represents the last value of one sequence modified by the session.
  message Seq {
    uint32 seq_id = 1 [(gogoproto.customname) = "SeqID"];
    int64 latest_val = 2;
  }

  repeated Seq seqs = 1;
  // last_seq_incremented is the id of the last sequence incremented by the
  // session. This field is filled in iff seqs is not empty.
  uint32 last_seq_incremented = 2;
}