Pular para o conteúdo principal
Última atualização em

tagsde consulta

Query tags são pares key-value personalizados que você aplica a cargas de trabalho SQL para que possa agrupar, filtrar e rastrear custos em Databricks SQL warehouse e no compute do Lakehouse Real-Time (Lakehouse//RT).

Use-as para agrupar queries por contexto de negócios, rastrear custos de warehouse e identificar fontes de queries de longa duração.

As tags aparecem na tabela system.query.history e na página Query History da IU do Databricks. A API ListQueries também retorna tags quando elas estão presentes. Por exemplo, você pode marcar queries com team:marketing para rastrear custos de workload de marketing, ou filtrar na tag @@dbt_model_name aplicada automaticamente para identificar queries geradas por um dbt model 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.

nota

Os conectores e Driver desta seção descrevem a configuração para warehouse do Databricks SQL. Para obter os métodos de conexão suportados no Lakehouse Real-Time (Lakehouse//RT), consulte Conectividade.

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

  1. Configure a conexão com o armazém.
  2. Acesse a caixa de diálogo de configurações do Databricks. Caixa de diálogo de configurações do Databricks no Power BI.
  3. Na caixa de texto " tagsde consulta" , insira tags de consulta usando a sintaxe do parâmetro de configuração da sessão.
  4. Clique em OK .
nota

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

Tags de query automáticas​

As tags de query automática anexam automaticamente metadados de contexto do Power BI a queries enviadas para warehouse do Databricks. A partir da versão de julho de 2026 do serviço Power BI, as tags de query automática são ativadas automaticamente — nenhuma configuração é necessária para ativá-las. As tags de query automática estão disponíveis apenas ao usar o Driver Arrow Database Connectivity (ADBC). Eles não são suportados com o Driver ODBC.

O Power BI anexa automaticamente as seguintes tags reservadas (prefixadas com @@) a queries. As tags disponíveis dependem do modo de conexão do Power BI:

keyde etiqueta

Consulta direta

Importar

@@powerbi_activity_id

Sim

Sim

@@powerbi_customer_tenant_id

Sim

Sim

@@powerbi_workspace_id

Sim

Sim

@@powerbi_dataset_id

Sim

Não

@@powerbi_report_id

Sim

Não

@@powerbi_visual_id

Sim

Não

keyde etiqueta

Consulta direta

Importar

@@powerbi_activity_id

Sim

Sim

@@powerbi_customer_tenant_id

Sim

Sim

@@powerbi_workspace_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.

Desativar tags de query automáticas​

As tags de query automáticas estão ativadas por default. Para desativá-las, modifique a query M no Power Query Editor para incluir EnableAutoQueryTags="false" nas opções de chamada do conector.

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​

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

  1. Configure a conexão com o armazém.
  2. Navegue até a tab SQLInicial .
  3. Insira as tags de consulta usando o comando SET QUERY_TAGS. Você pode incluir parâmetros Tableau na key ou no valor.
  4. 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={"team": "engineering", "dashboard": "abc123"}
        )
        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.

  • As query tags são suportadas em warehouses do Databricks SQL e no compute do Lakehouse Real-Time (Lakehouse//RT). A coluna query_tags não é preenchida para outros tipos de 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.

Nesta página