Skip to main content

Query

View as Markdown

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.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

Display name of the query that appears in list views, widget headings, and on the query page.

Example: Example query

descriptionstring

General description that conveys additional information about this query such as usage notes.

Example: Example description

owner_user_namestring

Username of the user that owns the query.

Example: user@acme.com

warehouse_idstring

ID of the SQL warehouse attached to the query.

Example: a7066a8ef796be84

query_textstring

Text of the query to be run.

Example: SELECT 1

run_as_modestring

Whose credentials the query runs with when it is shared. VIEWER uses the credentials of the user running the query. OWNER uses 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 disallow OWNER.

Values:

  • OWNER
  • VIEWER
lifecycle_statestring

Indicates whether the query is trashed.

Values:

  • ACTIVE
  • TRASHED
last_modifier_user_namestring

Username of the user who last saved changes to this query.

Example: user@acme.com

parent_pathstring

Workspace path of the workspace folder containing the object.

Example: /Users/user@acme.com

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_value or date_value.

Show child attributesHide child attributes
dynamic_date_valuestring

Dynamic date-time value based on current date-time.

Values:

  • NOW
  • YESTERDAY
date_valuestring

Manually specified date-time value in the format yyyy-MM-dd, optionally followed by a time as HH:mm or HH:mm:ss.

Example: 2024-01-15

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
date_range_valueobject

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes
dynamic_date_range_valuestring

Dynamic date-time range value based on current date-time.

Values:

Show 17 possible values
  • TODAY
  • YESTERDAY
  • THIS_WEEK
  • THIS_MONTH
  • THIS_YEAR
  • LAST_WEEK
  • LAST_MONTH
  • LAST_YEAR
  • LAST_HOUR
  • LAST_8_HOURS
  • LAST_24_HOURS
  • LAST_7_DAYS
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_60_DAYS
  • LAST_90_DAYS
  • LAST_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 as HH:mm or HH:mm:ss.

Example: 2024-01-01

endstring

End of the range, in the same format as start.

Example: 2024-01-31

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
start_day_of_weekint32

Day the week starts on for week-based dynamic ranges such as THIS_WEEK and LAST_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 /api/2.0/sql/queries/{id}

Gets a query.

API scopes: sql

Parameters​

idstringRequiredpath

UUID of the query to fetch.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

Response​

Returns the Query object.

List queries GA​

GET /api/2.0/sql/queries

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_token of 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.

Default: 20

Response​

resultsarray of object

Queries on this page.

Show child attributesHide child attributes
idstringIDImmutable

UUID identifying the query.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

Display name of the query that appears in list views, widget headings, and on the query page.

Example: Example query

descriptionstring

General description that conveys additional information about this query such as usage notes.

Example: Example description

owner_user_namestring

Username of the user that owns the query.

Example: user@acme.com

warehouse_idstring

ID of the SQL warehouse attached to the query.

Example: a7066a8ef796be84

query_textstring

Text of the query to be run.

Example: SELECT 1

run_as_modestring

Whose credentials the query runs with when it is shared. VIEWER uses the credentials of the user running the query. OWNER uses 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 disallow OWNER.

Values:

  • OWNER
  • VIEWER
lifecycle_statestring

Indicates whether the query is trashed.

Values:

  • ACTIVE
  • TRASHED
last_modifier_user_namestring

Username of the user who last saved changes to this query.

Example: user@acme.com

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_value or date_value.

Show child attributesHide child attributes
dynamic_date_valuestring

Dynamic date-time value based on current date-time.

Values:

  • NOW
  • YESTERDAY
date_valuestring

Manually specified date-time value in the format yyyy-MM-dd, optionally followed by a time as HH:mm or HH:mm:ss.

Example: 2024-01-15

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
date_range_valueobject

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes
dynamic_date_range_valuestring

Dynamic date-time range value based on current date-time.

Values:

Show 17 possible values
  • TODAY
  • YESTERDAY
  • THIS_WEEK
  • THIS_MONTH
  • THIS_YEAR
  • LAST_WEEK
  • LAST_MONTH
  • LAST_YEAR
  • LAST_HOUR
  • LAST_8_HOURS
  • LAST_24_HOURS
  • LAST_7_DAYS
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_60_DAYS
  • LAST_90_DAYS
  • LAST_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 as HH:mm or HH:mm:ss.

Example: 2024-01-01

endstringRequired

End of the range, in the same format as start.

Example: 2024-01-31

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
start_day_of_weekint32

Day the week starts on for week-based dynamic ranges such as THIS_WEEK and LAST_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_token to fetch the next page. Omitted when there are no more pages.

Create a query GA​

POST /api/2.0/sql/queries

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.

Example: Example query

descriptionstring

General description that conveys additional information about this query such as usage notes.

Example: Example description

warehouse_idstring

ID of the SQL warehouse attached to the query.

Example: a7066a8ef796be84

query_textstring

Text of the query to be run.

Example: SELECT 1

run_as_modestring

Whose credentials the query runs with when it is shared. VIEWER uses the credentials of the user running the query. OWNER uses 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 disallow OWNER.

Values:

  • OWNER
  • VIEWER
parent_pathstring

Workspace path of the workspace folder containing the object.

Example: /Users/user@acme.com

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_value or date_value.

Show child attributesHide child attributes
dynamic_date_valuestring

Dynamic date-time value based on current date-time.

Values:

  • NOW
  • YESTERDAY
date_valuestring

Manually specified date-time value in the format yyyy-MM-dd, optionally followed by a time as HH:mm or HH:mm:ss.

Example: 2024-01-15

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
date_range_valueobject

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes
dynamic_date_range_valuestring

Dynamic date-time range value based on current date-time.

Values:

Show 17 possible values
  • TODAY
  • YESTERDAY
  • THIS_WEEK
  • THIS_MONTH
  • THIS_YEAR
  • LAST_WEEK
  • LAST_MONTH
  • LAST_YEAR
  • LAST_HOUR
  • LAST_8_HOURS
  • LAST_24_HOURS
  • LAST_7_DAYS
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_60_DAYS
  • LAST_90_DAYS
  • LAST_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 as HH:mm or HH:mm:ss.

Example: 2024-01-01

endstringRequired

End of the range, in the same format as start.

Example: 2024-01-31

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
start_day_of_weekint32

Day the week starts on for week-based dynamic ranges such as THIS_WEEK and LAST_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.

Default: true

Response​

Returns the Query object.

Update a query GA​

PATCH /api/2.0/sql/queries/{id}

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.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

Request body​

queryobject

Query fields to update. Only the fields named in update_mask are 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.

Example: Example query

descriptionstring

General description that conveys additional information about this query such as usage notes.

Example: Example description

owner_user_namestring

Username of the user that owns the query.

Example: user@acme.com

warehouse_idstring

ID of the SQL warehouse attached to the query.

Example: a7066a8ef796be84

query_textstring

Text of the query to be run.

Example: SELECT 1

run_as_modestring

Whose credentials the query runs with when it is shared. VIEWER uses the credentials of the user running the query. OWNER uses 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 disallow OWNER.

Values:

  • OWNER
  • VIEWER
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_value or date_value.

Show child attributesHide child attributes
dynamic_date_valuestring

Dynamic date-time value based on current date-time.

Values:

  • NOW
  • YESTERDAY
date_valuestring

Manually specified date-time value in the format yyyy-MM-dd, optionally followed by a time as HH:mm or HH:mm:ss.

Example: 2024-01-15

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
date_range_valueobject

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes
dynamic_date_range_valuestring

Dynamic date-time range value based on current date-time.

Values:

Show 17 possible values
  • TODAY
  • YESTERDAY
  • THIS_WEEK
  • THIS_MONTH
  • THIS_YEAR
  • LAST_WEEK
  • LAST_MONTH
  • LAST_YEAR
  • LAST_HOUR
  • LAST_8_HOURS
  • LAST_24_HOURS
  • LAST_7_DAYS
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_60_DAYS
  • LAST_90_DAYS
  • LAST_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 as HH:mm or HH:mm:ss.

Example: 2024-01-01

endstringRequired

End of the range, in the same format as start.

Example: 2024-01-31

precisionstring

Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).

Values:

  • DAY_PRECISION
  • MINUTE_PRECISION
  • SECOND_PRECISION
start_day_of_weekint32

Day the week starts on for week-based dynamic ranges such as THIS_WEEK and LAST_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.

Default: true

Response​

Returns the Query object.

Delete a query GA​

DELETE /api/2.0/sql/queries/{id}

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.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d