Execute SQL Query
Usage
db_sql_exec_query(
statement,
warehouse_id,
catalog = NULL,
schema = NULL,
parameters = NULL,
row_limit = NULL,
byte_limit = NULL,
disposition = c("INLINE", "EXTERNAL_LINKS"),
format = c("JSON_ARRAY", "ARROW_STREAM", "CSV"),
wait_timeout = "10s",
on_wait_timeout = c("CONTINUE", "CANCEL"),
host = db_host(),
token = db_token(),
perform_request = TRUE
)
Arguments
- statement
String, the SQL statement to execute. The statement can optionally be parameterized, see
parameters
.- warehouse_id
String, ID of warehouse upon which to execute a statement.
- catalog
String, sets default catalog for statement execution, similar to
USE CATALOG
in SQL.- schema
String, sets default schema for statement execution, similar to
USE SCHEMA
in SQL.- parameters
List of Named Lists, 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 toNULL
explicitly.See docs for more details.
- row_limit
Integer, applies the given row limit to the statement's result set, but unlike the
LIMIT
clause in SQL, it also sets thetruncated
field in the response to indicate whether the result was trimmed due to the limit or not.- byte_limit
Integer, 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 usingEXTERNAL_LINKS
disposition, a default byte_limit of 100 GiB is applied ifbyte_limit
is not explicitly set.- disposition
One of
"INLINE"
(default) or"EXTERNAL_LINKS"
. See docs for details.- format
One of
"JSON_ARRAY"
(default),"ARROW_STREAM"
, or"CSV"
. See docs for details.- wait_timeout
String, default is
"10s"
. The time in seconds the call will wait for the statement's result set asNs
, whereN
can be set to0
or to a value between5
and50
. When set to0s
, 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 withPENDING
state and a statement ID which can be used for polling withdb_sql_exec_status()
.When set between
5
and50
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 aFAILED
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.- on_wait_timeout
One of
"CONTINUE"
(default) or"CANCEL"
. Whenwait_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 withdb_sql_exec_status()
.When set to
CANCEL
, the statement execution is canceled and the call returns with aCANCELED
state.- host
Databricks workspace URL, defaults to calling
db_host()
.- token
Databricks workspace token, defaults to calling
db_token()
.- perform_request
If
TRUE
(default) the request is performed, ifFALSE
the httr2 request is returned without being performed.
Details
Refer to the web documentation for detailed material on interaction of the various parameters and general recommendations
See also
Other SQL Execution APIs:
db_sql_exec_cancel()
,
db_sql_exec_result()
,
db_sql_exec_status()