查询标记

重要

此功能目前以公共预览版提供。

本页介绍如何使用查询标记对 Databricks SQL 仓库上的 SQL 工作负荷进行分组、筛选和属性成本。

查询标记是应用于 SQL 工作负荷的自定义键值对（例如， team:marketing 或 dbt_model_name:some_model_name）。这些标记显示在 system.query.history 表和 Azure Databricks UI 的 “查询历史记录 ”页上，如果不是空，则返回对 ListQueries API 的响应。通过查询标记，可以按业务上下文、属性仓库成本对查询进行分组，并确定长时间运行的查询的来源。

警告

标记数据以纯文本形式存储，可全局复制。不要使用包含密码、个人信息或其他敏感数据的标记键或值。

要求

在使用查询标记之前，请验证以下内容：

确认可以访问 system.query.history 表，特别是 query_tags 列。否则，请联系帐户管理员。请参阅查询历史记录系统表参考。
设置查询标记时的最低版本要求：
- dbt：dbt-databricks 1.11.0
- Power BI：2025 年 10 月版本
- Python 连接器：v4.1.3（会话级别）、v4.2.6（语句级别）
- Node.js 连接器：v1.12.0
- Go 连接器：v1.9.0
- JDBC 驱动程序（OSS）：v3.0.3

查询标记范围

查询标记的范围限定为 Databricks SQL 会话。在创建会话作为配置参数时，也可以使用 SQL 语句在 SET QUERY_TAGS 会话中设置它们。设置标记后，会话中的所有后续语句都与这些标记相关联。

设置查询标记

可以使用会话配置参数或 SQL 语句设置查询标记。

使用会话配置参数

创建会话时，使用 query_tags 配置参数（或 ssp_query_tags 在某些驱动程序中）设置查询标记。该值是一组序列化的键值对，其中冒号（:）分隔键和值，以及逗号（,）分隔对。此字符串格式由工具与接口的“设置查询标记”中列出的客户端接口接受。有关在特定客户端中配置会话的说明，请参阅以下示例。

如果冒号（:）、逗号（,）或反斜杠（\）出现在值中，请使用前导反斜杠（\\:、\\, 或 \\\\）来对其进行转义。反斜杠（\）在键和值中都必须进行转义。

以下示例指定标记 team=eng、cost_center=701，仅含键的标记 exp，以及包含 JSON blob 的标记 metadata：

query_tags = team:eng,cost_center:701,exp,metadata:{"foo"\\:"bar"\\,"baz"\\:1}

使用 SQL 语句

使用 SET QUERY_TAGS 语句设置、读取或删除当前会话的查询标记。

有关语法、参数和示例，请参阅 SET QUERY_TAGS。

从工具和接口设置查询标记

Azure Databricks UI

SET QUERY_TAGS可以在任意位置使用 SQL 语句，将 SQL 提交到仓库，包括 SQL 编辑器、笔记本和仪表板。请参阅 SET QUERY_TAGS。

Databricks SQL 语句执行 API （SEA）

将 query_tags 字段包含在 POST /api/2.0/sql/语句的请求正文中，以应用语句级标记。以这种方式设置的标记仅适用于该特定语句执行。

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/sql/statements" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": "abc123",
    "statement": "SELECT * FROM samples.nyctaxi.trips LIMIT 10",
    "query_tags": [
        { "key": "team", "value": "engineering" },
        { "key": "env", "value": "prod" }
      ]
  }'

dbt

最低版本： dbt-databricks 1.11.0

以下保留查询标记键会为所有 dbt 运行自动设置，也无法更改：

{
  "dbt_model_name": "my_model",
  "dbt_core_version": "1.10.7",
  "dbt_databricks_version": "1.11.0",
  "dbt_materialized": "incremental"
}

注释

默认标记受语法限制的约束。包含未转义冒号或逗号的模型名称会导致系统表中出现 tag_invalid: true 。

可以在项目和模型级别添加自定义查询标记。模型配置优先于连接配置。

项目级标记 （~/.dbt/profiles.yml）：

your_profile_name:
  target: dev
  outputs:
    dev:
      query_tags: '{"team": "marketing", "cost_center": "3000"}'

模型级标记 （~/.dbt/dbt_project.yml）：

name: 'your_project'
version: '1.0.0'
config-version: 2
models:
  your_model:
    +query_tags: '{"team": "content-marketing"}'

两种配置的结果是：

{
  "team": "content-marketing",
  "cost_center": "3000",
  "dbt_model_name": "model.dev.your_model",
  "dbt_core_version": "1.10.7",
  "dbt_databricks_version": "1.11.0",
  "dbt_materialized": "incremental"
}

Power BI

最低版本： 2025 年 10 月版本

配置与仓库的连接。
导航到 Databricks 设置对话框，如下图所示。
在 “查询标记 ”文本框中，使用会话配置参数语法输入查询标记。
单击 “确定” 。

注释

更改查询标记并单击 “确定 ”将启动一个新会话。以前设置的标记将被丢弃。

Tableau

配置与仓库的连接。
导航到 “初始 SQL ”选项卡。
使用 SET QUERY_TAGS输入查询标记。可以在键或值中包含 Tableau 参数。
单击 “登录 ”保存并进行身份验证。

注释

更改初始 SQL 并单击 “登录 ”会启动一个新会话。以前设置的标记将被丢弃。

Python 连接器

最低版本： v4.1.3（会话级别）、v4.2.6（语句级别）

会话级标记：

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
    query_tags = {"team": "engineering", "dashboard": "abc123"}
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 10")
        result = cursor.fetchall()

语句级标记：

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
) as connection:
    with connection.cursor() as cursor:
        cursor.execute(
            "SELECT * FROM samples.nyctaxi.trips LIMIT 10",
            query_tags={"team": "engineering", "dashboard": "abc123"}
        )
        result = cursor.fetchall()

Node.js 连接器

最低版本： v1.12.0

const { DBSQLClient } = require('@databricks/sql');
const client = new DBSQLClient();

client
  .connect({
    host: process.env.DATABRICKS_SERVER_HOSTNAME,
    path: process.env.DATABRICKS_HTTP_PATH,
    token: process.env.DATABRICKS_TOKEN,
  })
  .then(async (client) => {
    const session = await client.openSession({
      configuration: {
        query_tags: 'team:engineering,env:prod',
      },
    });

    const queryOperation = await session.executeStatement('SELECT * FROM samples.nyctaxi.trips LIMIT 10');
    const result = await queryOperation.fetchAll();

    await queryOperation.close();
    await session.close();
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

Go 连接器

最低版本： v1.9.0

DSN 连接字符串：

package main

import (
    "database/sql"
    "fmt"
    _ "github.com/databricks/databricks-sql-go"
)

func main() {
    dsn := "token:dapi1234@myworkspace.cloud.databricks.com:443/sql/1.0/endpoints/abc123?query_tags=team:engineering,env:prod"

    db, err := sql.Open("databricks", dsn)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT 10")
    if err != nil {
        panic(err)
    }
    defer rows.Close()
}

带有 WithSessionParams 的 NewConnector：

package main

import (
    "database/sql"
    "os"
    dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
    connector, err := dbsql.NewConnector(
        dbsql.WithAccessToken(os.Getenv("DATABRICKS_ACCESS_TOKEN")),
        dbsql.WithServerHostname(os.Getenv("DATABRICKS_HOST")),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
        dbsql.WithSessionParams(map[string]string{
            "query_tags": "team:engineering,env:prod",
        }),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT 10")
    if err != nil {
        panic(err)
    }
    defer rows.Close()
}

JDBC 驱动程序（OSS）

最低版本： v3.0.3

连接 URL：

String url = "jdbc:databricks://myworkspace.cloud.databricks.com:443/default;" +
             "httpPath=/sql/1.0/endpoints/abc123;" +
             "query_tags=team:engineering,env:prod;" +
             "AuthMech=3;UID=token;PWD=dapi1234";

Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM samples.nyctaxi.trips LIMIT 10");

Properties 对象：

String url = "jdbc:databricks://myworkspace.cloud.databricks.com:443/default";
Properties properties = new Properties();
properties.put("httpPath", "/sql/1.0/endpoints/abc123");
properties.put("query_tags", "team:engineering,env:prod");
properties.put("AuthMech", "3");
properties.put("UID", "token");
properties.put("PWD", "dapi1234");

Connection conn = DriverManager.getConnection(url, properties);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM samples.nyctaxi.trips LIMIT 10");

JDBC 驱动程序（Simba）

连接 URL：

String url = "jdbc:databricks://myworkspace.cloud.databricks.com:443;" +
             "httpPath=/sql/1.0/endpoints/abc123;" +
             "ssp_query_tags=team:engineering,env:prod;" +
             "AuthMech=3;UID=token;PWD=dapi1234";

Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM samples.nyctaxi.trips LIMIT 10");

Properties 对象：

String url = "jdbc:databricks://myworkspace.cloud.databricks.com:443";
Properties properties = new Properties();
properties.put("httpPath", "/sql/1.0/endpoints/abc123");
properties.put("ssp_query_tags", "team:engineering,env:prod");
properties.put("AuthMech", "3");
properties.put("UID", "token");
properties.put("PWD", "dapi1234");

Connection conn = DriverManager.getConnection(url, properties);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM samples.nyctaxi.trips LIMIT 10");

ODBC 驱动程序

在 ODBC 连接配置中包含参数 ssp_query_tags 。

查看查询标记

查询system.query.history表以查看查询标签。可以按特定键或键值对进行分组和筛选。

SELECT statement_id, query_tags, executed_by, start_time
FROM system.query.history
WHERE MAP_CONTAINS_KEY(query_tags, 'team')
  AND query_tags['team'] = 'engineering'
ORDER BY start_time DESC
LIMIT 100;

注释

仅键标记会显示一个 null 值。要筛选这些内容：

WHERE MAP_CONTAINS_KEY(query_tags, 'key') AND query_tags['key'] IS NULL

有关详细信息，请参阅查询历史记录系统表参考。

局限性

每个会话的查询标记限制为 10 KB。如果总大小超过此限制，则会删除传入的查询标记，并 tags_dropped: true 添加 sentinel 标记。
每个查询最多支持 20 个用户指定的标记。使用非 SQL 接口（会话配置参数）时，会丢弃其他标记，并 tag_truncated: true 添加 sentinel 标记。
标记键和值不得超过 128 个字符。使用非 SQL 接口（会话配置参数）时，将丢弃无效标记并 tag_invalid 添加。
标记键不得包含字符,、:、-、/或=.。使用非 SQL 接口（会话配置参数）时，将丢弃无效标记并 tag_invalid 添加。具有无效标记键的 SQL 语句在执行时失败，并出现错误。
仅 Databricks SQL 工作负荷支持查询标记。该列不会为其他计算类型填充。
开头的 @@ 密钥保留供内部使用。避免此前缀以防止冲突。

反馈

此页面是否有帮助？

Last updated on 2026-04-04