Query
A saved Databricks SQL query. A query stores the SQL text, the SQL warehouse it runs on, its parameters, and metadata such as the display name, description, owner, and tags.
Query object
A saved Databricks SQL query. A query stores the SQL text, the SQL warehouse it runs on, its parameters, and metadata such as the display name, description, owner, and tags.
- idstringIDImmutable
UUID identifying the query.
- display_namestring
Display name of the query that appears in list views, widget headings, and on the query page.
- descriptionstring
General description that conveys additional information about this query such as usage notes.
- owner_user_namestring
Username of the user that owns the query.
- warehouse_idstring
ID of the SQL warehouse attached to the query.
- query_textstring
Text of the query to be run.
- run_as_modestring
Whose credentials the query runs with when it is shared.
VIEWERuses the credentials of the user running the query.OWNERuses the owner's credentials where the product supports that, such as for legacy alerts and jobs. When omitted on create, the workspace default applies. A workspace admin can disallowOWNER.OWNERVIEWER
- lifecycle_statestring
Indicates whether the query is trashed.
ACTIVETRASHED
- last_modifier_user_namestring
Username of the user who last saved changes to this query.
- parent_pathstring
Workspace path of the workspace folder containing the object.
- tagsarray of string
Tags attached to the query. Tags appear in the query list and can be used to filter it.
- create_timestring
Timestamp when this query was created.
- update_timestring
Timestamp when this query was last updated.
- parametersarray of object
List of query parameter definitions.
Show child attributesHide child attributes
- titlestring
Text displayed in the user-facing parameter widget in the UI.
- namestring
Literal parameter marker that appears between double curly braces in the query text.
- text_valueobject
Text query parameter value.
Show child attributesHide child attributes
- valuestring
Text substituted for the parameter marker when the query runs. Quotation marks are added around the value automatically.
- numeric_valueobject
Numeric query parameter value.
Show child attributesHide child attributes
- valuedouble
Number substituted for the parameter marker when the query runs.
- enum_valueobject
Dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- enum_optionsstring
List of valid query parameter values, newline delimited.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- date_valueobject
Date query parameter value. Can only specify one of
dynamic_date_valueordate_value.Show child attributesHide child attributes
- dynamic_date_valuestring
Dynamic date-time value based on current date-time.
NOWYESTERDAY
- date_valuestring
Manually specified date-time value in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- date_range_valueobject
Date-range query parameter value. Can only specify one of
dynamic_date_range_valueordate_range_value.Show child attributesHide child attributes
- dynamic_date_range_valuestring
Dynamic date-time range value based on current date-time.
Show 17 possible values
TODAYYESTERDAYTHIS_WEEKTHIS_MONTHTHIS_YEARLAST_WEEKLAST_MONTHLAST_YEARLAST_HOURLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_60_DAYSLAST_90_DAYSLAST_12_MONTHS
- date_range_valueobject
Manually specified date-time range value.
Show child attributesHide child attributes
- startstring
Start of the range in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- endstring
End of the range, in the same format as
start.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- start_day_of_weekint32
Day the week starts on for week-based dynamic ranges such as
THIS_WEEKandLAST_WEEK, from 0 (Sunday) to 6 (Saturday). Defaults to 0.
- query_backed_valueobject
Query-based dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- query_idstring
UUID of the query that provides the parameter values.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- apply_auto_limitboolean
Whether to apply a 1000 row limit to the query result.
- catalogstring
Name of the catalog where this query will be executed.
- schemastring
Name of the schema where this query will be executed.
Get a query GA
GET
Gets a query.
API scopes: sql
Parameters
- idstringRequiredpath
UUID of the query to fetch.
Response
Returns the Query object.
List queries GA
GET
Gets a list of queries accessible to the user, ordered by creation time. Warning: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban.
API scopes: sql
Parameters
- page_tokenstringquery
Token from the
next_page_tokenof a previous response. Omit it to fetch the first page.
- page_sizeint32<= 100query
Maximum number of queries to return per page. Values above 100 are coerced to 100.
Response
- resultsarray of object
Queries on this page.
Show child attributesHide child attributes
- idstringIDImmutable
UUID identifying the query.
- display_namestring
Display name of the query that appears in list views, widget headings, and on the query page.
- descriptionstring
General description that conveys additional information about this query such as usage notes.
- owner_user_namestring
Username of the user that owns the query.
- warehouse_idstring
ID of the SQL warehouse attached to the query.
- query_textstring
Text of the query to be run.
- run_as_modestring
Whose credentials the query runs with when it is shared.
VIEWERuses the credentials of the user running the query.OWNERuses the owner's credentials where the product supports that, such as for legacy alerts and jobs. When omitted on create, the workspace default applies. A workspace admin can disallowOWNER.OWNERVIEWER
- lifecycle_statestring
Indicates whether the query is trashed.
ACTIVETRASHED
- last_modifier_user_namestring
Username of the user who last saved changes to this query.
- tagsarray of string
Tags attached to the query. Tags appear in the query list and can be used to filter it.
- create_timestring
Timestamp when this query was created.
- update_timestring
Timestamp when this query was last updated.
- parametersarray of object
List of query parameter definitions.
Show child attributesHide child attributes
- titlestring
Text displayed in the user-facing parameter widget in the UI.
- namestring
Literal parameter marker that appears between double curly braces in the query text.
- text_valueobject
Text query parameter value.
Show child attributesHide child attributes
- valuestring
Text substituted for the parameter marker when the query runs. Quotation marks are added around the value automatically.
- numeric_valueobject
Numeric query parameter value.
Show child attributesHide child attributes
- valuedouble
Number substituted for the parameter marker when the query runs.
- enum_valueobject
Dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- enum_optionsstring
List of valid query parameter values, newline delimited.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- date_valueobject
Date query parameter value. Can only specify one of
dynamic_date_valueordate_value.Show child attributesHide child attributes
- dynamic_date_valuestring
Dynamic date-time value based on current date-time.
NOWYESTERDAY
- date_valuestring
Manually specified date-time value in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- date_range_valueobject
Date-range query parameter value. Can only specify one of
dynamic_date_range_valueordate_range_value.Show child attributesHide child attributes
- dynamic_date_range_valuestring
Dynamic date-time range value based on current date-time.
Show 17 possible values
TODAYYESTERDAYTHIS_WEEKTHIS_MONTHTHIS_YEARLAST_WEEKLAST_MONTHLAST_YEARLAST_HOURLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_60_DAYSLAST_90_DAYSLAST_12_MONTHS
- date_range_valueobject
Manually specified date-time range value.
Show child attributesHide child attributes
- startstringRequired
Start of the range in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- endstringRequired
End of the range, in the same format as
start.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- start_day_of_weekint32
Day the week starts on for week-based dynamic ranges such as
THIS_WEEKandLAST_WEEK, from 0 (Sunday) to 6 (Saturday). Defaults to 0.
- query_backed_valueobject
Query-based dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- query_idstring
UUID of the query that provides the parameter values.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- apply_auto_limitboolean
Whether to apply a 1000 row limit to the query result.
- catalogstring
Name of the catalog where this query will be executed.
- schemastring
Name of the schema where this query will be executed.
- next_page_tokenstring
Token to pass as
page_tokento fetch the next page. Omitted when there are no more pages.
Create a query GA
POST
Creates a query. The caller becomes the owner of the new query.
API scopes: sql
Request body
- queryobject
The query to create. A display name and query text are required.
Show child attributesHide child attributes
- display_namestring
Display name of the query that appears in list views, widget headings, and on the query page.
- descriptionstring
General description that conveys additional information about this query such as usage notes.
- warehouse_idstring
ID of the SQL warehouse attached to the query.
- query_textstring
Text of the query to be run.
- run_as_modestring
Whose credentials the query runs with when it is shared.
VIEWERuses the credentials of the user running the query.OWNERuses the owner's credentials where the product supports that, such as for legacy alerts and jobs. When omitted on create, the workspace default applies. A workspace admin can disallowOWNER.OWNERVIEWER
- parent_pathstring
Workspace path of the workspace folder containing the object.
- tagsarray of string
Tags attached to the query. Tags appear in the query list and can be used to filter it.
- parametersarray of object
List of query parameter definitions.
Show child attributesHide child attributes
- titlestring
Text displayed in the user-facing parameter widget in the UI.
- namestring
Literal parameter marker that appears between double curly braces in the query text.
- text_valueobject
Text query parameter value.
Show child attributesHide child attributes
- valuestring
Text substituted for the parameter marker when the query runs. Quotation marks are added around the value automatically.
- numeric_valueobject
Numeric query parameter value.
Show child attributesHide child attributes
- valuedouble
Number substituted for the parameter marker when the query runs.
- enum_valueobject
Dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- enum_optionsstring
List of valid query parameter values, newline delimited.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- date_valueobject
Date query parameter value. Can only specify one of
dynamic_date_valueordate_value.Show child attributesHide child attributes
- dynamic_date_valuestring
Dynamic date-time value based on current date-time.
NOWYESTERDAY
- date_valuestring
Manually specified date-time value in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- date_range_valueobject
Date-range query parameter value. Can only specify one of
dynamic_date_range_valueordate_range_value.Show child attributesHide child attributes
- dynamic_date_range_valuestring
Dynamic date-time range value based on current date-time.
Show 17 possible values
TODAYYESTERDAYTHIS_WEEKTHIS_MONTHTHIS_YEARLAST_WEEKLAST_MONTHLAST_YEARLAST_HOURLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_60_DAYSLAST_90_DAYSLAST_12_MONTHS
- date_range_valueobject
Manually specified date-time range value.
Show child attributesHide child attributes
- startstringRequired
Start of the range in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- endstringRequired
End of the range, in the same format as
start.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- start_day_of_weekint32
Day the week starts on for week-based dynamic ranges such as
THIS_WEEKandLAST_WEEK, from 0 (Sunday) to 6 (Saturday). Defaults to 0.
- query_backed_valueobject
Query-based dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- query_idstring
UUID of the query that provides the parameter values.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- apply_auto_limitboolean
Whether to apply a 1000 row limit to the query result.
- catalogstring
Name of the catalog where this query will be executed.
- schemastring
Name of the schema where this query will be executed.
- auto_resolve_display_nameboolean
If true, automatically resolve query display name conflicts. Otherwise, fail the request if the query's display name conflicts with an existing query's display name.
Response
Returns the Query object.
Update a query GA
PATCH
Updates the fields of a query named in update_mask. Changing owner_user_name requires
workspace admin privileges. Changing run_as_mode requires CAN MANAGE permission on the query,
and only the query owner can switch it to OWNER.
API scopes: sql
Parameters
- idstringRequiredpath
UUID of the query to update.
Request body
- queryobject
Query fields to update. Only the fields named in
update_maskare changed.Show child attributesHide child attributes
- display_namestring
Display name of the query that appears in list views, widget headings, and on the query page.
- descriptionstring
General description that conveys additional information about this query such as usage notes.
- owner_user_namestring
Username of the user that owns the query.
- warehouse_idstring
ID of the SQL warehouse attached to the query.
- query_textstring
Text of the query to be run.
- run_as_modestring
Whose credentials the query runs with when it is shared.
VIEWERuses the credentials of the user running the query.OWNERuses the owner's credentials where the product supports that, such as for legacy alerts and jobs. When omitted on create, the workspace default applies. A workspace admin can disallowOWNER.OWNERVIEWER
- tagsarray of string
Tags attached to the query. Tags appear in the query list and can be used to filter it.
- parametersarray of object
List of query parameter definitions.
Show child attributesHide child attributes
- titlestring
Text displayed in the user-facing parameter widget in the UI.
- namestring
Literal parameter marker that appears between double curly braces in the query text.
- text_valueobject
Text query parameter value.
Show child attributesHide child attributes
- valuestring
Text substituted for the parameter marker when the query runs. Quotation marks are added around the value automatically.
- numeric_valueobject
Numeric query parameter value.
Show child attributesHide child attributes
- valuedouble
Number substituted for the parameter marker when the query runs.
- enum_valueobject
Dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- enum_optionsstring
List of valid query parameter values, newline delimited.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- date_valueobject
Date query parameter value. Can only specify one of
dynamic_date_valueordate_value.Show child attributesHide child attributes
- dynamic_date_valuestring
Dynamic date-time value based on current date-time.
NOWYESTERDAY
- date_valuestring
Manually specified date-time value in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- date_range_valueobject
Date-range query parameter value. Can only specify one of
dynamic_date_range_valueordate_range_value.Show child attributesHide child attributes
- dynamic_date_range_valuestring
Dynamic date-time range value based on current date-time.
Show 17 possible values
TODAYYESTERDAYTHIS_WEEKTHIS_MONTHTHIS_YEARLAST_WEEKLAST_MONTHLAST_YEARLAST_HOURLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_60_DAYSLAST_90_DAYSLAST_12_MONTHS
- date_range_valueobject
Manually specified date-time range value.
Show child attributesHide child attributes
- startstringRequired
Start of the range in the format
yyyy-MM-dd, optionally followed by a time asHH:mmorHH:mm:ss.
- endstringRequired
End of the range, in the same format as
start.
- precisionstring
Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
DAY_PRECISIONMINUTE_PRECISIONSECOND_PRECISION
- start_day_of_weekint32
Day the week starts on for week-based dynamic ranges such as
THIS_WEEKandLAST_WEEK, from 0 (Sunday) to 6 (Saturday). Defaults to 0.
- query_backed_valueobject
Query-based dropdown query parameter value.
Show child attributesHide child attributes
- valuesarray of string
List of selected query parameter values.
- query_idstring
UUID of the query that provides the parameter values.
- multi_values_optionsobject
If specified, allows multiple values to be selected for this parameter.
Show child attributesHide child attributes
- prefixstring
Character that prefixes each selected parameter value.
- separatorstring
Character that separates each selected parameter value. Defaults to a comma.
- suffixstring
Character that suffixes each selected parameter value.
- apply_auto_limitboolean
Whether to apply a 1000 row limit to the query result.
- catalogstring
Name of the catalog where this query will be executed.
- schemastring
Name of the schema where this query will be executed.
- update_maskstringRequired
Comma-separated list of the query fields to update, such as the display name or query text. Fields not listed keep their current values.
- auto_resolve_display_nameboolean
If true, automatically resolve query display name conflicts. Otherwise, fail the request if the query's display name conflicts with an existing query's display name.
Response
Returns the Query object.
Delete a query GA
DELETE
Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and cannot be used for alerts. You can restore a trashed query through the UI. A trashed query is permanently deleted after 30 days.
API scopes: sql
Parameters
- idstringRequiredpath
UUID of the query to move to the trash.