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 (nível de sessão), v4.2.6 (nível de instrução)
- SDK do Databricks para Python : 0.86.0
- 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.

API de Execução de InstruçõesDatabricks SQL (SEA)

Inclua o campo query_tags no corpo da solicitação POST /api/2.0/sql/statements para aplicar tags de nível de instrução. As tags definidas dessa forma aplicam-se somente à execução dessa instrução específica.

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

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.

Ativar tags de consulta automática

tags de consulta automática anexam automaticamente metadados de contexto Power BI às consultas enviadas aos data warehouses Databricks , sem exigir que você especifique manualmente os valores tag . Para ativar as tags de consulta automática, modifique a consulta M no Editor do Power Query para incluir EnableAutoQueryTags="true" nos parâmetros de conexão.

No Power BI Desktop ou no serviço Power BI , encontre o modelo semântico que inclui a consulta que você deseja tag.
Abra o Editor do Power Query .
Abra o Editor Avançado .
Adicione EnableAutoQueryTags="true" às opções na chamada DatabricksMultiCloud.Catalogs .

O exemplo a seguir mostra uma consulta M com tags de consulta automática ativadas:

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

Quando as tags de consulta automática estão ativadas, o Power BI anexa automaticamente as seguintes tags reservadas (prefixadas com @@) às consultas. As tags disponíveis dependem do modo de conexão Power BI :

keyde etiqueta	Consulta direta	Importar
`@@powerbi_activity_id`	Sim	Sim
`@@powerbi_dataset_id`	Sim	Não
`@@powerbi_report_id`	Sim	Não
`@@powerbi_visual_id`	Sim	Não

nota

As tags de consulta automática não são anexadas a consultas de metadados (como consultas de descoberta de catálogo ou esquema) em nenhum modo.

Parametrize a configuração.

Se o seu modelo semântico contiver várias tabelas, a Databricks recomenda definir EnableAutoQueryTags como um parâmetro do Power Query. Isso permite ativar ou desativar as tags de consulta automática em todas as consultas a partir de um único local, em vez de editar cada consulta individualmente.

No Editor do Power Query , selecione Gerenciar Parâmetros > Novo Parâmetro .
Crie um parâmetro chamado EnableAutoQueryTags com um tipo de Texto e um valor atual de "true".
Em cada consulta, substitua o valor fixo EnableAutoQueryTags="true" por uma referência ao parâmetro.

O exemplo a seguir mostra uma consulta M que faz referência ao parâmetro:

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

Com essa abordagem, você pode ativar/desativar as tags de consulta automática para todas as consultas em seu modelo semântico atualizando o valor do parâmetro uma única vez, sem precisar editar as consultas individualmente.

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 (nível de sessão), v4.2.6 (nível de instrução)

tags de nível de sessão:

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 de nível de declaração:

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={"team": "engineering", "dashboard": "abc123"}
        )
        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. Você também deve definir ApplySSPWithQueries=0 na configuração de conexão do seu driver ODBC.

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, 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;

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.

Limitações

As tags de consulta estão limitadas a 10 KB por sessão. Se o tamanho total exceder esse limite, as tags de consulta recebidas serão descartadas e uma tag sentinela tags_dropped: true será adicionada.
Cada consulta suporta um máximo de 20 tags especificadas pelo usuário. 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 invá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 invá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 compatíveis apenas com cargas de trabalho Databricks SQL . A coluna query_tags não é preenchida para outros tipos compute .
As teclas que começam com @@ são reservadas para uso interno. Evite este prefixo para prevenir conflitos.

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​

API de Execução de InstruçõesDatabricks SQL (SEA)​

dbt​

Power BI​

Ativar tags de consulta automática​

Parametrize a configuração.​

Tableau​

Conector Python​

Conector Node.js​

Conector Go​

Driver JDBC (OSS)​

Driver JDBC (Simba)​

Driver ODBC​

visualizar tagsde consulta​

Limitações​

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

API de Execução de InstruçõesDatabricks SQL (SEA)

dbt

Power BI

Ativar tags de consulta automática

Parametrize a configuração.

Tableau

Conector Python

Conector Node.js

Conector Go

Driver JDBC (OSS)

Driver JDBC (Simba)

Driver ODBC

visualizar tagsde consulta

Limitações