Skip to main content
Last updated on

SET QUERY_TAGS

Applies to: check marked yes Databricks SQL

Preview

This feature is in Public Preview.

Sets, reads, or removes query tags for the current session.

Query tags are custom key-value pairs that you can apply to SQL workloads to enable grouping, filtering, and cost attribution in the system.query.history table. For a complete overview of query tags, see Query tags.

Syntax​

SQL
-- Set or update one or more query tags for the current session
SET QUERY_TAGS[<tag_key>] = <tag_value> [, ...]

-- Read the query tags defined on the session
SET QUERY_TAGS;

Parameters​

  • tag_key

    A string literal. Leading and trailing whitespace is trimmed.

  • tag_value

    A string literal, NULL, or UNSET.

    • Leading and trailing whitespace is removed.
    • If the trimmed result is an empty string, it is treated as NULL (key-only tag).
    • UNSET removes the specified key from query tags.

Examples​

SQL
-- Set two key-value pairs to annotate subsequent statement executions in this session.
> SET QUERY_TAGS['team'] = 'marketing', QUERY_TAGS['cost_center'] = '701';

-- Execute a query with the tags attached
> SELECT * FROM sales_data;

-- Update tags: change team value, add new tag, and remove cost_center tag
> SET QUERY_TAGS['team'] = 'engineering', QUERY_TAGS['env'] = 'prod', QUERY_TAGS['cost_center'] = UNSET;

-- Display all tags currently set on the session
> SET QUERY_TAGS;
  key         value
  ----------  -----------
  team        engineering
  env         prod

-- Set a key-only tag (value is NULL)
> SET QUERY_TAGS['experiment'] = NULL;

-- Execute another query with the updated tags
-- This statement execution will be tagged with team:engineering, env:prod, experiment
> SELECT * FROM sales_data;