クエリタグ

備考

プレビュー

このページでは、クエリタグを使用して、Databricks SQL ウェアハウス上の SQL ワークロードのコストをグループ化、フィルター処理、属性付けする方法について説明します。

クエリタグは、SQL ワークロードに適用するカスタムのキーと値のペア (たとえば、 team:marketingまたはdbt_model_name:some_model_name ) です。これらのタグは、 Databricks UI のsystem.query.historyテーブルと 書き込みー履歴 ページに表示され、空でない場合はListQueries APIへの応答として返されます。クエリタグを使用すると、ビジネスコンテキストごとにクエリをグループ化し、ウェアハウスのコストを属性化し、長時間実行されるクエリのソースを識別できます。

警告

タグデータはプレーンテキストとして保存され、グローバルに複製される可能性があります。パスワード、個人情報、その他の機密データを含むタグキーまたは値は使用しないでください。

要件

クエリタグを使用する前に、次の点を確認してください。

system.query.historyテーブル、具体的にはquery_tags列にアクセスできることを確認します。そうでない場合は、アカウント管理者に問い合わせてください。「クエリ履歴システムテーブルリファレンス」を参照してください。
クエリタグを設定する場所に基づく最小バージョン要件:
- dbt : dbt-databricks 1.11.0
- Power BI : 2025年10月リリース
- Python コネクタ : v4.1.3
- Node.js コネクタ : v1.12.0
- Go コネクタ : v1.9.0
- JDBC ドライバー (OSS) : v3.0.3

クエリタグのスコープ

クエリタグの範囲はDatabricks SQL セッションに限定されます。これらは、セッションを作成するときに構成引数として設定することも、セッション内でSET QUERY_TAGS SQLステートメントを使用して設定することもできます。タグを設定すると、セッション内の後続のすべてのステートメントはそれらのタグに関連付けられます。

クエリタグを設定する

セッション構成またはSQLステートメントを使用してクエリタグを設定できます。

セッション構成を使用する

セッションの作成時に、 query_tags構成の問題 (または一部のドライバーではssp_query_tags ) を使用してクエリタグを設定します。値はシリアル化されたキーと値のペアのセットであり、キーと値はコロン ( : ) で区切られ、ペアはコンマ ( , ) で区切られます。この文字列形式は、「ツールとインターフェースからのクエリタグの設定」にリストされているクライアントインターフェースで受け入れられます。特定のクライアントでセッションを構成する手順については、以下の例を参照してください。

値にコロン ( : )、カンマ ( , )、またはバックスラッシュ ( \ ) が含まれる場合は、先頭にバックスラッシュを付けてエスケープします ( \\: 、 \\, 、または\\\\ )。キーと値の両方でバックスラッシュ ( \ ) をエスケープする必要があります。

次の例では、タグteam=eng 、 cost_center=701 、キーのみのタグexp 、およびJSON BLOB を含むmetadataタグを指定します。

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

SQL文を使用する

現在のセッションのクエリタグを設定、読み取り、または削除するには、 SET QUERY_TAGSステートメントを使用します。

構文、問題、および例については、 SET QUERY_TAGS」を参照してください。

ツールやインターフェースからクエリタグを設定する

Databricks UI

SQL エディター、ノートブック、ダッシュボードなど、ウェアハウスに SQL を送信できる場所であればどこでも、 SET QUERY_TAGS SQL ステートメントを使用できます。SET QUERY_TAGS を参照してください。

dbt

最小バージョン: dbt-databricks 1.11.0

次の予約済みクエリタグキーは、すべての dbt 実行に対して自動的に設定され、上書きすることはできません。

JSON
{
  "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 ):

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

モデルレベルのタグ ( ~/.dbt/dbt_project.yml ):

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

両方の構成の結果 :

JSON
{
  "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 設定ダイアログに移動します。
[クエリタグ] テキストボックスに、セッション構成問題構文を使用してクエリタグを入力します。
OK をクリックします。

注記

クエリタグを変更して [OK] をクリックすると、新しいセッションが開始されます。以前に設定されたタグは破棄されます。

Tableau

ウェアハウスへの接続を設定します。
「初期 SQL」 タブに移動します。
SET QUERY_TAGSを使用してクエリタグを入力します。Tableauキーまたは値に含めることができます。
「サインイン」 をクリックして保存し、認証します。

注記

初期 SQL を変更し、 「サインイン」 をクリックすると、新しいセッションが開始されます。以前に設定されたタグは破棄されます。

Pythonコネクタ

最小バージョン: v4.1.3

Python
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"),
    session_configuration = {
        '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()

Node.js コネクタ

最小バージョン: v1.12.0

JavaScript
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 接続文字列:

Go
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:

Go
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:

Java
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");

プロパティオブジェクト:

Java
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:

Java
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");

プロパティオブジェクト:

Java
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問題を含めます。

制限事項

クエリごとに最大 20 個のユーザー指定タグ。非 SQL インターフェイス (セッション構成) を使用する場合、追加のタグは破棄され、センチネルタグtag_truncated: trueが追加されます。
タグのキーと値は 128 文字を超えてはなりません。非 SQL インターフェース (セッション構成) を使用する場合、無効なタグは破棄され、 tag_invalidが追加されます。
タグキーには、文字, 、 : 、 - 、 / 、 = 、または.を含めることはできません。非 SQL インターフェース (セッション構成) を使用する場合、無効なタグは破棄され、 tag_invalidが追加されます。無効なタグキーを含む SQL ステートメントは、実行時にエラーで失敗します。
クエリタグは、Databricks SQL ワークロードでのみサポートされます。他のコンピュートタイプの場合、 query_tags列には値が入力されません。
Databricks は内部的に@@で始まるキーを使用する場合があります。一部のコネクタでは既にこのプレフィックスが使用されています。競合を防ぐため、このプレフィックスは使用しないでください。

クエリタグを表示

クエリタグを表示するには、 system.query.historyテーブルをクエリします。特定のキーまたはキーと値のペアでグループ化およびフィルタリングできます。

SQL
SELECT statement_id, query_tags, user_name, 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値とともに表示されます。フィルタリングするには:

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

詳細については、「クエリ履歴システムテーブルリファレンス」を参照してください。

要件​

クエリタグのスコープ​

クエリタグを設定する​

セッション構成を使用する​

SQL文を使用する​

ツールやインターフェースからクエリタグを設定する​

Databricks UI​

dbt​

Power BI​

Tableau​

Pythonコネクタ​

Node.js コネクタ​

Goコネクタ​

JDBC ドライバー (OSS)​

JDBC ドライバー (Simba)​

ODBC ドライバー​

制限事項​

クエリタグを表示​

要件