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 rastrear custos de cargas de trabalho SQL em data warehouses Databricks SQL .

tags de consulta são pares personalizados de key-valor que você aplica às cargas de trabalho SQL . Você pode usar tags de consulta para agrupar consultas por contexto de negócios, rastrear custos de armazenamento e identificar as origens de consultas de longa duração.

As tags aparecem na tabela system.query.history e na página Query History da interface do usuário do Databricks . A API ListQueries também retorna tags quando elas estão presentes. Por exemplo, você pode tag consultas com team:marketing para rastrear custos de carga de trabalho marketing ou dbt_model_name:some_model_name para identificar consultas geradas por um modelo dbt específico.

atenção

Os dados das tags são armazenados como texto simples e podem ser replicados globalmente. Não inclua senhas, informações de identificação pessoal ou outros dados sensíveis nas chaves ou valores tag .

Requisitos

Para usar tags de consulta, você precisa do seguinte:

Você deve ter acesso à coluna query_tags na tabela system.query.history . Se você não tiver acesso, entre em contato com o administrador da sua account . Consulte Referência da tabela do sistema Consulta história.
Seu conector ou driver deve atender a um requisito mínimo de versão. Consulte a seção específica da ferramenta ou conector em Definir tags de consulta de ferramentas e conectores para obter detalhes da versão.
SDK Databricks para Python : Versão mínima 0.86.0 para suporte tag de consulta.

Como funcionam as tags de consulta

tags de consulta são restritas às sessõesDatabricks SQL. Você pode configurá-los no nível da sessão ou no nível da instrução:

As tags de nível de sessão aplicam-se a todas as instruções subsequentes na sessão. Defina-os ao criar uma sessão usando um parâmetro de configuração ou dentro de uma sessão usando a instrução SQL SET QUERY_TAGS .
tagsde nível de declaração aplicam-se apenas a uma única declaração. As declarações subsequentes retornam às tags de nível de sessão. tags de nível de instrução estão disponíveis no conector Python (v4.2.6 ou superior), no conector Node.js (v1.12.0 ou superior), no conector Go (v1.9.0 ou superior) e na API de Execução de Instruções.

Sintaxe do parâmetro de configuração da sessão

Diversas ferramentas e conectores aceitam tags de consulta como um parâmetro de configuração de sessão chamado query_tags (ou ssp_query_tags para drivers baseados em Simba). O valor é uma string serializada de par key-valor, com dois pontos (:) separando chave e valores e vírgula (,) separando pares.

Se uma key ou valor contiver dois pontos (:), vírgula (,) ou barra invertida (\), escape-o com uma barra invertida inicial.

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

Intenção inconfundível:

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

Cadeias de configuração escapadas:

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

instruções SQL

Use a instrução SET QUERY_TAGS para definir, ler ou remover tags de consulta para a sessão atual. Você pode usar essa instrução em qualquer lugar onde possa enviar SQL para um data warehouse, incluindo o editor SQL , o Notebook e os dashboards.

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

Defina tags de consulta a partir de ferramentas e conectores.

As seções a seguir descrevem como definir tags de consulta para cada ferramenta, conector e driver compatível.

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 desta forma aplicam-se apenas à execução dessa instrução.

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

Arquivo: ~/.dbt/profiles.yml

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

tagde nível de modelo

Arquivo: ~/.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

Quando as tags de nível de projeto e de nível de modelo são definidas, as tags são mescladas. Os valores ao nível do modelo substituem os valores ao nível do projeto para a mesma key.

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.
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 associam automaticamente metadados de contexto do Power BI a consultas enviadas para os warehouses do Databricks. Tags de consulta automática estão disponíveis apenas ao utilizar o driver Arrow Database Connectivity (ADBC). Não são compatíveis com o driver ODBC.

Para ativar tags de consulta automática, modifique a query 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 de chamada do conector.

A chamada do conector é 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, defina EnableAutoQueryTags como um parâmetro do Power Query para que você possa ativar ou desativar a configuração em 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

Tableau

Defina tags de consulta no Tableau usando o recurso SQL Inicial.

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)

tagsde nível de sessão

Passe o parâmetro query_tags ao criar uma conexão. Todas as declarações na sessão herdam essas 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()

tagsde nível de declaração

Passe query_tags para cursor.execute() para tag uma única declaração. As declarações subsequentes retornam às 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"),
) 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()

Conector Node.js

Versão mínima: v1.12.0

tagsde nível de sessão

Passe queryTags ao abrir uma sessão. Todas as declarações na sessão herdam essas 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);
  });

tagsde nível de declaração

Passe queryTags para executeStatement() para tag uma única declaração. As declarações subsequentes retornam às tags de nível de sessão.

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

Conector Go

Versão mínima: v1.9.0

Cadeias de conexão DSN

Inclua query_tags como um parâmetro de consulta nas strings 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()
}

Novo conector com WithQueryTags

Use WithQueryTags para definir tags de nível de sessão a partir de um mapa. O conector lida com a serialização automaticamente.

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

tagsde nível de declaração

Use driverctx.NewContextWithQueryTags para adicionar tags a uma única declaração. Passe o contexto resultante para 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()
}

Driver JDBC (OSS)

Versão mínima: v3.0.3

URL de conexão

Inclua query_tags diretamente nas strings de URL de conexão 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");

Objeto de propriedades

Você também pode definir query_tags usando um objeto 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)

O driver Simba usa o nome do parâmetro ssp_query_tags em vez de query_tags.

URL de conexão

Inclua ssp_query_tags nas strings de URL de conexão 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");

Objeto de propriedades

Você também pode definir ssp_query_tags usando um objeto 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

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.

visualizar tagsde consulta

Consulte a tabela system.query.history para view tags de consulta. Você pode agrupar e filtrar por key 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;

tags que contêm apenas uma chave aparecem com o valor null . Para filtrar por uma tag que contenha apenas key :

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

Os seguintes limites se aplicam às tags de consulta.

Limites gerais

Os seguintes limites aplicam-se a todas as tags de consulta, independentemente de como estejam configuradas.

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 tags de consulta estão limitadas a 10 KB por sessão. Se o tamanho total exceder esse limite, as tags 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.
A chave e o valor da tag não devem exceder 128 caracteres.
A chave da tag não deve conter os caracteres ,, :, -, /, = ou ..
As teclas que começam com @@ são reservadas para uso interno.

Comportamento do parâmetro de configuração da sessão

Ao definir tags usando parâmetros de configuração de sessão (e não SQL), o seguinte comportamento adicional se aplica:

As tags que excedem o máximo de 20tag são descartadas e uma tag sentinela tag_truncated: true é adicionada.
As tags com chaves ou valores que excedam 128 caracteres, ou chaves que contenham caracteres inválidos, são descartadas e uma tag sentinela tag_invalid: true é adicionada.

Ao definir tags usando instruções SQL , uma chave tag inválida fará com que a instrução falhe com um erro em tempo de execução.

Requisitos​

Como funcionam as tags de consulta​

Sintaxe do parâmetro de configuração da sessão​

instruções SQL​

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

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

dbt​

tagde nível de projeto​

tagde nível de modelo​

Resultado com ambas as configurações​

Power BI​

Ativar tags de consulta automática​

Parametrize a configuração.​

Tableau​

Conector Python​

tagsde nível de sessão​

tagsde nível de declaração​

Conector Node.js​

tagsde nível de sessão​

tagsde nível de declaração​

Conector Go​

Cadeias de conexão DSN​

Novo conector com WithQueryTags​

tagsde nível de declaração​

Driver JDBC (OSS)​

URL de conexão​

Objeto de propriedades​

Driver JDBC (Simba)​

URL de conexão​

Objeto de propriedades​

Driver ODBC​

visualizar tagsde consulta​

Limitações​

Limites gerais​

Comportamento do parâmetro de configuração da sessão​

Requisitos

Como funcionam as tags de consulta

Sintaxe do parâmetro de configuração da sessão

instruções SQL

Defina tags de consulta a partir de ferramentas e conectores.

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

dbt

tagde nível de projeto

tagde nível de modelo

Resultado com ambas as configurações

Power BI

Ativar tags de consulta automática

Parametrize a configuração.

Tableau

Conector Python

tagsde nível de sessão

tagsde nível de declaração

Conector Node.js

tagsde nível de sessão

tagsde nível de declaração

Conector Go

Cadeias de conexão DSN

Novo conector com WithQueryTags

tagsde nível de declaração

Driver JDBC (OSS)

URL de conexão

Objeto de propriedades

Driver JDBC (Simba)

URL de conexão

Objeto de propriedades

Driver ODBC

visualizar tagsde consulta

Limitações

Limites gerais

Comportamento do parâmetro de configuração da sessão