Tags de query

info

Aperçu

Cette fonctionnalité est en Aperçu public.

Cette page décrit comment utiliser les balises de requête pour regrouper, filtrer et suivre les coûts des charges de travail SQL sur les SQL warehouse Databricks.

Les tags de query sont des paires clé-valeur personnalisées que vous appliquez aux charges de travail SQL. Vous pouvez utiliser des tags de query pour regrouper les queries par contexte métier, suivre les coûts du warehouse, et identifier les sources de queries de longue durée.

Les balises apparaissent dans la table system.query.history et sur la page Historique des requêtes de l'interface utilisateur de Databricks. L'API ListQueries renvoie également des balises lorsqu'elles sont présentes. Par exemple, vous pouvez étiqueter les query avec team:marketing pour suivre les coûts de la charge de travail marketing, ou filtrer sur l'étiquette @@dbt_model_name appliquée automatiquement pour identifier les query générées par un modèle dbt spécifique.

attention

Les données de balises sont stockées en texte brut et peuvent être répliquées globalement. N'incluez pas les mots de passe, les données personnelles identifiables ou d'autres données sensibles dans les clés ou les valeurs de tag.

Exigences

Pour utiliser les tags de query, vous devez disposer des éléments suivants :

Vous devez avoir accès à la colonne query_tags de la table system.query.history. Si vous n'avez pas accès, contactez votre administrateur de compte. Consulter la référence de la table système de l'historique des query.
Votre connecteur ou driver doit satisfaire une exigence de version minimale. Consultez la section outil ou connecteur spécifique dans Définir des tags de query à partir d'outils et de connecteurs pour les détails de la version.
**Databricks SDK pour Python** : version minimale 0.86.0 pour la prise en charge des balises de requête.

Fonctionnement des balises de query

Les étiquettes de requête sont limitées aux sessions Databricks SQL. Vous pouvez les définir au niveau de la session ou au niveau de l'instruction :

Les balises au niveau de la session s'appliquent à toutes les instructions suivantes dans la session. Définissez-les lors de la création d'une session à l'aide d'un paramètre de configuration, ou au sein d'une session à l'aide de l'instruction SQL SET QUERY_TAGS.
Les balises au niveau de l'instruction s'appliquent à une seule instruction uniquement. Les instructions suivantes rétablissent les balises au niveau de la session. Les balises au niveau de l'instruction sont disponibles dans le connecteur Python (v4.2.6 ou supérieur), le connecteur Node.js (v1.12.0 ou supérieur), le connecteur Go (v1.9.0 ou supérieur) et l'API d'exécution d'instructions.

Syntaxe des paramètres de configuration de session

Plusieurs outils et connecteurs acceptent les tags de query comme parameter de configuration de session appelé query_tags (ou ssp_query_tags pour les Drivers basés sur Simba). La valeur est une chaîne sérialisée de paires clé-valeur, avec un deux-points (:) séparant les clés et les valeurs et une virgule (,) séparant les paires.

Si une clé ou une valeur contient un signe deux points (:), une virgule (,) ou une barre oblique inverse (\), échappez-la avec une barre oblique inverse initiale.

L'exemple suivant spécifie les tags team:eng, cost_center:701, un tag à clé unique exp, et un tag metadata avec une valeur JSON.

Intention non échappée :

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

Chaîne de configuration échappée :

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

Instructions SQL

Utilisez l'instruction SET QUERY_TAGS pour définir, lire ou supprimer des tags de query pour la session actuelle. Vous pouvez utiliser cette instruction partout où vous pouvez soumettre du SQL à un Warehouse, y compris l'éditeur SQL, les Notebooks et les tableaux de bord.

Pour la syntaxe, les paramètres et des exemples, consultez SET QUERY_TAGS.

Définissez les tags de query à partir des outils et des connecteurs

Les sections suivantes décrivent comment définir les balises de query à partir de chaque outil, connecteur et Driver pris en charge.

API d'exécution des instructions Databricks SQL (SEA)

Incluez le champ query_tags dans le corps de la requête de POST /api/2.0/sql/statements pour appliquer des balises au niveau de l’instruction. Les tags définis de cette manière s'appliquent uniquement à cette exécution d'instruction.

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

Version minimale : dbt-databricks 1.11.0

Les clés de tag de requête réservées suivantes sont définies automatiquement pour toutes les exécutions dbt et ne peuvent pas être remplacées :

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

remarque

Les tags default sont soumis à des limitations de syntaxe. Les noms de modèle qui incluent des deux-points ou des virgules non échappés entraînent tag_invalid: true dans la table système.

Vous pouvez ajouter des tags de query personnalisés aux niveaux projet et modèle. La configuration du modèle a priorité sur la configuration de la connexion.

Balise de niveau projet

Fichier : ~/.dbt/profiles.yml

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

Tag de niveau modèle

Fichier : ~/.dbt/dbt_project.yml

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

Résultat avec les deux configurations

Lorsque les tags au niveau du projet et au niveau du modèle sont définis, les tags sont Merge. Les valeurs au niveau du modèle remplacent les valeurs au niveau du projet pour la même clé.

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

Version minimale : version d'octobre 2025.

Configurez la connexion au warehouse.
Accédez à la boîte de dialogue des paramètres Databricks.
Dans la zone de texte Balises de query , saisissez des balises de query en utilisant la syntaxe des paramètres de configuration de session.
Cliquez sur **OK**.

remarque

Modifier les tags de query et cliquer sur **OK** start une nouvelle session. Les tags précédemment définis sont ignorés.

Tags de query automatiques

Les balises de query automatiques associent automatiquement les métadonnées de contexte Power BI aux queries envoyées aux warehouses Databricks. À compter de la version de juillet 2026 du service Power BI, les étiquettes de query automatiques sont activées automatiquement — aucune configuration n'est requise pour les activer. Les étiquettes de query automatiques sont disponibles uniquement lors de l'utilisation du driver Arrow Database Connectivity (ADBC). Ils ne sont pas pris en charge avec le driver ODBC.

Power BI appose automatiquement les balises réservées suivantes (préfixées par @@) aux requêtes. Les tags disponibles dépendent du mode de connexion Power BI :

Clé de tag	DirectQuery	Importer
`@@powerbi_activity_id`	Oui	Oui
`@@powerbi_customer_tenant_id`	Oui	Oui
`@@powerbi_workspace_id`	Oui	Oui
`@@powerbi_dataset_id`	Oui	Non
`@@powerbi_report_id`	Oui	Non
`@@powerbi_visual_id`	Oui	Non

Clé de tag	DirectQuery	Importer
`@@powerbi_activity_id`	Oui	Oui
`@@powerbi_customer_tenant_id`	Oui	Oui
`@@powerbi_workspace_id`	Oui	Oui
`@@powerbi_dataset_id`	Oui	Non
`@@powerbi_report_id`	Oui	Non
`@@powerbi_visual_id`	Oui	Non

remarque

Les tags de query automatiques ne sont pas associés aux queries de métadonnées (telles que les queries de découverte de catalogue ou de schéma) dans aucun mode.

Désactiver les balises de query automatiques

Les balises de query automatiques sont activées par default. Pour les désactiver, modifiez la query M dans l'éditeur Power Query pour inclure EnableAutoQueryTags="false" dans les options d'appel du connecteur.

Powerquery
let
    Source = DatabricksMultiCloud.Catalogs(
        "myworkspace.cloud.databricks.com",
        "/sql/1.0/warehouses/abc123",
        [Catalog=null, Database=null, EnableAutoQueryTags="false",
         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

Définissez les query tags dans Tableau à l'aide de la fonctionnalité SQL initiale.

Configurez la connexion au warehouse.
Accédez au **tab SQL initial**.
Saisissez les tags de query à l'aide de la commande SET QUERY_TAGS. Vous pouvez inclure des paramètres Tableau dans la clé ou la valeur.
Cliquez sur Se connecter pour enregistrer et authentifier.

remarque

La modification du SQL initial et le clic sur Se connecter start une nouvelle session. Les tags précédemment définis sont ignorés.

Connecteur Python.

Version minimale : v4,1,3 (au niveau de la session), v4,2,6 (au niveau de la déclaration)

Tags au niveau de la session

Passez le parameter query_tags lors de la création d'une connexion. Toutes les instructions de la session héritent de ces 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()

Tags au niveau de l'instruction

Passez query_tags à cursor.execute() pour taguer une seule instruction. Les instructions suivantes reviennent aux tags de niveau session.

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

Connecteur Node.js

Version minimale : v1.12.0

Tags au niveau de la session

Passez queryTags lors de l'ouverture d'une session. Toutes les instructions de la session héritent de ces tags.

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

Tags au niveau de l'instruction

Passez queryTags à executeStatement() pour taguer une seule instruction. Les instructions suivantes reviennent aux tags de niveau session.

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

Connecteur Go

Version minimale : v1.9.0

Chaîne de connexion DSN

Incluez query_tags comme parameter de query dans la chaîne DSN.

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

NewConnector avec WithQueryTags

Utilisez WithQueryTags pour définir des tags de niveau session à partir d'une carte. Le connecteur gère automatiquement la sérialisation.

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

Tags au niveau de l'instruction

Utilisez driverctx.NewContextWithQueryTags pour attacher des tags à une seule instruction. Transmettez le contexte résultant à QueryContext ou 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 Driver (OSS)

Version minimale : v3.0.3

URL de connexion

Incluez query_tags directement dans la chaîne d'URL de connexion JDBC.

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

Objet Propriétés

Vous pouvez également définir query_tags à l'aide d'un objet Properties.

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

Driver JDBC (Simba)

Le Driver Simba utilise le nom du paramètre ssp_query_tags au lieu de query_tags.

URL de connexion

Incluez ssp_query_tags dans la chaîne d’URL de connexion JDBC.

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

Objet Propriétés

Vous pouvez également définir ssp_query_tags à l'aide d'un objet Properties.

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

Driver ODBC

Incluez le paramètre ssp_query_tags dans votre configuration de connexion ODBC. Vous devez également définir ApplySSPWithQueries=0 dans la configuration de la connexion.

Afficher les tags de query

Consultez la table system.query.history pour afficher les balises de query. Vous pouvez regrouper et filtrer par clé ou par paire clé-valeur.

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;

Les tags à clé unique apparaissent avec une valeur null. Pour filtrer un tag à clé unique :

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

Pour plus d’information, consultez la référence des tables système de l’historique des query.

Limitations

Les limites suivantes s'appliquent aux balises de query.

Limites générales

Les limites suivantes s'appliquent à tous les tags de query, quelle que soit la manière dont ils sont définis.

Les étiquettes de requête sont prises en charge uniquement pour les charges de travail Databricks SQL. La colonne query_tags n'est pas renseignée pour les autres types de compute.
Les balises de requête sont limitées à 10 Ko par session. Si la taille totale dépasse cette limite, les balises entrantes sont supprimées et une balise sentinelle tags_dropped: true est ajoutée.
Chaque query prend en charge un maximum de 20 tags spécifiés par l'utilisateur.
Les clés et valeurs de tag ne doivent pas dépasser 128 caractères.
Les clés de tag ne doivent pas contenir les caractères ,, :, -, /, = ou ..
Les clés commençant par @@ sont réservées à un usage interne.

Comportement du paramètre de configuration de session

Lorsque vous définissez des tags à l'aide de paramètres de configuration de session (pas SQL), le comportement supplémentaire suivant s'applique :

Les balises qui dépassent le maximum de 20 sont ignorées et une balise sentinelle tag_truncated: true est ajoutée.
Les balises dont les clés ou les valeurs dépassent 128 caractères, ou les clés qui contiennent des caractères non valides, sont ignorées et une balise sentinelle tag_invalid: true est ajoutée.

Lorsque vous définissez des tags à l’aide d’instructions SQL, des clés de tag non valides entraînent l’échec de l’instruction avec une erreur au moment de l’exécution.

Exigences​

Fonctionnement des balises de query​

Syntaxe des paramètres de configuration de session​

Instructions SQL​

Définissez les tags de query à partir des outils et des connecteurs​

API d'exécution des instructions Databricks SQL (SEA)​

dbt​

Balise de niveau projet​

Tag de niveau modèle​

Résultat avec les deux configurations​

Power BI​

Tags de query automatiques​

Désactiver les balises de query automatiques​

Tableau​

Connecteur Python.​

Tags au niveau de la session​

Tags au niveau de l'instruction​

Connecteur Node.js​

Tags au niveau de la session​

Tags au niveau de l'instruction​

Connecteur Go​

Chaîne de connexion DSN​

NewConnector avec WithQueryTags​

Tags au niveau de l'instruction​

JDBC Driver (OSS)​

URL de connexion​

Objet Propriétés​

Driver JDBC (Simba)​

URL de connexion​

Objet Propriétés​

Driver ODBC​

Afficher les tags de query​

Limitations​

Limites générales​

Comportement du paramètre de configuration de session​

Exigences

Fonctionnement des balises de query

Syntaxe des paramètres de configuration de session

Instructions SQL

Définissez les tags de query à partir des outils et des connecteurs

API d'exécution des instructions Databricks SQL (SEA)

dbt

Balise de niveau projet

Tag de niveau modèle

Résultat avec les deux configurations

Power BI

Tags de query automatiques

Désactiver les balises de query automatiques

Tableau

Connecteur Python.

Tags au niveau de la session

Tags au niveau de l'instruction

Connecteur Node.js

Tags au niveau de la session

Tags au niveau de l'instruction

Connecteur Go

Chaîne de connexion DSN

NewConnector avec WithQueryTags

Tags au niveau de l'instruction

JDBC Driver (OSS)

URL de connexion

Objet Propriétés

Driver JDBC (Simba)

URL de connexion

Objet Propriétés

Driver ODBC

Afficher les tags de query

Limitations

Limites générales

Comportement du paramètre de configuration de session