Adding comments to SQL text allows you to filter by and group-by custom properties in Queries tagged with the - Tagging Specification will automatically be detected by

Follow the below steps to manually add annotations to any query. For example within BI tools or to update SQL strings manually via your ETL workflow system.


Three Ways to Generate Query Annotations

  1. API
  2. Web-based tool
  3. Python SDK 



Generating Annotations via "api_annotate" API endpoint

The following API responds with a tag.

The endpoint accepts up to 5 parameters. Here is a usage example:

curl -S -XPOST ""


"annotation": "/* INTERMIX_ID: eyJkYWciOiAiZGFnMSIsICJ2ZXJzaW9uIjogIjEiLCAiYXBwX3ZlciI6ICIxLjEiLCAidXNlciI6ICJ1c2VyMSIsICJmb3JtYXQiOiAiaW50ZXJtaXgiLCAiY2hhcnRfbmFtZSI6ICIiLCAiYXBwIjogImFwcDEiLCAibWV0YSI6IHt9LCAiYXQiOiAiIiwgInRhc2siOiAidGFzazEifQ== */",
"request": "/api/api_annotate?app=app1&app_ver=1.1&dag=dag1&task=task1&user=user1"

Generating Annotations via Web Tool

  1. Log into and go to 'Organization Settings' -> 'App Tracing'
  2. Enter the values that identify your SQL query and hit 'Create'.
  3. Paste the annotation string to the top of your SQL query.



Generating Annotations with Python SDK

See this article for instructions on using the Python SDK.