Query tags

Query tags help you trace Hightouch-initiated queries in your warehouse's query history. Use them to attribute compute costs 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 cost 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 cost and runtime data. You can use them to attribute compute costs to specific syncs or audiences, debug slow or failed queries, and monitor query patterns across your workspace.

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 Hightouch operations carry tags. Operations that aren't tied to a specific sync — such as column suggestion refreshes, schema previews, and sync log writes — appear in query history without tags.

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['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_sync_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):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_sync_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 = '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_sync_id')
ORDER BY creation_time DESC;

Attribute warehouse costs

Use query tags to attribute warehouse compute costs to specific syncs, audiences, or teams. 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 cost 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;

For more granular attribution — for example, mapping sync IDs to team names, audiences, or business units — you can join query history with a lookup table that maps Hightouch IDs to your internal taxonomy.

Group cost by audience

To see which audiences drive the most compute, group by hightouch_audience_id:

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

Considerations

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

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.