Documentation
¶
Overview ¶
The Statement Execution API v2 can be used to execute SQL statements on a SQL warehouse and fetch the result. It works the same as the Statement Execution API (v1), except that `warehouse_id` is a path parameter on every call, including polling, fetching result chunks, and canceling. Routing on the warehouse ID gives lower latency and higher concurrency.
Version 2 currently supports Lakehouse//RT warehouses only. For other warehouse types, use the Statement Execution API (v1). You can also run statements on Lakehouse//RT warehouses with version 1, but version 2 is optimized for them.
Index ¶
- type BaseChunkInfo
- type CancelStatementRequest
- type CancelStatementResponse
- type ColumnInfo
- type ColumnTypeName
- type ExecuteStatementRequest
- type ExternalLink
- type FetchDisposition
- type Format
- type GetResultDataRequest
- type GetStatementResultRequest
- type QueryTag
- type ResultData
- type ResultManifest
- type Schema
- type ServiceError
- type ServiceErrorCode
- type StatementExecutionV2API
- func (a *StatementExecutionV2API) CancelStatement(ctx context.Context, request CancelStatementRequest) (*CancelStatementResponse, error)
- func (a *StatementExecutionV2API) ExecuteStatement(ctx context.Context, request ExecuteStatementRequest) (*StatementResponse, error)
- func (a *StatementExecutionV2API) GetResultData(ctx context.Context, request GetResultDataRequest) (*ResultData, error)
- func (a *StatementExecutionV2API) GetStatementResult(ctx context.Context, request GetStatementResultRequest) (*StatementResponse, error)
- type StatementExecutionV2Interface
- type StatementExecutionV2Servicedeprecated
- type StatementParameter
- type StatementResponse
- type StatementStatus
- type StatementStatusState
- type TimeoutAction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BaseChunkInfo ¶
type BaseChunkInfo struct {
// The number of bytes in the result chunk. This field is not available when
// using `INLINE` disposition.
ByteCount int64 `json:"byte_count,omitempty"`
// The position within the sequence of result set chunks.
ChunkIndex int `json:"chunk_index,omitempty"`
// The number of rows within the result chunk.
RowCount int64 `json:"row_count,omitempty"`
// The starting row offset within the result set.
RowOffset int64 `json:"row_offset,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
Metadata of one result set chunk, as listed in the result manifest.
func (BaseChunkInfo) MarshalJSON ¶
func (s BaseChunkInfo) MarshalJSON() ([]byte, error)
func (*BaseChunkInfo) UnmarshalJSON ¶
func (s *BaseChunkInfo) UnmarshalJSON(b []byte) error
type CancelStatementRequest ¶
type CancelStatementRequest struct {
// The statement ID is returned upon successfully submitting a SQL
// statement, and is a required reference for all subsequent calls.
StatementId string `json:"-" url:"-"`
// The ID of the SQL warehouse that ran the statement.
WarehouseId string `json:"-" url:"-"`
}
Request to cancel the statement given in the path on the warehouse given in the path.
func (*CancelStatementRequest) UnmarshalJSON ¶
func (s *CancelStatementRequest) UnmarshalJSON(b []byte) error
type CancelStatementResponse ¶
type CancelStatementResponse struct {
}
Empty response to a cancel request. Receiving it means the cancel request was accepted.
func (*CancelStatementResponse) UnmarshalJSON ¶
func (s *CancelStatementResponse) UnmarshalJSON(b []byte) error
type ColumnInfo ¶
type ColumnInfo struct {
// The name of the column.
Name string `json:"name,omitempty"`
// The ordinal position of the column (starting at position 0).
Position int `json:"position,omitempty"`
// The format of the interval type.
TypeIntervalType string `json:"type_interval_type,omitempty"`
// The name of the base data type. This doesn't include details for complex
// types such as STRUCT, MAP or ARRAY.
TypeName ColumnTypeName `json:"type_name,omitempty"`
// Specifies the number of digits in a number. This applies to the DECIMAL
// type.
TypePrecision int `json:"type_precision,omitempty"`
// Specifies the number of digits to the right of the decimal point in a
// number. This applies to the DECIMAL type.
TypeScale int `json:"type_scale,omitempty"`
// The full SQL type specification.
TypeText string `json:"type_text,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
Describes one column of the result set: its name, SQL type, and position.
func (ColumnInfo) MarshalJSON ¶
func (s ColumnInfo) MarshalJSON() ([]byte, error)
func (*ColumnInfo) UnmarshalJSON ¶
func (s *ColumnInfo) UnmarshalJSON(b []byte) error
type ColumnTypeName ¶
type ColumnTypeName string
The name of the base data type. This doesn't include details for complex types such as STRUCT, MAP or ARRAY.
const ColumnTypeNameArray ColumnTypeName = `ARRAY`
const ColumnTypeNameBinary ColumnTypeName = `BINARY`
const ColumnTypeNameBoolean ColumnTypeName = `BOOLEAN`
const ColumnTypeNameByte ColumnTypeName = `BYTE`
const ColumnTypeNameChar ColumnTypeName = `CHAR`
const ColumnTypeNameDate ColumnTypeName = `DATE`
const ColumnTypeNameDecimal ColumnTypeName = `DECIMAL`
const ColumnTypeNameDouble ColumnTypeName = `DOUBLE`
const ColumnTypeNameFloat ColumnTypeName = `FLOAT`
const ColumnTypeNameInt ColumnTypeName = `INT`
const ColumnTypeNameInterval ColumnTypeName = `INTERVAL`
const ColumnTypeNameLong ColumnTypeName = `LONG`
const ColumnTypeNameMap ColumnTypeName = `MAP`
const ColumnTypeNameNull ColumnTypeName = `NULL`
const ColumnTypeNameShort ColumnTypeName = `SHORT`
const ColumnTypeNameString ColumnTypeName = `STRING`
const ColumnTypeNameStruct ColumnTypeName = `STRUCT`
const ColumnTypeNameTimestamp ColumnTypeName = `TIMESTAMP`
const ColumnTypeNameUserDefinedType ColumnTypeName = `USER_DEFINED_TYPE`
func (*ColumnTypeName) Set ¶
func (f *ColumnTypeName) Set(v string) error
Set raw string value and validate it against allowed values
func (*ColumnTypeName) String ¶
func (f *ColumnTypeName) String() string
String representation for fmt.Print
func (*ColumnTypeName) Type ¶
func (f *ColumnTypeName) Type() string
Type always returns ColumnTypeName to satisfy [pflag.Value] interface
func (*ColumnTypeName) Values ¶
func (f *ColumnTypeName) Values() []ColumnTypeName
Values returns all possible values for ColumnTypeName.
There is no guarantee on the order of the values in the slice.
type ExecuteStatementRequest ¶
type ExecuteStatementRequest struct {
// Applies the given byte limit to the statement's result size. Byte counts
// are based on internal data representations and might not match the final
// size in the requested `format`. If the result was truncated due to the
// byte limit, then `truncated` in the response is set to `true`. When using
// `EXTERNAL_LINKS` disposition, a default `byte_limit` of 100 GiB is
// applied if `byte_limit` is not explicitly set.
ByteLimit int64 `json:"byte_limit,omitempty"`
// Sets default catalog for statement execution, similar to [`USE CATALOG`]
// in SQL.
//
// [`USE CATALOG`]: https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-catalog.html
Catalog string `json:"catalog,omitempty"`
// The fetch disposition provides two modes of fetching results: `INLINE`
// and `EXTERNAL_LINKS`.
//
// Statements executed with `INLINE` disposition will return result data
// inline, in `JSON_ARRAY` format, in a series of chunks. If a given
// statement produces a result set with a size larger than 25 MiB, that
// statement execution is aborted, and no result set will be available.
//
// **NOTE** Byte limits are computed based upon internal representations of
// the result set data, and might not match the sizes visible in JSON
// responses.
//
// Statements executed with `EXTERNAL_LINKS` disposition will return result
// data as external links: URLs that point to cloud storage internal to the
// workspace. Using `EXTERNAL_LINKS` disposition allows statements to
// generate arbitrarily sized result sets for fetching up to 100 GiB. The
// resulting links have two important properties:
//
// 1. They point to resources _external_ to the Databricks compute;
// therefore any associated authentication information (typically a personal
// access token, OAuth token, or similar) _must be removed_ when fetching
// from these links.
//
// 2. These are short-lived cloud-storage URLs with a specific expiration,
// indicated in the response. The behavior when attempting to use an expired
// link is cloud specific.
Disposition FetchDisposition `json:"disposition,omitempty"`
// Statement execution supports three result formats: `JSON_ARRAY`,
// `ARROW_STREAM`, and `CSV`. Set `format` explicitly: on Lakehouse//RT
// warehouses, an omitted `format` with the `INLINE` disposition currently
// returns Arrow data rather than `JSON_ARRAY`.
//
// Important: The formats `ARROW_STREAM` and `CSV` are supported only with
// `EXTERNAL_LINKS` disposition. `JSON_ARRAY` is supported in `INLINE` and
// `EXTERNAL_LINKS` disposition.
//
// When specifying `format=JSON_ARRAY`, result data will be formatted as an
// array of arrays of values, where each value is either the *string
// representation* of a value, or `null`. For example, the output of `SELECT
// concat('id-', id) AS strCol, id AS intCol, null AS nullCol FROM range(3)`
// would look like this:
//
// “` [ [ "id-1", "1", null ], [ "id-2", "2", null ], [ "id-3", "3", null
// ], ] “`
//
// When specifying `format=JSON_ARRAY` and `disposition=EXTERNAL_LINKS`,
// each chunk in the result contains compact JSON with no indentation or
// extra whitespace.
//
// When specifying `format=ARROW_STREAM` and `disposition=EXTERNAL_LINKS`,
// each chunk in the result will be formatted as Apache Arrow Stream. See
// the [Apache Arrow streaming format].
//
// When specifying `format=CSV` and `disposition=EXTERNAL_LINKS`, each chunk
// in the result will be a CSV according to [RFC 4180] standard. All column
// values will have *string representation* similar to the `JSON_ARRAY`
// format, and `null` values will be encoded as “null”. Only the first
// chunk in the result would contain a header row with column names. For
// example, the output of `SELECT concat('id-', id) AS strCol, id AS intCol,
// null as nullCol FROM range(3)` would look like this:
//
// “` strCol,intCol,nullCol id-1,1,null id-2,2,null id-3,3,null “`
//
// [Apache Arrow streaming format]: https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format
// [RFC 4180]: https://www.rfc-editor.org/rfc/rfc4180
Format Format `json:"format,omitempty"`
// When `wait_timeout > 0s`, the call will block up to the specified time.
// If the statement execution doesn't finish within this time,
// `on_wait_timeout` determines whether the execution should continue or be
// canceled. When set to `CONTINUE`, the statement execution continues
// asynchronously and the call returns a statement ID which can be used for
// polling the statement status. When set to `CANCEL`, the statement
// execution is canceled and the call returns with a `CANCELED` state.
// Lakehouse//RT warehouses currently don't support `CANCEL`: the statement
// keeps running as with `CONTINUE`.
OnWaitTimeout TimeoutAction `json:"on_wait_timeout,omitempty"`
// A list of parameters to pass into a SQL statement containing parameter
// markers. A parameter consists of a name, a value, and optionally a type.
// To represent a NULL value, the `value` field may be omitted or set to
// `null` explicitly. If the `type` field is omitted, the value is
// interpreted as a string.
//
// If the type is given, parameters will be checked for type correctness
// according to the given type. A value is correct if the provided string
// can be converted to the requested type using the `cast` function. The
// exact semantics are described in the section [`cast` function] of the SQL
// language reference.
//
// For example, the following statement contains two parameters, `my_name`
// and `my_date`:
//
// “` SELECT * FROM my_table WHERE name = :my_name AND date = :my_date “`
//
// The parameters can be passed in the request body as follows:
//
// ` { ..., "statement": "SELECT * FROM my_table WHERE name = :my_name AND
// date = :my_date", "parameters": [ { "name": "my_name", "value": "the
// name" }, { "name": "my_date", "value": "2020-01-01", "type": "DATE" } ] }
// `
//
// Currently, positional parameters denoted by a `?` marker are not
// supported by the Databricks SQL Statement Execution API.
//
// Also see the section [Parameter markers] of the SQL language reference.
//
// [Parameter markers]: https://docs.databricks.com/sql/language-manual/sql-ref-parameter-marker.html
// [`cast` function]: https://docs.databricks.com/sql/language-manual/functions/cast.html
Parameters []StatementParameter `json:"parameters,omitempty"`
// An array of query tags to annotate a SQL statement. A query tag consists
// of a non-empty key and, optionally, a value. To represent a NULL value,
// either omit the `value` field or manually set it to `null` or white
// space. Refer to the SQL language reference for the format specification
// of query tags. There's no significance to the order of tags. Only one
// value per key will be recorded. A sequence in excess of 20 query tags
// will be coerced to 20. Example:
//
// { ..., "query_tags": [ { "key": "team", "value": "eng" }, { "key": "some
// key only tag" } ] }
QueryTags []QueryTag `json:"query_tags,omitempty"`
// Applies the given row limit to the statement's result set, but unlike the
// `LIMIT` clause in SQL, it also sets the `truncated` field in the response
// to indicate whether the result was trimmed due to the limit or not.
RowLimit int64 `json:"row_limit,omitempty"`
// Sets default schema for statement execution, similar to [`USE SCHEMA`] in
// SQL.
//
// [`USE SCHEMA`]: https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-schema.html
Schema string `json:"schema,omitempty"`
// The SQL statement to execute. The statement can optionally be
// parameterized, see `parameters`. The maximum query text size is 16 MiB.
Statement string `json:"statement"`
// The time in seconds the call will wait for the statement's result set as
// `Ns`, where `N` can be set to 0 or to a value between 5 and 50.
//
// When set to `0s`, the statement will execute in asynchronous mode and the
// call will not wait for the execution to finish. In this case, the call
// returns directly with `PENDING` state and a statement ID which can be
// used for polling the statement status.
//
// When set between 5 and 50 seconds, the call will behave synchronously up
// to this timeout and wait for the statement execution to finish. If the
// execution finishes within this time, the call returns immediately with a
// manifest and result data (or a `FAILED` state in case of an execution
// error). If the statement takes longer to execute, `on_wait_timeout`
// determines what should happen after the timeout is reached.
WaitTimeout string `json:"wait_timeout,omitempty"`
// The ID of the SQL warehouse to run the statement on. Currently, only
// [Lakehouse//RT] warehouses are supported. See also [What are SQL
// warehouses?].
//
// [Lakehouse//RT]: https://docs.databricks.com/compute/sql-warehouse/real-time.html
// [What are SQL warehouses?]: https://docs.databricks.com/sql/admin/warehouse-type.html
WarehouseId string `json:"-" url:"-"`
ForceSendFields []string `json:"-" url:"-"`
}
Request to execute a SQL statement on the warehouse given in the path.
func (ExecuteStatementRequest) MarshalJSON ¶
func (s ExecuteStatementRequest) MarshalJSON() ([]byte, error)
func (*ExecuteStatementRequest) UnmarshalJSON ¶
func (s *ExecuteStatementRequest) UnmarshalJSON(b []byte) error
type ExternalLink ¶
type ExternalLink struct {
// The number of bytes in the result chunk. This field is not available when
// using `INLINE` disposition.
ByteCount int64 `json:"byte_count,omitempty"`
// The position within the sequence of result set chunks.
ChunkIndex int `json:"chunk_index,omitempty"`
// Indicates the date-time that the given external link will expire and
// become invalid, after which point a new `external_link` must be
// requested.
Expiration string `json:"expiration,omitempty"`
// A short-lived cloud-storage URL pointing to a chunk of result data,
// hosted by an external service, with a short expiration time (<= 15
// minutes). As this URL contains a temporary credential, it should be
// considered sensitive and the client should not expose this URL in a log.
ExternalLink string `json:"external_link,omitempty"`
// HTTP headers that must be included with a GET request to the
// `external_link`. Each header is provided as a key-value pair. Headers are
// typically used to pass a decryption key to the external service. The
// values of these headers should be considered sensitive and the client
// should not expose these values in a log.
HttpHeaders map[string]string `json:"http_headers,omitempty"`
// When fetching, provides the `chunk_index` for the _next_ chunk. If
// absent, indicates there are no more chunks. The next chunk can be fetched
// with a get-result-chunk request for that index.
NextChunkIndex int `json:"next_chunk_index,omitempty"`
// When fetching, provides a link to fetch the _next_ chunk. If absent,
// indicates there are no more chunks. This link is an absolute `path` to be
// joined with your `$DATABRICKS_HOST`, and should be treated as an opaque
// link. This is an alternative to using `next_chunk_index`. Lakehouse//RT
// warehouses currently don't return this field; use `next_chunk_index`
// instead.
NextChunkInternalLink string `json:"next_chunk_internal_link,omitempty"`
// The number of rows within the result chunk.
RowCount int64 `json:"row_count,omitempty"`
// The starting row offset within the result set.
RowOffset int64 `json:"row_offset,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
A short-lived cloud-storage link to one chunk of result data.
func (ExternalLink) MarshalJSON ¶
func (s ExternalLink) MarshalJSON() ([]byte, error)
func (*ExternalLink) UnmarshalJSON ¶
func (s *ExternalLink) UnmarshalJSON(b []byte) error
type FetchDisposition ¶
type FetchDisposition string
const FetchDispositionExternalLinks FetchDisposition = `EXTERNAL_LINKS`
const FetchDispositionInline FetchDisposition = `INLINE`
func (*FetchDisposition) Set ¶
func (f *FetchDisposition) Set(v string) error
Set raw string value and validate it against allowed values
func (*FetchDisposition) String ¶
func (f *FetchDisposition) String() string
String representation for fmt.Print
func (*FetchDisposition) Type ¶
func (f *FetchDisposition) Type() string
Type always returns FetchDisposition to satisfy [pflag.Value] interface
func (*FetchDisposition) Values ¶
func (f *FetchDisposition) Values() []FetchDisposition
Values returns all possible values for FetchDisposition.
There is no guarantee on the order of the values in the slice.
type Format ¶
type Format string
The format of the result data.
const FormatArrowStream Format = `ARROW_STREAM`
const FormatCsv Format = `CSV`
const FormatJsonArray Format = `JSON_ARRAY`
type GetResultDataRequest ¶
type GetResultDataRequest struct {
// The zero-based index of the result chunk to fetch.
ChunkIndex int `json:"-" url:"-"`
// The statement ID is returned upon successfully submitting a SQL
// statement, and is a required reference for all subsequent calls.
StatementId string `json:"-" url:"-"`
// The ID of the SQL warehouse that ran the statement.
WarehouseId string `json:"-" url:"-"`
}
func (*GetResultDataRequest) UnmarshalJSON ¶
func (s *GetResultDataRequest) UnmarshalJSON(b []byte) error
type GetStatementResultRequest ¶
type GetStatementResultRequest struct {
// The statement ID is returned upon successfully submitting a SQL
// statement, and is a required reference for all subsequent calls.
StatementId string `json:"-" url:"-"`
// The ID of the SQL warehouse that ran the statement.
WarehouseId string `json:"-" url:"-"`
}
func (*GetStatementResultRequest) UnmarshalJSON ¶
func (s *GetStatementResultRequest) UnmarshalJSON(b []byte) error
type QueryTag ¶
type QueryTag struct {
Key string `json:"key"`
Value string `json:"value,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
* A query execution can be annotated with an optional key-value pair to allow users to attribute the executions by key and optional value to filter by. QueryTag is the user-facing representation.
func (QueryTag) MarshalJSON ¶
func (*QueryTag) UnmarshalJSON ¶
type ResultData ¶
type ResultData struct {
// The number of bytes in the result chunk. This field is not available when
// using `INLINE` disposition.
ByteCount int64 `json:"byte_count,omitempty"`
// The position within the sequence of result set chunks.
ChunkIndex int `json:"chunk_index,omitempty"`
// The `JSON_ARRAY` format is an array of arrays of values, where each
// non-null value is formatted as a string. Null values are encoded as JSON
// `null`.
DataArray [][]json.RawMessage `json:"data_array,omitempty"`
// Short-lived cloud-storage links to the result data, used with the
// `EXTERNAL_LINKS` disposition.
ExternalLinks []ExternalLink `json:"external_links,omitempty"`
// When fetching, provides the `chunk_index` for the _next_ chunk. If
// absent, indicates there are no more chunks. The next chunk can be fetched
// with a get-result-chunk request for that index.
NextChunkIndex int `json:"next_chunk_index,omitempty"`
// When fetching, provides a link to fetch the _next_ chunk. If absent,
// indicates there are no more chunks. This link is an absolute `path` to be
// joined with your `$DATABRICKS_HOST`, and should be treated as an opaque
// link. This is an alternative to using `next_chunk_index`. Lakehouse//RT
// warehouses currently don't return this field; use `next_chunk_index`
// instead.
NextChunkInternalLink string `json:"next_chunk_internal_link,omitempty"`
// The number of rows within the result chunk.
RowCount int64 `json:"row_count,omitempty"`
// The starting row offset within the result set.
RowOffset int64 `json:"row_offset,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
Contains the result data of a single chunk when using `INLINE` disposition. When using `EXTERNAL_LINKS` disposition, the array `external_links` is used instead to provide short-lived cloud-storage URLs to the result data in cloud storage. Exactly one of these alternatives is used. (While the `external_links` array prepares the API to return multiple links in a single response, currently only a single link is returned.)
func (ResultData) MarshalJSON ¶
func (s ResultData) MarshalJSON() ([]byte, error)
func (*ResultData) UnmarshalJSON ¶
func (s *ResultData) UnmarshalJSON(b []byte) error
type ResultManifest ¶
type ResultManifest struct {
// Array of result set chunk metadata.
Chunks []BaseChunkInfo `json:"chunks,omitempty"`
// The format of the result data, as requested with `format`.
Format Format `json:"format,omitempty"`
// The schema of the result set: the ordered list of column descriptions.
Schema *Schema `json:"schema,omitempty"`
// The total number of bytes in the result set. This field is not available
// when using `INLINE` disposition.
TotalByteCount int64 `json:"total_byte_count,omitempty"`
// The total number of chunks that the result set has been divided into.
TotalChunkCount int `json:"total_chunk_count,omitempty"`
// The total number of rows in the result set.
TotalRowCount int64 `json:"total_row_count,omitempty"`
// Indicates whether the result is truncated due to `row_limit` or
// `byte_limit`.
Truncated bool `json:"truncated,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
The result manifest provides schema and metadata for the result set.
func (ResultManifest) MarshalJSON ¶
func (s ResultManifest) MarshalJSON() ([]byte, error)
func (*ResultManifest) UnmarshalJSON ¶
func (s *ResultManifest) UnmarshalJSON(b []byte) error
type Schema ¶
type Schema struct {
// The number of columns in the result set.
ColumnCount int `json:"column_count,omitempty"`
// The column descriptions, in result set order.
Columns []ColumnInfo `json:"columns,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
The schema is an ordered list of column descriptions.
func (Schema) MarshalJSON ¶
func (*Schema) UnmarshalJSON ¶
type ServiceError ¶
type ServiceError struct {
// The error code that classifies the failure.
ErrorCode ServiceErrorCode `json:"error_code,omitempty"`
// A brief summary of the error condition.
Message string `json:"message,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
The error that caused a statement execution to fail.
func (ServiceError) MarshalJSON ¶
func (s ServiceError) MarshalJSON() ([]byte, error)
func (*ServiceError) UnmarshalJSON ¶
func (s *ServiceError) UnmarshalJSON(b []byte) error
type ServiceErrorCode ¶
type ServiceErrorCode string
Error codes that classify a failed statement execution.
const ServiceErrorCodeAborted ServiceErrorCode = `ABORTED`
const ServiceErrorCodeAlreadyExists ServiceErrorCode = `ALREADY_EXISTS`
const ServiceErrorCodeBadRequest ServiceErrorCode = `BAD_REQUEST`
const ServiceErrorCodeCancelled ServiceErrorCode = `CANCELLED`
const ServiceErrorCodeDeadlineExceeded ServiceErrorCode = `DEADLINE_EXCEEDED`
const ServiceErrorCodeInternalError ServiceErrorCode = `INTERNAL_ERROR`
const ServiceErrorCodeIoError ServiceErrorCode = `IO_ERROR`
const ServiceErrorCodeNotFound ServiceErrorCode = `NOT_FOUND`
const ServiceErrorCodeResourceExhausted ServiceErrorCode = `RESOURCE_EXHAUSTED`
const ServiceErrorCodeServiceUnderMaintenance ServiceErrorCode = `SERVICE_UNDER_MAINTENANCE`
const ServiceErrorCodeUnauthenticated ServiceErrorCode = `UNAUTHENTICATED`
const ServiceErrorCodeUnknown ServiceErrorCode = `UNKNOWN`
func (*ServiceErrorCode) Set ¶
func (f *ServiceErrorCode) Set(v string) error
Set raw string value and validate it against allowed values
func (*ServiceErrorCode) String ¶
func (f *ServiceErrorCode) String() string
String representation for fmt.Print
func (*ServiceErrorCode) Type ¶
func (f *ServiceErrorCode) Type() string
Type always returns ServiceErrorCode to satisfy [pflag.Value] interface
func (*ServiceErrorCode) Values ¶
func (f *ServiceErrorCode) Values() []ServiceErrorCode
Values returns all possible values for ServiceErrorCode.
There is no guarantee on the order of the values in the slice.
type StatementExecutionV2API ¶
type StatementExecutionV2API struct {
// contains filtered or unexported fields
}
The Statement Execution API v2 can be used to execute SQL statements on a SQL warehouse and fetch the result. It works the same as the Statement Execution API (v1), except that `warehouse_id` is a path parameter on every call, including polling, fetching result chunks, and canceling. Routing on the warehouse ID gives lower latency and higher concurrency.
Version 2 currently supports Lakehouse//RT warehouses only. For other warehouse types, use the Statement Execution API (v1). You can also run statements on Lakehouse//RT warehouses with version 1, but version 2 is optimized for them.
func NewStatementExecutionV2 ¶
func NewStatementExecutionV2(client *client.DatabricksClient) *StatementExecutionV2API
func (*StatementExecutionV2API) CancelStatement ¶
func (a *StatementExecutionV2API) CancelStatement(ctx context.Context, request CancelStatementRequest) (*CancelStatementResponse, error)
func (*StatementExecutionV2API) ExecuteStatement ¶
func (a *StatementExecutionV2API) ExecuteStatement(ctx context.Context, request ExecuteStatementRequest) (*StatementResponse, error)
func (*StatementExecutionV2API) GetResultData ¶
func (a *StatementExecutionV2API) GetResultData(ctx context.Context, request GetResultDataRequest) (*ResultData, error)
func (*StatementExecutionV2API) GetStatementResult ¶
func (a *StatementExecutionV2API) GetStatementResult(ctx context.Context, request GetStatementResultRequest) (*StatementResponse, error)
type StatementExecutionV2Interface ¶
type StatementExecutionV2Interface interface {
// Requests that an executing statement be canceled. Callers must poll for
// status to see the terminal state. The cancel response is empty; receiving a
// response indicates successful receipt.
CancelStatement(ctx context.Context, request CancelStatementRequest) (*CancelStatementResponse, error)
// Execute a SQL statement and optionally await its results for a specified
// time.
//
// **Use case: small result sets with INLINE + JSON_ARRAY**
//
// For flows that generate small and predictable result sets (<= 25 MiB),
// `INLINE` responses of `JSON_ARRAY` result data are typically the simplest way
// to execute and fetch result data.
//
// **Use case: large result sets with EXTERNAL_LINKS**
//
// Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result
// sets efficiently. The main differences from using `INLINE` disposition are
// that the result data is accessed with short-lived cloud-storage URLs, and
// that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV`
// compared to only `JSON_ARRAY` with `INLINE`.
//
// **External-link URLs**
//
// External links point to data stored within your workspace's internal cloud
// storage. The URLs are valid for only a short period, <= 15 minutes. Alongside
// each `external_link` is an expiration field indicating the time at which the
// URL is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and
// fetched multiple times and in parallel.
//
// ----
//
// ### **Warning: Databricks strongly recommends that you protect the URLs that
// are returned by the `EXTERNAL_LINKS` disposition.**
//
// When you use the `EXTERNAL_LINKS` disposition, a short-lived cloud-storage
// URL is generated to download the results. The URL contains temporary access
// credentials, so protect it and do not set an `Authorization` header in the
// download request.
//
// The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a
// [support case].
//
// See also [Security best practices].
//
// ----
//
// StatementResponse contains `statement_id` and `status`; other fields might be
// absent or present depending on context. If the SQL warehouse fails to execute
// the provided statement, a 200 response is returned with `status.state` set to
// `FAILED` (in contrast to a failure when accepting the request, which results
// in a non-200 response). Details of the error can be found at `status.error`
// in case of execution failures.
//
// [Security best practices]: https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices
// [support case]: https://docs.databricks.com/resources/support.html
ExecuteStatement(ctx context.Context, request ExecuteStatementRequest) (*StatementResponse, error)
// After the statement execution has `SUCCEEDED`, this request can be used to
// fetch any chunk by index. Whereas the first chunk with `chunk_index=0` is
// typically fetched with the execute or the get-status request, this request
// can be used to fetch subsequent chunks. The response structure is identical
// to the nested `result` element of those responses, and similarly includes the
// `next_chunk_index` field for simple iteration through the result set.
// Depending on `disposition`, the response returns chunks of data either
// inline, or as links.
GetResultData(ctx context.Context, request GetResultDataRequest) (*ResultData, error)
// This request can be used to poll for the statement's status.
// StatementResponse contains `statement_id` and `status`; other fields might be
// absent or present depending on context. When the `status.state` field is
// `SUCCEEDED` it will also return the result manifest and the first chunk of
// the result data. When the statement is in the terminal states `CANCELED`,
// `CLOSED` or `FAILED`, it returns HTTP 200 with the state set. After at least
// 12 hours in a terminal state, the statement is removed from the warehouse and
// further calls will receive an HTTP 404 response.
//
// **NOTE** This call currently might take up to 5 seconds to get the latest
// status and result.
GetStatementResult(ctx context.Context, request GetStatementResultRequest) (*StatementResponse, error)
}
type StatementExecutionV2Service
deprecated
type StatementExecutionV2Service interface {
// Requests that an executing statement be canceled. Callers must poll for
// status to see the terminal state. The cancel response is empty; receiving
// a response indicates successful receipt.
CancelStatement(ctx context.Context, request CancelStatementRequest) (*CancelStatementResponse, error)
// Execute a SQL statement and optionally await its results for a specified
// time.
//
// **Use case: small result sets with INLINE + JSON_ARRAY**
//
// For flows that generate small and predictable result sets (<= 25 MiB),
// `INLINE` responses of `JSON_ARRAY` result data are typically the simplest
// way to execute and fetch result data.
//
// **Use case: large result sets with EXTERNAL_LINKS**
//
// Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large
// result sets efficiently. The main differences from using `INLINE`
// disposition are that the result data is accessed with short-lived
// cloud-storage URLs, and that there are 3 supported formats: `JSON_ARRAY`,
// `ARROW_STREAM` and `CSV` compared to only `JSON_ARRAY` with `INLINE`.
//
// **External-link URLs**
//
// External links point to data stored within your workspace's internal
// cloud storage. The URLs are valid for only a short period, <= 15 minutes.
// Alongside each `external_link` is an expiration field indicating the time
// at which the URL is no longer valid. In `EXTERNAL_LINKS` mode, chunks can
// be resolved and fetched multiple times and in parallel.
//
// ----
//
// ### **Warning: Databricks strongly recommends that you protect the URLs
// that are returned by the `EXTERNAL_LINKS` disposition.**
//
// When you use the `EXTERNAL_LINKS` disposition, a short-lived
// cloud-storage URL is generated to download the results. The URL contains
// temporary access credentials, so protect it and do not set an
// `Authorization` header in the download request.
//
// The `EXTERNAL_LINKS` disposition can be disabled upon request by creating
// a [support case].
//
// See also [Security best practices].
//
// ----
//
// StatementResponse contains `statement_id` and `status`; other fields
// might be absent or present depending on context. If the SQL warehouse
// fails to execute the provided statement, a 200 response is returned with
// `status.state` set to `FAILED` (in contrast to a failure when accepting
// the request, which results in a non-200 response). Details of the error
// can be found at `status.error` in case of execution failures.
//
// [Security best practices]: https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices
// [support case]: https://docs.databricks.com/resources/support.html
ExecuteStatement(ctx context.Context, request ExecuteStatementRequest) (*StatementResponse, error)
// After the statement execution has `SUCCEEDED`, this request can be used
// to fetch any chunk by index. Whereas the first chunk with `chunk_index=0`
// is typically fetched with the execute or the get-status request, this
// request can be used to fetch subsequent chunks. The response structure is
// identical to the nested `result` element of those responses, and
// similarly includes the `next_chunk_index` field for simple iteration
// through the result set. Depending on `disposition`, the response returns
// chunks of data either inline, or as links.
GetResultData(ctx context.Context, request GetResultDataRequest) (*ResultData, error)
// This request can be used to poll for the statement's status.
// StatementResponse contains `statement_id` and `status`; other fields
// might be absent or present depending on context. When the `status.state`
// field is `SUCCEEDED` it will also return the result manifest and the
// first chunk of the result data. When the statement is in the terminal
// states `CANCELED`, `CLOSED` or `FAILED`, it returns HTTP 200 with the
// state set. After at least 12 hours in a terminal state, the statement is
// removed from the warehouse and further calls will receive an HTTP 404
// response.
//
// **NOTE** This call currently might take up to 5 seconds to get the latest
// status and result.
GetStatementResult(ctx context.Context, request GetStatementResultRequest) (*StatementResponse, error)
}
The Statement Execution API v2 can be used to execute SQL statements on a SQL warehouse and fetch the result. It works the same as the Statement Execution API (v1), except that `warehouse_id` is a path parameter on every call, including polling, fetching result chunks, and canceling. Routing on the warehouse ID gives lower latency and higher concurrency.
Version 2 currently supports Lakehouse//RT warehouses only. For other warehouse types, use the Statement Execution API (v1). You can also run statements on Lakehouse//RT warehouses with version 1, but version 2 is optimized for them.
Deprecated: Do not use this interface, it will be removed in a future version of the SDK.
type StatementParameter ¶
type StatementParameter struct {
// The name of a parameter marker to be substituted in the statement.
Name string `json:"name"`
// The data type, given as a string. For example: `INT`, `STRING`,
// `DECIMAL(10,2)`. If no type is given the type is assumed to be `STRING`.
// Complex types, such as `ARRAY`, `MAP`, and `STRUCT` are not supported.
// For valid types, refer to the section [Data types] of the SQL language
// reference.
//
// [Data types]: https://docs.databricks.com/sql/language-manual/functions/cast.html
Type string `json:"type,omitempty"`
// The value to substitute, represented as a string. If omitted, the value
// is interpreted as NULL.
Value string `json:"value,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
A named parameter to substitute for a parameter marker in the statement.
func (StatementParameter) MarshalJSON ¶
func (s StatementParameter) MarshalJSON() ([]byte, error)
func (*StatementParameter) UnmarshalJSON ¶
func (s *StatementParameter) UnmarshalJSON(b []byte) error
type StatementResponse ¶
type StatementResponse struct {
// The schema and metadata of the result set. Present when `status.state` is
// `SUCCEEDED`.
Manifest *ResultManifest `json:"manifest,omitempty"`
// The first chunk of result data. Present when `status.state` is
// `SUCCEEDED`.
Result *ResultData `json:"result,omitempty"`
// The statement ID is returned upon successfully submitting a SQL
// statement, and is a required reference for all subsequent calls.
StatementId string `json:"statement_id,omitempty"`
// The execution state of the statement and, if it failed, the error
// details.
Status *StatementStatus `json:"status,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
Statement Execution (Lakehouse//RT) is version 2 of the Statement Execution API. It is optimized for Lakehouse//RT warehouses, with lower latency and higher concurrency, and takes `warehouse_id` as a path parameter on every call. It currently supports Lakehouse//RT warehouses only. The Statement Execution API (version 1) works with all SQL warehouse types, including Lakehouse//RT.
func (StatementResponse) MarshalJSON ¶
func (s StatementResponse) MarshalJSON() ([]byte, error)
func (*StatementResponse) UnmarshalJSON ¶
func (s *StatementResponse) UnmarshalJSON(b []byte) error
type StatementStatus ¶
type StatementStatus struct {
// The error details. Only populated when `state` is `FAILED`.
Error *ServiceError `json:"error,omitempty"`
// SQLSTATE error code returned when the statement execution fails. Only
// populated when the statement status is `FAILED`.
SqlState string `json:"sql_state,omitempty"`
// Statement execution state: - `PENDING`: waiting for warehouse -
// `RUNNING`: running - `SUCCEEDED`: execution was successful, result data
// available for fetch - `FAILED`: execution failed; reason for failure
// described in accompanying error message - `CANCELED`: user canceled; can
// come from explicit cancel call, or timeout with `on_wait_timeout=CANCEL`
// - `CLOSED`: execution successful, and statement closed; result no longer
// available for fetch
State StatementStatusState `json:"state,omitempty"`
ForceSendFields []string `json:"-" url:"-"`
}
The status response includes execution state and if relevant, error information.
func (StatementStatus) MarshalJSON ¶
func (s StatementStatus) MarshalJSON() ([]byte, error)
func (*StatementStatus) UnmarshalJSON ¶
func (s *StatementStatus) UnmarshalJSON(b []byte) error
type StatementStatusState ¶
type StatementStatusState string
Statement execution state.
const StatementStatusStateCanceled StatementStatusState = `CANCELED`
const StatementStatusStateClosed StatementStatusState = `CLOSED`
const StatementStatusStateFailed StatementStatusState = `FAILED`
const StatementStatusStatePending StatementStatusState = `PENDING`
const StatementStatusStateRunning StatementStatusState = `RUNNING`
const StatementStatusStateSucceeded StatementStatusState = `SUCCEEDED`
func (*StatementStatusState) Set ¶
func (f *StatementStatusState) Set(v string) error
Set raw string value and validate it against allowed values
func (*StatementStatusState) String ¶
func (f *StatementStatusState) String() string
String representation for fmt.Print
func (*StatementStatusState) Type ¶
func (f *StatementStatusState) Type() string
Type always returns StatementStatusState to satisfy [pflag.Value] interface
func (*StatementStatusState) Values ¶
func (f *StatementStatusState) Values() []StatementStatusState
Values returns all possible values for StatementStatusState.
There is no guarantee on the order of the values in the slice.
type TimeoutAction ¶
type TimeoutAction string
What happens when the statement execution outlives `wait_timeout`.
const TimeoutActionCancel TimeoutAction = `CANCEL`
const TimeoutActionContinue TimeoutAction = `CONTINUE`
func (*TimeoutAction) Set ¶
func (f *TimeoutAction) Set(v string) error
Set raw string value and validate it against allowed values
func (*TimeoutAction) String ¶
func (f *TimeoutAction) String() string
String representation for fmt.Print
func (*TimeoutAction) Type ¶
func (f *TimeoutAction) Type() string
Type always returns TimeoutAction to satisfy [pflag.Value] interface
func (*TimeoutAction) Values ¶
func (f *TimeoutAction) Values() []TimeoutAction
Values returns all possible values for TimeoutAction.
There is no guarantee on the order of the values in the slice.