query_history

Creates, updates, deletes, gets or lists a query_history resource.

Overview

Name	query_history
Type	Resource
Id	databricks_workspace.sql.query_history

Fields

The following fields are returned by SELECT queries:

list

Name	Datatype	Description
cache_query_id	string
endpoint_id	string	Alias for ``warehouse_id``.
executed_as_user_id	integer	The ID of the user whose credentials were used to run the query.
query_id	string	The query ID.
session_id	string	The spark session UUID that query ran on. This is either the Spark Connect, DBSQL, or SDP session ID.
user_id	integer	The ID of the user who ran the query.
warehouse_id	string	Warehouse ID.
executed_as_user_name	string	The email address or username of the user whose credentials were used to run the query.
user_name	string	The email address or username of the user who ran the query.
▶channel_used	object	SQL Warehouse channel information at the time of query execution
client_application	string	Client application that ran the statement. For example: Databricks SQL Editor, Tableau, and Power BI. This field is derived from information provided by client applications. While values are expected to remain static over time, this cannot be guaranteed.
duration	integer	Total time of the statement execution. This value does not include the time taken to retrieve the results, which can result in a discrepancy between this value and the start-to-finish wall-clock time.
error_message	string	Message describing why the query could not complete.
execution_end_time_ms	integer	The time execution of the query ended.
is_final	boolean	Whether more updates for the query are expected.
lookup_key	string	A key that can be used to look up query details.
▶metrics	object	Metrics about query execution.
plans_state	string	Whether plans exist for the execution, or the reason why they are missing (EMPTY, EXISTS, IGNORED_LARGE_PLANS_SIZE, IGNORED_SMALL_DURATION, IGNORED_SPARK_PLAN_TYPE, UNKNOWN)
query_end_time_ms	integer	The time the query ended.
▶query_source	object	A struct that contains key-value pairs representing Databricks entities that were involved in the execution of this statement, such as jobs, notebooks, or dashboards. This field only records Databricks entities.
query_start_time_ms	integer	The time the query started.
▶query_tags	array	A query execution can be optionally annotated with query tags
query_text	string	The text of the query.
rows_produced	integer	The number of results returned by the query.
spark_ui_url	string	URL to the Spark UI query plan.
statement_type	string	Type of statement for this query (ALTER, ANALYZE, CALL, COPY, CREATE, DELETE, DESCRIBE, DROP, EXPLAIN, GRANT, INSERT, MERGE, OPTIMIZE, OTHER, REFRESH, REPLACE, REVOKE, SELECT, SET, SHOW, TRUNCATE, UPDATE, USE)
status	string	Statuses which are also used by OperationStatus in runtime. When adding a new QueryStatus, make<br />sure to update com.databricks.sqlgateway.history.QueryStatusOrdering (CANCELED, COMPILED, COMPILING, FAILED, FINISHED, QUEUED, RUNNING, STARTED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	deployment_name	filter_by, include_metrics, max_results, page_token	List the history of queries through SQL warehouses, and serverless compute.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
filter_by	object	An optional filter object to limit query history results. Accepts parameters such as user IDs, endpoint IDs, and statuses to narrow the returned data. In a URL, the parameters of this filter are specified with dot notation. For example: filter_by.statement_ids.
include_metrics	boolean	Whether to include the query metrics with each query. Only use this for a small subset of queries (max_results). Defaults to false.
max_results	integer	Limit the number of results returned in one page. Must be less than 1000 and the default is 100.
page_token	string	A token that can be used to get the next page of results. The token can contains characters that need to be encoded before using it in a URL. For example, the character '+' needs to be replaced by %2B. This field is optional.

SELECT examples

list

List the history of queries through SQL warehouses, and serverless compute.

SELECT
cache_query_id,
endpoint_id,
executed_as_user_id,
query_id,
session_id,
user_id,
warehouse_id,
executed_as_user_name,
user_name,
channel_used,
client_application,
duration,
error_message,
execution_end_time_ms,
is_final,
lookup_key,
metrics,
plans_state,
query_end_time_ms,
query_source,
query_start_time_ms,
query_tags,
query_text,
rows_produced,
spark_ui_url,
statement_type,
status
FROM databricks_workspace.sql.query_history
WHERE deployment_name = '{{ deployment_name }}' -- required
AND filter_by = '{{ filter_by }}'
AND include_metrics = '{{ include_metrics }}'
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;