Query tags

Query tags help you trace Hightouch-initiated queries in your warehouse's query history. Use them to attribute compute usage to specific syncs or audiences, debug slow queries, and monitor query patterns across your workspace.

What you'll learn

• How query tags work and which warehouses support them
• Which tags are available
• How to enable query tags
• How to read tags in your warehouse's query history
• How to build usage attribution reports

Overview

Query tags are metadata labels that Hightouch can attach to the queries it runs against your warehouse. Each tag identifies the Hightouch resource — workspace, sync, model, audience, or destination — that triggered the query.

Tags appear in your warehouse's query history alongside runtime data, so you can break query activity down by the sync, audience, or model that triggered it.

Query tags are available on Databricks, Snowflake, and BigQuery. On Databricks and Snowflake, Hightouch sets them at the session level. On BigQuery, Hightouch writes them as job labels on query jobs.

Not all queries carry the full set of tags. Operations that aren't tied to a specific sync — such as column suggestion refreshes and schema previews — carry workspace-level tags like source and hightouch_workspace_id, but not sync-specific tags like hightouch_sync_id.

Available tags

Hightouch can attach the following tags to warehouse queries:

Not all tags are present on every query. Tags that don't apply to a given operation are omitted.

Enable query tags

Query tags are enabled per workspace by Hightouch. Contact Hightouch support or your account team to enable them and choose which tag keys you want active.

There is no customer-side configuration required in the warehouse. Once enabled, tags are applied automatically to all Hightouch-initiated queries in the workspace.

Access query tags in your warehouse

How you read query tags depends on your warehouse.

Databricks

Query tags are available in the system.query.history table in the query_tags column. Use bracket notation to extract a specific tag:

SELECT
  query_tags['source'] AS source,
  query_tags['hightouch_workspace_id'] AS workspace_id,
  query_tags['hightouch_sync_id'] AS sync_id,
  query_tags['hightouch_audience_id'] AS audience_id,
  total_task_duration_ms,
  start_time
FROM system.query.history
WHERE query_tags['hightouch_workspace_id'] IS NOT NULL
ORDER BY start_time DESC;

Snowflake

Query tags are stored as a JSON string in the QUERY_TAG column of the SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY view. Parse the JSON to extract individual tags:

SELECT
  PARSE_JSON(query_tag):source::STRING AS source,
  PARSE_JSON(query_tag):hightouch_workspace_id::STRING AS workspace_id,
  PARSE_JSON(query_tag):hightouch_sync_id::STRING AS sync_id,
  PARSE_JSON(query_tag):hightouch_audience_id::STRING AS audience_id,
  total_elapsed_time,
  start_time
FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
WHERE query_tag IS NOT NULL
  AND TRY_PARSE_JSON(query_tag):hightouch_workspace_id IS NOT NULL
ORDER BY start_time DESC;

BigQuery

On BigQuery, Hightouch writes query tags as job labels. Read them from the INFORMATION_SCHEMA.JOBS view. Replace REGION_NAME with the region where your BigQuery jobs run:

SELECT
  job_id,
  creation_time,
  total_bytes_processed,
  total_slot_ms,
  (SELECT value FROM UNNEST(labels) WHERE key = 'source') AS source,
  (SELECT value FROM UNNEST(labels) WHERE key = 'hightouch_workspace_id') AS workspace_id,
  (SELECT value FROM UNNEST(labels) WHERE key = 'hightouch_sync_id') AS sync_id,
  (SELECT value FROM UNNEST(labels) WHERE key = 'hightouch_audience_id') AS audience_id
FROM `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS
WHERE EXISTS (SELECT 1 FROM UNNEST(labels) WHERE key = 'hightouch_workspace_id')
ORDER BY creation_time DESC;

Attribute warehouse usage

Use query tags to attribute warehouse compute usage to specific syncs, audiences, or destinations. The general pattern is to group your warehouse's query history by the Hightouch tag that matches the dimension you care about. For background on what drives warehouse compute in Hightouch, see Manage warehouse compute.

Group usage by sync

This Databricks example groups total runtime by sync_id:

SELECT
  query_tags['hightouch_sync_id'] AS sync_id,
  COUNT(*) AS query_count,
  SUM(total_task_duration_ms) AS total_runtime_ms
FROM system.query.history
WHERE query_tags['hightouch_sync_id'] IS NOT NULL
GROUP BY query_tags['hightouch_sync_id']
ORDER BY total_runtime_ms DESC;

Group usage by audience

To see which audiences drive the most compute, group by hightouch_audience_id. This Snowflake example groups total runtime by audience_id:

SELECT
  PARSE_JSON(query_tag):hightouch_audience_id::STRING AS audience_id,
  COUNT(*) AS query_count,
  SUM(total_elapsed_time) AS total_runtime_ms
FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
WHERE TRY_PARSE_JSON(query_tag):hightouch_audience_id IS NOT NULL
GROUP BY 1
ORDER BY total_runtime_ms DESC;

Considerations

Untagged queries are shared overhead. Queries for column suggestions and schema previews don't carry sync-specific tags. Exclude them from per-sync reports or categorize them as shared usage.

Tags reflect current state. If you rename or reconfigure a sync, the sync_id stays the same, but any metadata you've mapped to it (such as team name or business unit) may need updating.

Enablement is workspace-scoped. Tags are enabled for all Hightouch-initiated queries in a workspace. You can't enable them for individual syncs, but you can control which tag keys are active.