[{"data":1,"prerenderedAt":907},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fapi\u002Fsql-logs":3},{"id":4,"title":5,"body":6,"description":898,"extension":899,"meta":900,"navigation":901,"path":902,"redirect":903,"seo":904,"stem":905,"__hash__":906},"docs\u002Fdocs\u002Fapi\u002Fsql-logs.md","SQL Logs API Workflows",{"type":7,"value":8,"toc":886},"minimark",[9,13,17,39,44,47,67,70,97,101,104,107,147,150,183,186,194,199,388,391,421,425,428,476,479,498,502,505,598,601,605,611,613,663,666,708,712,717,719,784,787,811,817,819,844,848,851,854,858,882],[10,11,5],"h1",{"id":12},"sql-logs-api-workflows",[14,15,16],"p",{},"Use this page when you need live SQL visibility for stream execution, Data Explorer, SQL Console, file queries, or federated queries.",[14,18,19,20,24,25,28,29,32,33,38],{},"The current backend sends SQL logs over ",[21,22,23],"code",{},"GET \u002Fapi\u002Fv1\u002Flogs\u002Fstream",", and uses ",[21,26,27],{},"GET"," or ",[21,30,31],{},"PUT \u002Fapi\u002Fv1\u002Fsystem\u002Fsql-logging"," for capture-mode control. Use SQL logs to debug performance issues, validate generated queries, and understand how the system interacts with your data sources. For stream status, persisted stream logs, and run history, see ",[34,35,37],"a",{"href":36},"\u002Fdocs\u002Fapi\u002Flogs-and-monitoring","Logs And Monitoring API Workflows",".",[40,41,43],"h2",{"id":42},"route-model","Route model",[14,45,46],{},"SQL logs currently use these routes:",[48,49,50,56,62],"ul",{},[51,52,53,55],"li",{},[21,54,23],{}," for live SQL log delivery over SSE",[51,57,58,61],{},[21,59,60],{},"GET \u002Fapi\u002Fv1\u002Fsystem\u002Fsql-logging"," to read the current SQL capture mode",[51,63,64,66],{},[21,65,31],{}," to change the current SQL capture mode",[14,68,69],{},"Authentication:",[48,71,72,78,84,94],{},[51,73,74,77],{},[21,75,76],{},"\u002Flogs\u002Fstream"," is currently exposed as a public SSE route",[51,79,80,83],{},[21,81,82],{},"\u002Fsystem\u002Fsql-logging"," uses the IDE auth path",[51,85,86,87,90,91],{},"for API usage outside desktop localhost mode, send ",[21,88,89],{},"X-API-Key"," and ",[21,92,93],{},"X-Install-ID",[51,95,96],{},"in desktop mode on localhost, IDE routes can also work without an API key",[40,98,100],{"id":99},"read-live-sql-logs","Read live SQL logs",[14,102,103],{},"Use the shared SSE stream when you need immediate visibility into SQL generated by stream workers, Data Explorer, SQL Console, file queries, or federated queries.",[14,105,106],{},"The live stream distinguishes payload families with SSE event names:",[108,109,110,123],"table",{},[111,112,113],"thead",{},[114,115,116,120],"tr",{},[117,118,119],"th",{},"Event name",[117,121,122],{},"Purpose",[124,125,126,137],"tbody",{},[114,127,128,134],{},[129,130,131],"td",{},[21,132,133],{},"sql",[129,135,136],{},"SQL log payloads",[114,138,139,144],{},[129,140,141],{},[21,142,143],{},"log",[129,145,146],{},"Structured monitoring logs on the same stream",[14,148,149],{},"Example:",[151,152,157],"pre",{"className":153,"code":154,"language":155,"meta":156,"style":156},"language-bash shiki shiki-themes github-light github-dark","curl -N \"$API_URL\u002Flogs\u002Fstream\"\n","bash","",[21,158,159],{"__ignoreMap":156},[160,161,164,168,172,176,180],"span",{"class":162,"line":163},"line",1,[160,165,167],{"class":166},"sScJk","curl",[160,169,171],{"class":170},"sj4cs"," -N",[160,173,175],{"class":174},"sZZnC"," \"",[160,177,179],{"class":178},"sVt8B","$API_URL",[160,181,182],{"class":174},"\u002Flogs\u002Fstream\"\n",[14,184,185],{},"Example SQL log payload:",[151,187,192],{"className":188,"code":190,"language":191,"meta":156},[189],"language-text","event: sql\ndata: {\"id\":\"sql_123\",\"connectionId\":\"conn_postgres_prod\",\"database\":\"postgres\",\"schema\":\"public\",\"tableName\":\"actor\",\"query\":\"SELECT * FROM public.actor LIMIT 100\",\"purpose\":\"DATA_QUERY\",\"startedAt\":\"2026-03-20T09:41:31.000Z\",\"durationMs\":18,\"rowCount\":100}\n","text",[21,193,190],{"__ignoreMap":156},[195,196,198],"h3",{"id":197},"sql-log-fields","SQL log fields",[108,200,201,214],{},[111,202,203],{},[114,204,205,208,211],{},[117,206,207],{},"Field",[117,209,210],{},"Type",[117,212,213],{},"Description",[124,215,216,229,241,253,265,277,289,301,314,326,338,351,363,375],{},[114,217,218,223,226],{},[129,219,220],{},[21,221,222],{},"id",[129,224,225],{},"string",[129,227,228],{},"Unique log entry identifier",[114,230,231,236,238],{},[129,232,233],{},[21,234,235],{},"connectionId",[129,237,225],{},[129,239,240],{},"Connection that produced the query",[114,242,243,248,250],{},[129,244,245],{},[21,246,247],{},"tabId",[129,249,225],{},[129,251,252],{},"UI tab context (omitted for non-UI queries)",[114,254,255,260,262],{},[129,256,257],{},[21,258,259],{},"database",[129,261,225],{},[129,263,264],{},"Database name",[114,266,267,272,274],{},[129,268,269],{},[21,270,271],{},"schema",[129,273,225],{},[129,275,276],{},"Schema name (omitted when not applicable)",[114,278,279,284,286],{},[129,280,281],{},[21,282,283],{},"tableName",[129,285,225],{},[129,287,288],{},"Table being queried (omitted when not applicable)",[114,290,291,296,298],{},[129,292,293],{},[21,294,295],{},"query",[129,297,225],{},[129,299,300],{},"SQL text (truncated to 100 KB)",[114,302,303,308,311],{},[129,304,305],{},[21,306,307],{},"params",[129,309,310],{},"array",[129,312,313],{},"Query parameters (omitted when empty)",[114,315,316,321,323],{},[129,317,318],{},[21,319,320],{},"purpose",[129,322,225],{},[129,324,325],{},"Why the query was executed (see purpose values below)",[114,327,328,333,335],{},[129,329,330],{},[21,331,332],{},"startedAt",[129,334,225],{},[129,336,337],{},"ISO 8601 timestamp with milliseconds",[114,339,340,345,348],{},[129,341,342],{},[21,343,344],{},"durationMs",[129,346,347],{},"number",[129,349,350],{},"Execution time in milliseconds",[114,352,353,358,360],{},[129,354,355],{},[21,356,357],{},"rowCount",[129,359,347],{},[129,361,362],{},"Rows returned or affected",[114,364,365,370,372],{},[129,366,367],{},[21,368,369],{},"error",[129,371,225],{},[129,373,374],{},"Error message (present only on failure)",[114,376,377,382,385],{},[129,378,379],{},[21,380,381],{},"redacted",[129,383,384],{},"boolean",[129,386,387],{},"Privacy flag (present only when query was redacted)",[14,389,390],{},"Verification:",[48,392,393,400,418],{},[51,394,395,396,399],{},"confirm SQL payloads arrive as ",[21,397,398],{},"event: sql"," SSE frames",[51,401,402,403,405,406,405,408,405,410,405,412,414,415,417],{},"confirm fields such as ",[21,404,235],{},", ",[21,407,295],{},[21,409,320],{},[21,411,332],{},[21,413,344],{},", and ",[21,416,357],{}," are present",[51,419,420],{},"trigger one known stream, explorer, or console action and verify the expected purpose appears",[40,422,424],{"id":423},"what-currently-emits-sql-logs","What currently emits SQL logs",[14,426,427],{},"Current backend coverage includes:",[48,429,430,439,445,451,457,468,473],{},[51,431,432,433,90,436],{},"stream reader or writer SQL operations, especially ",[21,434,435],{},"SCHEMA_CHANGE",[21,437,438],{},"DML_OPERATION",[51,440,441,442],{},"database metadata loading and object inspection as ",[21,443,444],{},"SCHEMA_INTROSPECTION",[51,446,447,448],{},"table or view preview reads as ",[21,449,450],{},"DATA_QUERY",[51,452,453,454],{},"exact row counts as ",[21,455,456],{},"COUNT_QUERY",[51,458,459,460,405,462,405,464,414,466],{},"SQL Console statements classified from the SQL itself, including ",[21,461,450],{},[21,463,456],{},[21,465,435],{},[21,467,438],{},[51,469,470,471],{},"database row inserts, updates, and deletes as ",[21,472,438],{},[51,474,475],{},"file metadata, file preview, file count, file console, and federated console queries as live SQL log events",[14,477,478],{},"Current gaps:",[48,480,481,487,492],{},[51,482,483,486],{},[21,484,485],{},"\u002Ffiles\u002Fsummary"," does not currently emit a separate SQL log event",[51,488,489,486],{},[21,490,491],{},"\u002Ffiles\u002Fcsv\u002Fsniff",[51,493,494,497],{},[21,495,496],{},"GET \u002Fapi\u002Fv1\u002Fstreams\u002F{id}\u002Flogs"," is a persisted stream-run log route, not a live SQL log feed",[40,499,501],{"id":500},"purpose-values-you-will-see","Purpose values you will see",[14,503,504],{},"SQL purpose values in the current backend:",[108,506,507,515],{},[111,508,509],{},[114,510,511,513],{},[117,512,122],{},[117,514,213],{},[124,516,517,526,538,547,566,575,588],{},[114,518,519,523],{},[129,520,521],{},[21,522,444],{},[129,524,525],{},"Metadata discovery and object inspection",[114,527,528,532],{},[129,529,530],{},[21,531,450],{},[129,533,534,535],{},"Preview reads, filtered reads, and general ",[21,536,537],{},"SELECT",[114,539,540,544],{},[129,541,542],{},[21,543,456],{},[129,545,546],{},"Exact row count requests",[114,548,549,553],{},[129,550,551],{},[21,552,435],{},[129,554,555,556,405,559,562,563],{},"DDL such as ",[21,557,558],{},"CREATE",[21,560,561],{},"ALTER",", or ",[21,564,565],{},"DROP",[114,567,568,572],{},[129,569,570],{},[21,571,438],{},[129,573,574],{},"Inserts, updates, and deletes",[114,576,577,582],{},[129,578,579],{},[21,580,581],{},"PLAN_ANALYSIS",[129,583,584,587],{},[21,585,586],{},"EXPLAIN"," \u002F query plan inspection",[114,589,590,595],{},[129,591,592],{},[21,593,594],{},"UTILITY",[129,596,597],{},"Connectivity probes, health checks, and unclassified queries",[14,599,600],{},"These values are classified from the executed SQL or set explicitly by the backend for stream, explorer, and file operations.",[40,602,604],{"id":603},"read-the-current-sql-capture-mode","Read the current SQL capture mode",[14,606,607,608,610],{},"Use ",[21,609,60],{}," when you need to know how much SQL logging the backend is currently emitting.",[14,612,149],{},[151,614,616],{"className":153,"code":615,"language":155,"meta":156,"style":156},"curl \"$API_URL\u002Fsystem\u002Fsql-logging\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -H \"X-Install-ID: $INSTALL_ID\"\n",[21,617,618,632,649],{"__ignoreMap":156},[160,619,620,622,624,626,629],{"class":162,"line":163},[160,621,167],{"class":166},[160,623,175],{"class":174},[160,625,179],{"class":178},[160,627,628],{"class":174},"\u002Fsystem\u002Fsql-logging\"",[160,630,631],{"class":170}," \\\n",[160,633,635,638,641,644,647],{"class":162,"line":634},2,[160,636,637],{"class":170},"  -H",[160,639,640],{"class":174}," \"X-API-Key: ",[160,642,643],{"class":178},"$API_KEY",[160,645,646],{"class":174},"\"",[160,648,631],{"class":170},[160,650,652,654,657,660],{"class":162,"line":651},3,[160,653,637],{"class":170},[160,655,656],{"class":174}," \"X-Install-ID: ",[160,658,659],{"class":178},"$INSTALL_ID",[160,661,662],{"class":174},"\"\n",[14,664,665],{},"Example response:",[151,667,671],{"className":668,"code":669,"language":670,"meta":156,"style":156},"language-json shiki shiki-themes github-light github-dark","{\n  \"sqlCaptureMode\": \"minimal\",\n  \"forwardSQLLogs\": true\n}\n","json",[21,672,673,678,692,702],{"__ignoreMap":156},[160,674,675],{"class":162,"line":163},[160,676,677],{"class":178},"{\n",[160,679,680,683,686,689],{"class":162,"line":634},[160,681,682],{"class":170},"  \"sqlCaptureMode\"",[160,684,685],{"class":178},": ",[160,687,688],{"class":174},"\"minimal\"",[160,690,691],{"class":178},",\n",[160,693,694,697,699],{"class":162,"line":651},[160,695,696],{"class":170},"  \"forwardSQLLogs\"",[160,698,685],{"class":178},[160,700,701],{"class":170},"true\n",[160,703,705],{"class":162,"line":704},4,[160,706,707],{"class":178},"}\n",[40,709,711],{"id":710},"change-the-sql-capture-mode","Change the SQL capture mode",[14,713,607,714,716],{},[21,715,31],{}," when you need to reduce noise or turn on broader SQL visibility.",[14,718,149],{},[151,720,722],{"className":153,"code":721,"language":155,"meta":156,"style":156},"curl -X PUT \"$API_URL\u002Fsystem\u002Fsql-logging\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -H \"X-Install-ID: $INSTALL_ID\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"sqlCaptureMode\":\"verbose\"}'\n",[21,723,724,742,754,766,775],{"__ignoreMap":156},[160,725,726,728,731,734,736,738,740],{"class":162,"line":163},[160,727,167],{"class":166},[160,729,730],{"class":170}," -X",[160,732,733],{"class":174}," PUT",[160,735,175],{"class":174},[160,737,179],{"class":178},[160,739,628],{"class":174},[160,741,631],{"class":170},[160,743,744,746,748,750,752],{"class":162,"line":634},[160,745,637],{"class":170},[160,747,640],{"class":174},[160,749,643],{"class":178},[160,751,646],{"class":174},[160,753,631],{"class":170},[160,755,756,758,760,762,764],{"class":162,"line":651},[160,757,637],{"class":170},[160,759,656],{"class":174},[160,761,659],{"class":178},[160,763,646],{"class":174},[160,765,631],{"class":170},[160,767,768,770,773],{"class":162,"line":704},[160,769,637],{"class":170},[160,771,772],{"class":174}," \"Content-Type: application\u002Fjson\"",[160,774,631],{"class":170},[160,776,778,781],{"class":162,"line":777},5,[160,779,780],{"class":170},"  -d",[160,782,783],{"class":174}," '{\"sqlCaptureMode\":\"verbose\"}'\n",[14,785,786],{},"Current mode behavior from backend source:",[48,788,789,795,805],{},[51,790,791,794],{},[21,792,793],{},"off"," disables SQL log emission",[51,796,797,800,801,90,803],{},[21,798,799],{},"minimal"," keeps SQL errors plus ",[21,802,435],{},[21,804,438],{},[51,806,807,810],{},[21,808,809],{},"verbose"," emits all SQL purposes for both stream SQL and IDE SQL activity",[14,812,813,816],{},[21,814,815],{},"forwardSQLLogs"," is derived automatically from the selected mode.",[14,818,390],{},[48,820,821,828,837],{},[51,822,823,824,827],{},"call ",[21,825,826],{},"GET \u002Fsystem\u002Fsql-logging"," before and after the update",[51,829,830,831,833,834,836],{},"in ",[21,832,799],{},", confirm ordinary preview ",[21,835,450],{}," events stop appearing while SQL errors still appear",[51,838,830,839,841,842],{},[21,840,809],{},", confirm preview and metadata events appear again on ",[21,843,76],{},[40,845,847],{"id":846},"api-vs-ui","API vs UI",[14,849,850],{},"Use the UI Logs view for interactive inspection during stream runs, Data Explorer work, and SQL Console work.",[14,852,853],{},"Use the API when you need to stream SQL activity into external tooling, confirm which backend queries a workflow generates during either streaming or interactive work, or change runtime SQL logging behavior programmatically.",[40,855,857],{"id":856},"related-docs","Related docs",[48,859,860,864,870,876],{},[51,861,862],{},[34,863,37],{"href":36},[51,865,866],{},[34,867,869],{"href":868},"\u002Fdocs\u002Foperations\u002Fobservability","Observability",[51,871,872],{},[34,873,875],{"href":874},"\u002Fdocs\u002Fapi\u002Ffederated-queries","Federated Queries",[51,877,878],{},[34,879,881],{"href":880},"\u002Fdocs\u002Fapi\u002Ffiles-and-storage","Working with Files and S3",[883,884,885],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":156,"searchDepth":634,"depth":634,"links":887},[888,889,892,893,894,895,896,897],{"id":42,"depth":634,"text":43},{"id":99,"depth":634,"text":100,"children":890},[891],{"id":197,"depth":651,"text":198},{"id":423,"depth":634,"text":424},{"id":500,"depth":634,"text":501},{"id":603,"depth":634,"text":604},{"id":710,"depth":634,"text":711},{"id":846,"depth":634,"text":847},{"id":856,"depth":634,"text":857},"Inspect live SQL logs from streams, Data Explorer, SQL Console, files, and federated queries, and control SQL capture mode in DBConvert Streams.","md",{},false,"\u002Fdocs\u002Fapi\u002Fsql-logs",null,{"title":5,"description":898},"docs\u002Fapi\u002Fsql-logs","YZ0aR6W7-1E3y4GvsBWZHV7qAkoascQujnZ8iOBNM80",1783896284451]