queries_legacy

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

Overview

Name	queries_legacy
Type	Resource
Id	databricks_workspace.sql.queries_legacy

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Query ID.
name	string	The title of this query that appears in list views, widget headings, and on the query page.
data_source_id	string	Data source ID maps to the ID of the data source used by the resource and is distinct from the warehouse ID. [Learn more] [Learn more]: https://docs.databricks.com/api/workspace/datasources/list
last_modified_by_id	integer	The ID of the user who last saved changes to this query.
latest_query_data_id	string	If there is a cached result for this query and user, this field includes the query result ID. If this query uses parameters, this field is always null.
user_id	integer	The ID of the user who owns the query.
can_edit	boolean
created_at	string	The timestamp when this query was created.
description	string	General description that conveys additional information about this query such as usage notes.
is_archived	boolean	Indicates whether the query is trashed. Trashed queries can't be used in dashboards, or appear in search results. If this boolean is `true`, the `options` property for this query includes a `moved_to_trash_at` timestamp. Trashed queries are permanently deleted after 30 days.
is_draft	boolean	Whether the query is a draft. Draft queries only appear in list views for their owners. Visualizations from draft queries cannot appear on dashboards.
is_favorite	boolean	Whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is selected.
is_safe	boolean	Text parameter types are not safe from SQL injection for all types of data source. Set this Boolean parameter to `true` if a query either does not use any text type parameters or uses a data source type where text type parameters are handled safely.
▶last_modified_by	object
▶options	object
parent	string	The identifier of the workspace folder containing the object.
permission_tier	string	* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query * `CAN_MANAGE`: Can manage the query (CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_VIEW)
query	string	The text of the query to be run.
query_hash	string	A SHA-256 hash of the query text along with the authenticated user ID.
run_as_role	string	Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) (owner, viewer)
tags	array
updated_at	string	The timestamp at which this query was last updated.
▶user	object
▶visualizations	array

list

Name	Datatype	Description
id	string	Query ID.
name	string	The title of this query that appears in list views, widget headings, and on the query page.
data_source_id	string	Data source ID maps to the ID of the data source used by the resource and is distinct from the warehouse ID. [Learn more] [Learn more]: https://docs.databricks.com/api/workspace/datasources/list
last_modified_by_id	integer	The ID of the user who last saved changes to this query.
latest_query_data_id	string	If there is a cached result for this query and user, this field includes the query result ID. If this query uses parameters, this field is always null.
user_id	integer	The ID of the user who owns the query.
can_edit	boolean
created_at	string	The timestamp when this query was created.
description	string	General description that conveys additional information about this query such as usage notes.
is_archived	boolean	Indicates whether the query is trashed. Trashed queries can't be used in dashboards, or appear in search results. If this boolean is `true`, the `options` property for this query includes a `moved_to_trash_at` timestamp. Trashed queries are permanently deleted after 30 days.
is_draft	boolean	Whether the query is a draft. Draft queries only appear in list views for their owners. Visualizations from draft queries cannot appear on dashboards.
is_favorite	boolean	Whether this query object appears in the current user's favorites list. This flag determines whether the star icon for favorites is selected.
is_safe	boolean	Text parameter types are not safe from SQL injection for all types of data source. Set this Boolean parameter to `true` if a query either does not use any text type parameters or uses a data source type where text type parameters are handled safely.
▶last_modified_by	object
▶options	object
parent	string	The identifier of the workspace folder containing the object.
permission_tier	string	* `CAN_VIEW`: Can view the query * `CAN_RUN`: Can run the query * `CAN_EDIT`: Can edit the query * `CAN_MANAGE`: Can manage the query (CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_VIEW)
query	string	The text of the query to be run.
query_hash	string	A SHA-256 hash of the query text along with the authenticated user ID.
run_as_role	string	Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior) (owner, viewer)
tags	array
updated_at	string	The timestamp at which this query was last updated.
▶user	object
▶visualizations	array

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	query_id, deployment_name		Retrieve a query object definition along with contextual permissions information about the currently
list	select	deployment_name	order, page, page_size, q	Gets a list of queries. Optionally, this list can be filtered by a search term.
create	insert	deployment_name		Creates a new query definition. Queries created with this endpoint belong to the authenticated user
replace	replace	query_id, deployment_name		Modify this query definition.
delete	delete	query_id, deployment_name		Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and
restore	exec	query_id, deployment_name		Restore a query that has been moved to the trash. A restored query appears in list views and searches.

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)
query_id	string	str
order	string	Name of query attribute to order by. Default sort order is ascending. Append a dash (-) to order descending instead. - name: The name of the query. - created_at: The timestamp the query was created. - runtime: The time it took to run this query. This is blank for parameterized queries. A blank value is treated as the highest value for sorting. - executed_at: The timestamp when the query was last run. - created_by: The user name of the user that created the query.
page	integer	Page number to retrieve.
page_size	integer	Number of queries to return per page.
q	string	Full text search term

SELECT examples

get

Retrieve a query object definition along with contextual permissions information about the currently

SELECT
id,
name,
data_source_id,
last_modified_by_id,
latest_query_data_id,
user_id,
can_edit,
created_at,
description,
is_archived,
is_draft,
is_favorite,
is_safe,
last_modified_by,
options,
parent,
permission_tier,
query,
query_hash,
run_as_role,
tags,
updated_at,
user,
visualizations
FROM databricks_workspace.sql.queries_legacy
WHERE query_id = '{{ query_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

list

Gets a list of queries. Optionally, this list can be filtered by a search term.

SELECT
id,
name,
data_source_id,
last_modified_by_id,
latest_query_data_id,
user_id,
can_edit,
created_at,
description,
is_archived,
is_draft,
is_favorite,
is_safe,
last_modified_by,
options,
parent,
permission_tier,
query,
query_hash,
run_as_role,
tags,
updated_at,
user,
visualizations
FROM databricks_workspace.sql.queries_legacy
WHERE deployment_name = '{{ deployment_name }}' -- required
AND order = '{{ order }}'
AND page = '{{ page }}'
AND page_size = '{{ page_size }}'
AND q = '{{ q }}'
;

INSERT examples

create

Creates a new query definition. Queries created with this endpoint belong to the authenticated user

INSERT INTO databricks_workspace.sql.queries_legacy (
data_source_id,
description,
name,
options,
parent,
query,
run_as_role,
tags,
deployment_name
)
SELECT 
'{{ data_source_id }}',
'{{ description }}',
'{{ name }}',
'{{ options }}',
'{{ parent }}',
'{{ query }}',
'{{ run_as_role }}',
'{{ tags }}',
'{{ deployment_name }}'
RETURNING
id,
name,
data_source_id,
last_modified_by_id,
latest_query_data_id,
user_id,
can_edit,
created_at,
description,
is_archived,
is_draft,
is_favorite,
is_safe,
last_modified_by,
options,
parent,
permission_tier,
query,
query_hash,
run_as_role,
tags,
updated_at,
user,
visualizations
;

Manifest

# Description fields are for documentation purposes
- name: queries_legacy
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the queries_legacy resource.
  - name: data_source_id
    value: "{{ data_source_id }}"
    description: |
      Data source ID maps to the ID of the data source used by the resource and is distinct from the warehouse ID. [Learn more] [Learn more]: https://docs.databricks.com/api/workspace/datasources/list
  - name: description
    value: "{{ description }}"
    description: |
      General description that conveys additional information about this query such as usage notes.
  - name: name
    value: "{{ name }}"
    description: |
      The title of this query that appears in list views, widget headings, and on the query page.
  - name: options
    value: "{{ options }}"
    description: |
      Exclusively used for storing a list parameter definitions. A parameter is an object with `title`, `name`, `type`, and `value` properties. The `value` field here is the default value. It can be overridden at runtime.
  - name: parent
    value: "{{ parent }}"
    description: |
      The identifier of the workspace folder containing the object.
  - name: query
    value: "{{ query }}"
    description: |
      The text of the query to be run.
  - name: run_as_role
    value: "{{ run_as_role }}"
    description: |
      Sets the **Run as** role for the object. Must be set to one of `"viewer"` (signifying "run as viewer" behavior) or `"owner"` (signifying "run as owner" behavior)
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      :returns: :class:`LegacyQuery`

REPLACE examples

replace

Modify this query definition.

REPLACE databricks_workspace.sql.queries_legacy
SET 
data_source_id = '{{ data_source_id }}',
description = '{{ description }}',
name = '{{ name }}',
options = '{{ options }}',
query = '{{ query }}',
run_as_role = '{{ run_as_role }}',
tags = '{{ tags }}'
WHERE 
query_id = '{{ query_id }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
id,
name,
data_source_id,
last_modified_by_id,
latest_query_data_id,
user_id,
can_edit,
created_at,
description,
is_archived,
is_draft,
is_favorite,
is_safe,
last_modified_by,
options,
parent,
permission_tier,
query,
query_hash,
run_as_role,
tags,
updated_at,
user,
visualizations;

DELETE examples

delete

Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and

DELETE FROM databricks_workspace.sql.queries_legacy
WHERE query_id = '{{ query_id }}' --required
AND deployment_name = '{{ deployment_name }}' --required
;

Lifecycle Methods

restore

Restore a query that has been moved to the trash. A restored query appears in list views and searches.

EXEC databricks_workspace.sql.queries_legacy.restore 
@query_id='{{ query_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required
;