package salesforce.hyperdb.grpc.v1

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc ExecuteQuery (QueryParam, stream QueryResult)

  hyper_service.proto:19

  Execute a query / statement and retrieve its result. The result stream will always start with a result header (QueryResultHeader) and in case that data is returned the data will be streamed in chunks.

  message QueryParam

  hyper_service.proto:25

  QueryParam represents a query alongside with additional options to describe the execution context, like attached databases or parameters. Additionally, the output format for data chunks can be configured

  • string query = 1

    The SQL query text. See https://tableau.github.io/hyper-db/docs/sql/ for a documentation of Hyper's SQL.

  • repeated AttachedDatabase database = 2

    Specify the list of attached databases for this query

  • QueryParam.OutputFormat output_format = 3

    Specify the output format for query result data chunks. Default is text output.

  • map<string, string> params = 4

    Settings to allow adjusting the execution of a query. See https://tableau.github.io/hyper-db/docs/hyper-api/connection#connection-settings

  message QueryResult

  hyper_service.proto:73

  The result of a query, in a QueryResult stream the result header will always come first and will be followed by the configured result chunk type.

  • oneof result

    • QueryResultHeader header = 1

    • QueryBinaryResultChunk arrow_chunk = 4

    • QueryStringResultChunk qsv1_chunk = 5

Used in: QueryParam

• string path = 1

  Access path for the database

• string alias = 2

  Alias for the database under which it should be availabe in SQL

Describes a column

Used in: QueryResultSchema

• string name = 1

• optional SqlType type = 2

Error details for HyperService rpcs (defined in hyper_service.proto) This message is used in two ways: 1. by Hyper to report error information to its clients 2. by upstream services to report errors to Hyper We distuish between customer-visible information and internal ("system") information. Hyper makes sure to not expose the system-internal information via any of its public endpoints. Note for Upstream services: - Use `ErrorInfo` to enable Hyper to provide detailed error messages to customer and improved debuggability - When providing detailed information, you MUST provide both customer_detail and system_detail - If Hyper is unable to validate correctness of `ErrorInfo`, it will fallback to standard GRPC Error Model and map the error message to system_detail

• string primary_message = 1

  The primary (terse) error message MUST NOT contain sensitive data as it will be logged and returned to user MANDATORY FIELD

• string sqlstate = 2

  The SQL state error code Treated as InternalError, if empty

• string customer_hint = 3

  A suggestion on what what to do about the problem Differs from customer_detail by offering advise rather than hard facts Can be returned to the customer but MUST NOT be logged

• string customer_detail = 4

  Error detail with customer data classification Can be returned to the customer but MUST NOT be logged

• string system_detail = 5

  Error detail with system data classification Can be logged but MUST NOT be forwarded to untrusted clients or customers

• optional TextPosition position = 6

  Position information pertaining to the error This will be IGNORED for Error Info coming from upstream services of Hyper

• string error_source = 7

  The cause of the error ALLOWED values are "User" and "System" (case sensitive) Use "User" if and only if the error can only be caused by the end-user or customer

A result chunk which contains multiple rows encoded in the binary format requested via the `output_format` field of the `QueryParam` message

Used in: QueryResult

• bytes data = 127

Returned for statements, some statements additionally return the affected row count. The server will only send this message once the changes of the statement are committed successfully.

Used in: QueryResultHeader

• oneof command_return

  • google.protobuf.Empty empty = 2

  • uint64 affected_rows = 1

Currently supported output formats

Used in: QueryParam

• TEXT_DEBUG = 0

  Encode the result chunk in a text-based format intended for debugging gRPC on the command line. Currently, this format is the same as `QUERY_SERVICE_V1`, which encodes the result as a JSON array. However, this format might change in the future.

• ARROW_LEGACY = 2

  Do not use this format when onboarding any new workloads. `ARROW_STREAM` is strictly preferable. Encode the result chunk in a proprietary variant similar to the "Arrow IPC format". Each result chunk consists of a schema and a record batch message. This is the original format of the gRPC proxy. For the JDBC Tableau connector, this format is passed through directly to the public Data Cloud API endpoint. As such, we cannot just drop support for it.

• QUERY_SERVICE_V1 = 3

  Do not use this format when onboarding any new workloads. `ARROW_STREAM` is strictly preferable. Encode the result chunk as a JSON array of objects using the Query Service V1 SQL API convention.

• ARROW_STREAM = 4

  Encode the result chunk as part of a single Arrow IPC stream that encompasses all result chunks of a query. This means only the first result chunk contains a schema message. The following result chunks contain one or more record batch messages.

Describes the schema of the query result

Used in: QueryResult

• oneof header

  • QueryResultSchema schema = 1

    Returned for normal queries (i.e., SELECT)

  • QueryCommandOk command = 2

    Returned when the query was of statement type

Schema of the query result

Used in: QueryResultHeader

• repeated ColumnDescription column = 1

A result chunk which contains multiple rows encoded in the textual format requested via the `output_format` field of the `QueryParam` message

Used in: QueryResult

• string data = 127

Type of a result column, provides additional information through the modifier field

Used in: ColumnDescription

• SqlType.TypeTag tag = 1

  Matches hyperapi::SqlType enum

• oneof modifier

  Additional type information, e.g. about precision

  • google.protobuf.Empty empty = 2

  • uint32 max_length = 3

    Only available if tag is a text type

  • SqlType.NumericModifier numeric_modifier = 4

    Only available if tag is a numeric type

The precision of a numeric column

Used in: SqlType

• uint32 precision = 1

• uint32 scale = 2

Used in: SqlType

• HYPER_UNSUPPORTED = 0

• HYPER_BOOL = 1

• HYPER_BIG_INT = 2

• HYPER_SMALL_INT = 3

• HYPER_INT = 4

• HYPER_NUMERIC = 5

• HYPER_DOUBLE = 6

• HYPER_OID = 7

• HYPER_BYTE_A = 8

• HYPER_TEXT = 9

• HYPER_VARCHAR = 10

• HYPER_CHAR = 11

• HYPER_JSON = 12

• HYPER_DATE = 13

• HYPER_INTERVAL = 14

• HYPER_TIME = 15

• HYPER_TIMESTAMP = 16

• HYPER_TIMESTAMP_TZ = 17

• HYPER_GEOGRAPHY = 18

Positional information on the error, references the user-provided SQL text

Used in: ErrorInfo

• uint64 error_begin_character_offset = 2

  Start offset, measured in unicode code points

• uint64 error_end_character_offset = 3

  End offset, measured in unicode code points