tagsde consulta

info

Visualização

Este recurso está em Pré-visualização Pública.

Esta página descreve como usar tags de consulta para agrupar, filtrar e atribuir custos a cargas de trabalho SQL em data warehouses Databricks SQL .

tags de consulta são pares personalizados de key-valor (por exemplo, team:marketing ou dbt_model_name:some_model_name) que você aplica às cargas de trabalho SQL . Essas tags aparecem na tabela system.query.history e na página Query History da interface do usuário Databricks e são retornadas nas respostas da APIListQueries se não estiverem vazias. As tags de consulta permitem agrupar consultas por contexto de negócios, atribuir custos ao data warehouse e identificar as origens de consultas de longa duração.

atenção

Os dados das tags são armazenados como texto simples e podem ser replicados globalmente. Não utilize chaves ou valores tag que contenham senhas, informações pessoais ou outros dados sensíveis.

Requisitos

Antes de usar as tags de consulta, verifique o seguinte:

Confirme se você pode acessar a tabela system.query.history , especificamente a coluna query_tags . Caso contrário, entre em contato com o administrador da sua account . Consulte Referência da tabela do sistema Consulta história.
Requisitos mínimos de versão com base em onde você define as tags de consulta:
- dbt : dbt-databricks 1.11.0
- Power BI : lançamento em outubro de 2025
- Conector Python : v4.1.3
- Conector Node.js : v1.12.0
- Go Connector : v1.9.0
- Driver JDBC (OSS) : v3.0.3

Escopo da tag de consulta

tags de consulta são restritas às sessõesDatabricks SQL. Você pode defini-los ao criar uma sessão como um parâmetro de configuração ou dentro de uma sessão usando a instrução SQL SET QUERY_TAGS . Após definir as tags, todas as instruções subsequentes na sessão ficam associadas a essas tags.

Defina as tags de consulta.

Você pode definir tags de consulta usando parâmetros de configuração de sessão ou instruções SQL.

Usar parâmetros de configuração de sessão

Defina as tags de consulta usando o parâmetro de configuração query_tags (ou ssp_query_tags em alguns drivers) ao criar uma sessão. O valor é um conjunto serializado de pares key-valor, com dois pontos (:) separando chave e valores, e uma vírgula (,) separando pares. Este formato de string é aceito pelas interfaces de cliente listadas em Definir tags de consulta de ferramentas e interfaces. Para obter instruções sobre como configurar sessões em seu cliente específico, consulte os exemplos abaixo.

Se dois pontos (:), vírgula (,) ou barra invertida (\) aparecerem em um valor, escape-os com uma barra invertida inicial (\\:, \\, ou \\\\). A barra invertida (\) deve ser escapada tanto na chave quanto nos valores.

O exemplo a seguir especifica tags team=eng, cost_center=701, uma tag somente com keyexp e uma tag metadata com um blob JSON :

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

Utilize instruções SQL

Use a instrução SET QUERY_TAGS para definir, ler ou remover tags de consulta para a sessão atual.

Para sintaxe, parâmetros e exemplos, consulte SET QUERY_TAGS.

Defina tags de consulta a partir de ferramentas e interfaces.

Interface do usuário do Databricks

Use a instrução SQL SET QUERY_TAGS em qualquer lugar onde você possa enviar SQL para um data warehouse, incluindo o editor SQL , o Notebook e os dashboards. Consulte SET QUERY_TAGS.

dbt

Versão mínima: dbt-databricks 1.11.0

As seguintes chaves tag consulta reservadas são definidas automaticamente para todas as execuções dbt e não podem ser substituídas:

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

nota

tags padrão estão sujeitas a limitações de sintaxe. Os nomes de modelos que incluem dois pontos ou vírgulas não escapados resultam em tag_invalid: true na tabela do sistema.

Você pode adicionar tags de consulta personalizadas tanto no nível do projeto quanto no nível do modelo. A configuração do modelo tem prioridade sobre a configuração da conexão.

tagde nível de projeto (~/.dbt/profiles.yml):

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

tagde nível de modelo (~/.dbt/dbt_project.yml):

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

Resultado com ambas as configurações:

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

Versão mínima: lançamento em outubro de 2025

Configure a conexão com o armazém.
Acesse a caixa de diálogo de configurações do Databricks, conforme mostrado na imagem a seguir.
Na caixa de texto " tagsde consulta" , insira tags de consulta usando a sintaxe do parâmetro de configuração da sessão.
Clique em OK .

nota

Alterar tags de consulta e clicar em OK inicia uma nova sessão. tags definidas anteriormente são descartadas.

Tableau

Configure a conexão com o armazém.
Navegue até a tab SQLInicial .
Insira as tags de consulta usando o comando SET QUERY_TAGS. Você pode incluir parâmetros Tableau na key ou no valor.
Clique em "Entrar" para salvar e autenticar.

nota

Alterar o SQL inicial e clicar em "Entrar" inicia uma nova sessão. tags definidas anteriormente são descartadas.

Conector Python

Versão mínima: 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()

Conector Node.js

Versão mínima: 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);
  });

Conector Go

Versão mínima: v1.9.0

Cadeias de conexão 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()
}

Novo conector com parâmetros de sessão:

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

Driver JDBC (OSS)

Versão mínima: v3.0.3

URL de conexão:

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

Objeto de propriedades:

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

Driver JDBC (Simba)

URL de conexão:

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

Objeto de propriedades:

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

Inclua o parâmetro ssp_query_tags na sua configuração de conexão ODBC.

Limitações

Máximo de 20 tags especificadas pelo usuário por consulta. Ao usar interfaces não-SQL (parâmetros de configuração de sessão), as tags adicionais são descartadas e uma tag sentinela tag_truncated: true é adicionada.
A chave e o valor da tag não devem exceder 128 caracteres. Ao usar interfaces não-SQL (parâmetros de configuração de sessão), as tags que não são válidas são descartadas e tag_invalid é adicionado.
A chave da tag não deve conter os caracteres ,, :, -, /, = ou .. Ao usar interfaces não-SQL (parâmetros de configuração de sessão), as tags que não são válidas são descartadas e tag_invalid é adicionado. Instruções SQL com chave tag inválida falham com um erro em tempo de execução.
tags de consulta são suportadas apenas para cargas de trabalho Databricks SQL . A coluna query_tags não é preenchida para outros tipos compute .
Databricks pode usar internamente chaves que começam com @@ . Alguns conectores já utilizam esse prefixo. Evite este prefixo para prevenir conflitos.

visualizar tagsde consulta

Consulte a tabela system.query.history para view tags de consulta. Você pode agrupar e filtrar por chave específica ou por par key-valor.

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;

nota

tags que contêm apenas uma chave aparecem com o valor null . Para filtrá-los:

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

Para mais informações, consulte Consultar história referência da tabela do sistema.

Requisitos​

Escopo da tag de consulta​

Defina as tags de consulta.​

Usar parâmetros de configuração de sessão​

Utilize instruções SQL​

Defina tags de consulta a partir de ferramentas e interfaces.​

Interface do usuário do Databricks​

dbt​

Power BI​

Tableau​

Conector Python​

Conector Node.js​

Conector Go​

Driver JDBC (OSS)​

Driver JDBC (Simba)​

Driver ODBC​

Limitações​

visualizar tagsde consulta​

Requisitos

Escopo da tag de consulta

Defina as tags de consulta.

Usar parâmetros de configuração de sessão

Utilize instruções SQL

Defina tags de consulta a partir de ferramentas e interfaces.

Interface do usuário do Databricks

dbt

Power BI

Tableau

Conector Python

Conector Node.js

Conector Go

Driver JDBC (OSS)

Driver JDBC (Simba)

Driver ODBC

Limitações

visualizar tagsde consulta