クエリタグ

備考

プレビュー

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

クエリタグは、SQLワークロードに適用するカスタムのキーと値のペアです。クエリタグを使用すると、ビジネスコンテキストごとにクエリをグループ化し、ウェアハウスのコストを追跡し、長時間実行されるクエリのソースを特定できます。

タグは、 Databricks UI のsystem.query.historyテーブルと 書き込みー履歴 ページに表示されます。 ListQueries APIは、タグが存在する場合はタグも返します。例えば、 team:marketingでクエリにタグを付けてマーケティング作業負荷コストを追跡したり、 dbt_model_name:some_model_nameで特定の dbt モデルによって生成されたクエリを識別したりできます。

警告

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

要件

クエリタグを使用するには、以下のものが必要です。

system.query.historyテーブルのquery_tags列にアクセスできる必要があります。アクセス権がない場合は、アカウント管理者にお問い合わせください。クエリ履歴システムテーブルのリファレンスを参照してください。
コネクタまたはドライバは、最小バージョン要件を満たしている必要があります。バージョンの詳細については、「ツールとコネクタからクエリタグを設定する」の該当ツールまたはコネクタのセクションを参照してください。
Databricks SDK for Python ：クエリタグをサポートするには、バージョン0.86.0以上が必要です。

クエリタグの仕組み

クエリタグは、 Databricks SQLセッションにスコープされます。セッションレベルまたはステートメントレベルで設定できます。

セッションレベルのタグは、 そのセッション内の後続のすべてのステートメントに適用されます。設定を使用してセッションを作成する際に設定するか、セッション内でSET QUERY_TAGS SQLステートメントを使用して設定します。
ステートメントレベルのタグは、 単一のステートメントにのみ適用されます。以降のステートメントはセッションレベルのタグに戻ります。ステートメントレベルのタグは、Python Connector（v4.2.6以降）、Node.js Connector（v1.12.0以降）、Go Connector（v1.9.0以降）、およびステートメント実行APIで使用できます。

セッション構成の問題の構文

いくつかのツールとコネクタは、クエリタグをquery_tags (Simba ベースのドライバーの場合はssp_query_tags ) と呼ばれるセッション構成として受け入れます。値はキーと値のペアのシリアル化された文字列であり、コロン（ : ）がキーと値を区切り、コンマ（ , ）がペアを区切ります。

キーまたは値にコロン（ : ）、コンマ（ , ）、またはバックスラッシュ（ \ ）が含まれている場合は、先頭にバックスラッシュを付けてエスケープします。

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

逃れられない意図：

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

エスケープされた設定文字列:

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

SQL文

SET QUERY_TAGSステートメントを使用して、現在のセッションのクエリタグを設定、読み取り、または削除します。このステートメントは、SQLエディタ、ノートブック、ダッシュボードなど、データウェアハウスにSQLを送信できる場所であればどこでも使用できます。

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

ツールとコネクタからクエリタグを設定する

以下のセクションでは、サポートされている各ツール、コネクタ、およびドライバからクエリタグを設定する方法について説明します。

Databricks SQL ステートメント実行 API (SEA)

ステートメントレベルのタグを適用するには、 POST /api/2.0/sql/statementsのリクエストボディにquery_tagsフィールドを含めてください。このように設定されたタグは、そのステートメントの実行にのみ適用されます。

Bash
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 実行に対して自動的に設定され、上書きすることはできません。

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] をクリックすると、新しいセッションが開始されます。以前に設定されたタグは破棄されます。

自動クエリタグを有効にする

自動クエリータグは、Databricksウェアハウスに送信されたクエリーにPower BIコンテキストメタデータを自動的に添付します。自動クエリータグは、Arrow Database Connectivity (ADBC)ドライバーを使用している場合にのみ利用可能です。ODBCドライバーでは対応していません。

自動クエリタグを有効にするには、Power Query Editor の M クエリを編集して、接続パラメーターに EnableAutoQueryTags="true" を含めます。

Power BI Desktop または Power BI サービスで、タグ付けしたいクエリを含むセマンティックモデルを見つけます。
Power Query エディターを 開きます。
詳細エディター を開きます。
コネクタ呼び出しオプションにEnableAutoQueryTags="true"を追加します。

コネクタ呼び出しはDatabricksMultiCloud.Catalogsです。

以下の例は、自動クエリタグが有効になっているMクエリを示しています。

Powerquery
let
    Source = DatabricksMultiCloud.Catalogs(
        "myworkspace.cloud.databricks.com",
        "/sql/1.0/warehouses/abc123",
        [Catalog=null, Database=null, EnableAutoQueryTags="true",
         EnableAutomaticProxyDiscovery=null, Implementation="2.0"]),
    samples_Database = Source{[Name="samples",Kind="Database"]}[Data],
    nyctaxi_Schema = samples_Database{[Name="nyctaxi",Kind="Schema"]}[Data],
    trips_Table = nyctaxi_Schema{[Name="trips",Kind="Table"]}[Data]
in
    trips_Table

自動クエリタグが有効になっている場合、Power BI はクエリに次の予約済みタグ ( @@で始まる) を自動的に付加します。利用可能なタグは、Power BIの接続モードによって異なります。

タグキー	DirectQuery	インポート
`@@powerbi_activity_id`	はい	はい
`@@powerbi_dataset_id`	はい	No
`@@powerbi_report_id`	はい	No
`@@powerbi_visual_id`	はい	No

注記

自動クエリタグは、メタデータクエリ（カタログクエリやスキーマ検出クエリなど）には、どのモードでも添付されません。

設定をパラメータ化する

セマンティックモデルに複数のテーブルが含まれている場合は、Power Query パラメーターとしてEnableAutoQueryTags定義することで、各クエリを個別に編集する代わりに、単一の場所から設定をオンまたはオフに切り替えることができます。

Power Query エディター で、 [管理] > [新しい問題] を選択します。
タイプが Text 、現在の値が"true"のEnableAutoQueryTagsという名前の問題を作成します。
各クエリで、ハードコードされたEnableAutoQueryTags="true"を問題への参照に置き換えます。

次の例は、問題を参照する M クエリを示しています。

Powerquery
let
    Source = DatabricksMultiCloud.Catalogs(
        "myworkspace.cloud.databricks.com",
        "/sql/1.0/warehouses/abc123",
        [Catalog=null, Database=null, EnableAutoQueryTags=EnableAutoQueryTags,
         EnableAutomaticProxyDiscovery=null, Implementation="2.0"]),
    samples_Database = Source{[Name="samples",Kind="Database"]}[Data],
    nyctaxi_Schema = samples_Database{[Name="nyctaxi",Kind="Schema"]}[Data],
    trips_Table = nyctaxi_Schema{[Name="trips",Kind="Table"]}[Data]
in
    trips_Table

Tableau

Tableauで初期SQL機能を使用してクエリタグを設定します。

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

注記

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

Pythonコネクタ

最小バージョン: v4.1.3(セッションレベル)、v4.2.6 (ステートメントレベル)

セッションレベルのタグ

接続を作成するときに、 query_tags問題を渡します。セッション内のすべてのステートメントは、これらのタグを継承します。

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"),
    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()

ステートメントレベルのタグ

単一のステートメントにタグを付けるには、 query_tagsからcursor.execute()までの値を渡します。以降のステートメントはセッションレベルのタグに戻ります。

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"),
) as connection:
    with connection.cursor() as cursor:
        cursor.execute(
            "SELECT * FROM samples.nyctaxi.trips LIMIT 10",
            query_tags={&quot;team&quot;: &quot;engineering&quot;, &quot;dashboard&quot;: &quot;abc123&quot;}
        )
        result = cursor.fetchall()

Node.js コネクタ

最小バージョン: v1.12.0

セッションレベルのタグ

セッションを開く際にqueryTagsを渡してください。セッション内のすべてのステートメントは、これらのタグを継承します。

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({
      queryTags: {
        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);
  });

ステートメントレベルのタグ

単一のステートメントにタグを付けるには、 queryTagsからexecuteStatement()までの値を渡します。以降のステートメントはセッションレベルのタグに戻ります。

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();

    const queryOperation = await session.executeStatement('SELECT * FROM samples.nyctaxi.trips LIMIT 10', {
      queryTags: {
        team: 'engineering',
        request_id: 'abc-123',
      },
    });
    const result = await queryOperation.fetchAll();

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

Goコネクタ

最小バージョン: v1.9.0

DSN接続文字列

DSN 文字列にクエリとしてquery_tags含めます。

Go
package main
    "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()
}

WithQueryTags を使用した NewConnector

セッションレベルのタグをマップから設定するには、 WithQueryTags使用します。コネクタはシリアル化を自動的に処理します。

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.WithQueryTags(map[string]string{
            "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()
}

ステートメントレベルのタグ

単一のステートメントにタグを付けるには、 driverctx.NewContextWithQueryTagsを使用します。結果として得られたコンテキストをQueryContextまたはExecContextに渡します。

Go
package main

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

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")),
    )
    if err != nil {
        panic(err)
    }

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

    ctx := driverctx.NewContextWithQueryTags(context.Background(), map[string]string{
        "team":        "data-eng",
        "application": "etl-pipeline",
    })

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

JDBC ドライバー (OSS)

最小バージョン: v3.0.3

接続URL

JDBC接続URLにquery_tags直接含めてください。

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";
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM samples.nyctaxi.trips LIMIT 10");

プロパティオブジェクト

Propertiesオブジェクトを使用してquery_tagsを設定することもできます。

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("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)

Simba ドライバーは、 query_tagsではなく、問題名ssp_query_tagsを使用します。

接続URL

JDBC接続 URL 文字列にssp_query_tagsを含めます。

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

プロパティオブジェクト

Propertiesオブジェクトを使用してssp_query_tagsを設定することもできます。

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問題を含めます。接続設定でApplySSPWithQueries=0も設定する必要があります。

クエリタグを表示

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

SQL
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値が表示されます。キーのみのタグでフィルタリングするには：

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

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

制限事項

クエリタグには以下の制限が適用されます。

一般的な制限

以下の制限は、クエリタグの設定方法に関わらず、すべてのクエリタグに適用されます。

クエリタグは、Databricks SQLワークロードでのみサポートされています。他のコンピュートタイプの場合、 query_tags列には値が入力されません。
クエリタグはセッションごとに10KBまでという制限があります。合計サイズがこの制限を超えると、受信したタグは破棄され、 tags_dropped: true番兵タグが追加されます。
各クエリは、最大20個のユーザー指定タグをサポートします。
タグのキーと値は、128文字を超えてはなりません。
タグキーには、文字, 、 : 、 - 、 / 、 = 、または.を含めることはできません。
@@で始まるキーは内部使用のために予約されています。

セッション構成の問題の動作

( SQLではなく) セッション構成を使用してタグを設定する場合、次の追加動作が適用されます。

最大 20 タグを超えるタグは破棄され、 tag_truncated: trueセンチネルタグが追加されます。
キーまたは値が128文字を超えるタグ、あるいは無効な文字を含むキーを持つタグは破棄され、 tag_invalid: true番兵タグが追加されます。

SQL文を使用してタグを設定する場合、無効なタグキーがあると、実行時にエラーが発生して文が失敗します。

要件​

クエリタグの仕組み​

セッション構成の問題の構文​

SQL文​

ツールとコネクタからクエリタグを設定する​

Databricks SQL ステートメント実行 API (SEA)​

dbt​

プロジェクトレベルのタグ​

モデルレベルのタグ​

両方の構成での結果​

Power BI​

自動クエリタグを有効にする​

設定をパラメータ化する​

Tableau​

Pythonコネクタ​

セッションレベルのタグ​

ステートメントレベルのタグ​

Node.js コネクタ​

セッションレベルのタグ​

ステートメントレベルのタグ​

Goコネクタ​

DSN接続文字列​

WithQueryTags を使用した NewConnector​

ステートメントレベルのタグ​

JDBC ドライバー (OSS)​

接続URL​

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

JDBC ドライバー (Simba)​

接続URL​

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

ODBC ドライバー​

クエリタグを表示​

制限事項​

一般的な制限​

セッション構成の問題の動作​

要件

クエリタグの仕組み

セッション構成の問題の構文

SQL文

ツールとコネクタからクエリタグを設定する

Databricks SQL ステートメント実行 API (SEA)

dbt

プロジェクトレベルのタグ

モデルレベルのタグ

両方の構成での結果

Power BI

自動クエリタグを有効にする

設定をパラメータ化する

Tableau

Pythonコネクタ

セッションレベルのタグ

ステートメントレベルのタグ

Node.js コネクタ

セッションレベルのタグ

ステートメントレベルのタグ

Goコネクタ

DSN接続文字列

WithQueryTags を使用した NewConnector

ステートメントレベルのタグ

JDBC ドライバー (OSS)

接続URL

プロパティオブジェクト

JDBC ドライバー (Simba)

接続URL

プロパティオブジェクト

ODBC ドライバー

クエリタグを表示

制限事項

一般的な制限

セッション構成の問題の動作