[{"data":1,"prerenderedAt":2050},["ShallowReactive",2],{"\u002Ffeatures\u002Ftraces\u002Fquerying-spans-navigation":3,"\u002Ffeatures\u002Ftraces\u002Fquerying-spans":116},[4,8,28,38,52,56,60,70,74,78,82,86,90,94,98],{"title":5,"path":6,"stem":7},"Get started","\u002Ffeatures","features\u002Findex",{"title":9,"closed":10,"path":11,"stem":12,"children":13,"page":-1},"Traces",true,"\u002Ffeatures\u002Ftraces","features\u002F01.traces\u002Findex",[14,16,20,24],{"title":15,"path":11,"stem":12},"Introduction",{"title":17,"path":18,"stem":19},"Grouping & systems","\u002Ffeatures\u002Ftraces\u002Fgrouping","features\u002F01.traces\u002Fgrouping",{"title":21,"path":22,"stem":23},"Querying spans","\u002Ffeatures\u002Ftraces\u002Fquerying-spans","features\u002F01.traces\u002Fquerying-spans",{"title":25,"path":26,"stem":27},"Querying traces","\u002Ffeatures\u002Ftraces\u002Fquerying-traces","features\u002F01.traces\u002Fquerying-traces",{"title":29,"closed":10,"path":30,"stem":31,"children":32,"page":-1},"Logs","\u002Ffeatures\u002Flogs","features\u002F02.logs\u002Findex",[33,34],{"title":15,"path":30,"stem":31},{"title":35,"path":36,"stem":37},"Grouping rules","\u002Ffeatures\u002Flogs\u002Fgrouping","features\u002F02.logs\u002Fgrouping",{"title":39,"closed":10,"path":40,"stem":41,"children":42,"page":-1},"Metrics","\u002Ffeatures\u002Fmetrics","features\u002F03.metrics\u002Findex",[43,44,48],{"title":15,"path":40,"stem":41},{"title":45,"path":46,"stem":47},"Querying","\u002Ffeatures\u002Fmetrics\u002Fquerying","features\u002F03.metrics\u002F02.querying",{"title":49,"path":50,"stem":51},"PromQL compat","\u002Ffeatures\u002Fmetrics\u002Fpromql-compat","features\u002F03.metrics\u002F03.promql-compat",{"title":53,"path":54,"stem":55},"Alerts and Notifications","\u002Ffeatures\u002Falerting","features\u002F04.alerting",{"title":57,"path":58,"stem":59},"Chart annotations","\u002Ffeatures\u002Fannotations","features\u002F05.annotations",{"title":61,"path":62,"stem":63,"children":64,"closed":10},"Dashboards","\u002Ffeatures\u002Fdashboards","features\u002F06.dashboards\u002F1.index",[65,66],{"title":61,"path":62,"stem":63},{"title":67,"path":68,"stem":69},"YAML Templates","\u002Ffeatures\u002Fdashboards\u002Fyaml","features\u002F06.dashboards\u002F2.yaml",{"title":71,"path":72,"stem":73},"Transformations","\u002Ffeatures\u002Ftransformations","features\u002F07.transformations",{"title":75,"path":76,"stem":77},"Service graph","\u002Ffeatures\u002Fservice-graph","features\u002F08.service-graph",{"title":79,"path":80,"stem":81},"Grafana integration","\u002Ffeatures\u002Fgrafana","features\u002F09.grafana",{"title":83,"path":84,"stem":85},"Data fixtures","\u002Ffeatures\u002Ffixtures","features\u002F10.fixtures",{"title":87,"path":88,"stem":89},"JavaScript Source Maps","\u002Ffeatures\u002Fsourcemaps","features\u002F11.sourcemaps",{"title":91,"path":92,"stem":93},"MCP Server","\u002Ffeatures\u002Fmcp","features\u002F12.mcp",{"title":95,"path":96,"stem":97},"Searching","\u002Ffeatures\u002Fsearching","features\u002F4.searching",{"title":99,"closed":10,"path":100,"stem":101,"children":102,"page":115},"SSO","\u002Ffeatures\u002Fsso","features\u002Fsso",[103,107,111],{"title":104,"path":105,"stem":106},"Google","\u002Ffeatures\u002Fsso\u002Fgoogle","features\u002Fsso\u002F1.google",{"title":108,"path":109,"stem":110},"Okta","\u002Ffeatures\u002Fsso\u002Fokta","features\u002Fsso\u002F2.okta",{"title":112,"path":113,"stem":114},"Keycloak","\u002Ffeatures\u002Fsso\u002Fkeycloak","features\u002Fsso\u002F3.keycloak",false,{"page":117,"surround":2045},{"id":118,"title":21,"body":119,"description":2034,"extension":2035,"image":2036,"meta":2037,"navigation":10,"path":22,"seo":2043,"stem":23,"surround_disabled":115,"__hash__":2044},"features\u002Ffeatures\u002F01.traces\u002Fquerying-spans.md",{"type":120,"value":121,"toc":1996},"minimark",[122,139,146,151,154,179,191,195,200,214,221,226,229,359,363,366,406,410,413,510,514,517,544,547,560,566,570,573,635,638,658,662,665,704,708,712,719,824,828,869,873,879,905,907,914,930,936,940,946,1021,1032,1036,1040,1043,1227,1231,1240,1254,1258,1261,1287,1291,1294,1510,1514,1517,1599,1603,1606,1610,1636,1639,1643,1679,1682,1686,1708,1711,1716,1720,1723,1727,1735,1739,1754,1758,1776,1780,1800,1804,1824,1828,1832,1877,1881,1922,1926,1967,1971,1992],[123,124,125,126,130,131,134,135,138],"p",{},"Uptrace provides a powerful querying language that enables you to filter, group, and aggregate your observability data effectively. The query language supports filters (",[127,128,129],"code",{},"where _status_code = \"error\"","), grouping (",[127,132,133],{},"group by _group_id","), and aggregates (",[127,136,137],{},"p50(_dur_ms)",").",[123,140,141],{},[142,143],"img",{"alt":144,"src":145},"Filters","\u002Ffeatures\u002Fquerying-spans\u002Ffiltering.png",[147,148,150],"h2",{"id":149},"prerequisites-for-effective-querying","Prerequisites for Effective Querying",[123,152,153],{},"To write useful and performant queries, you need to pre-process raw data to ensure it has a well-defined structure. You can achieve this by:",[155,156,157,171],"ul",{},[158,159,160,161,166,167],"li",{},"Recording contextual information in span ",[162,163,165],"a",{"href":164},"\u002Fopentelemetry\u002Fdistributed-tracing#attributes","attributes"," and ",[162,168,170],{"href":169},"\u002Fopentelemetry\u002Fdistributed-tracing#events","events",[158,172,173,174,178],{},"Using ",[162,175,177],{"href":176},"\u002Fglossary\u002Fstructured-logging","structured logging"," for logs",[123,180,181,182,186,187,190],{},"For ",[183,184,185],"em",{},"searching"," over spans and logs (as opposed to complex querying), Uptrace supports a more concise syntax described in the ",[162,188,189],{"href":96},"searching documentation",".",[147,192,194],{"id":193},"query-language-components","Query Language Components",[196,197,199],"h3",{"id":198},"identifiers","Identifiers",[123,201,202,203,206,207,210,211,190],{},"Identifiers are unquoted strings that reference span fields, attributes, and extract values from JSON. Examples include ",[127,204,205],{},"_name",", ",[127,208,209],{},"_display_name",", and ",[127,212,213],{},"_dur_ms",[123,215,216,220],{},[217,218,219],"strong",{},"Important:"," Span fields start with an underscore to distinguish them from attributes.",[222,223,225],"h4",{"id":224},"built-in-span-fields","Built-in Span Fields",[123,227,228],{},"The following table lists all built-in span fields available for querying:",[230,231,232,245],"table",{},[233,234,235],"thead",{},[236,237,238,242],"tr",{},[239,240,241],"th",{},"Span Field",[239,243,244],{},"Description",[246,247,248,259,269,279,288,298,310,320,329,339,349],"tbody",{},[236,249,250,256],{},[251,252,253],"td",{},[127,254,255],{},"_id",[251,257,258],{},"Unique span identifier",[236,260,261,266],{},[251,262,263],{},[127,264,265],{},"_parent_id",[251,267,268],{},"Parent span identifier",[236,270,271,276],{},[251,272,273],{},[127,274,275],{},"_trace_id",[251,277,278],{},"Trace identifier",[236,280,281,285],{},[251,282,283],{},[127,284,205],{},[251,286,287],{},"Span operation name (used for grouping)",[236,289,290,295],{},[251,291,292],{},[127,293,294],{},"_event_name",[251,296,297],{},"Event name (for span events)",[236,299,300,304],{},[251,301,302],{},[127,303,209],{},[251,305,306,307,309],{},"Display name when ",[127,308,205],{}," is not enough.",[236,311,312,317],{},[251,313,314],{},[127,315,316],{},"_kind",[251,318,319],{},"Span kind (client, server, etc.)",[236,321,322,326],{},[251,323,324],{},[127,325,213],{},[251,327,328],{},"Span duration in milliseconds (float64)",[236,330,331,336],{},[251,332,333],{},[127,334,335],{},"_time",[251,337,338],{},"Span start time (microseconds accuracy)",[236,340,341,346],{},[251,342,343],{},[127,344,345],{},"_status_code",[251,347,348],{},"Span status code (ok, error, unset)",[236,350,351,356],{},[251,352,353],{},[127,354,355],{},"_status_message",[251,357,358],{},"Span status message",[222,360,362],{"id":361},"attribute-names","Attribute Names",[123,364,365],{},"Attribute names are normalized by replacing dots with underscores. Common examples include:",[230,367,368,377],{},[233,369,370],{},[236,371,372,375],{},[239,373,374],{},"Attribute Name",[239,376,244],{},[246,378,379,393],{},[236,380,381,386],{},[251,382,383],{},[127,384,385],{},"display_name",[251,387,388,392],{},[162,389,391],{"href":390},"grouping#display-name","display.name"," attribute",[236,394,395,400],{},[251,396,397],{},[127,398,399],{},"service_name",[251,401,402,403,392],{},"OpenTelemetry ",[127,404,405],{},"service.name",[196,407,409],{"id":408},"data-types","Data Types",[123,411,412],{},"Uptrace supports the following attribute types, each with specific comparison operators:",[230,414,415,425],{},[233,416,417],{},[236,418,419,422],{},[239,420,421],{},"Attribute Type",[239,423,424],{},"Supported Comparison Operators",[246,426,427,455,483,497],{},[236,428,429,434],{},[251,430,431],{},[127,432,433],{},"str",[251,435,436,206,439,206,442,206,445,206,448,451,452],{},[127,437,438],{},"=",[127,440,441],{},"in",[127,443,444],{},"like",[127,446,447],{},"contains",[127,449,450],{},"~"," (regexp), ",[127,453,454],{},"exists",[236,456,457,465],{},[251,458,459,166,462],{},[127,460,461],{},"int",[127,463,464],{},"float",[251,466,467,206,469,206,472,206,475,206,478,206,481],{},[127,468,438],{},[127,470,471],{},"\u003C",[127,473,474],{},"\u003C=",[127,476,477],{},">",[127,479,480],{},">=",[127,482,454],{},[236,484,485,490],{},[251,486,487],{},[127,488,489],{},"bool",[251,491,492,206,494],{},[127,493,438],{},[127,495,496],{},"!=",[236,498,499,504],{},[251,500,501],{},[127,502,503],{},"[]str",[251,505,506,206,508],{},[127,507,447],{},[127,509,454],{},[222,511,513],{"id":512},"type-specification","Type Specification",[123,515,516],{},"While type discovery is automatic, you can explicitly specify types when needed:",[518,519,524],"pre",{"className":520,"code":521,"language":522,"meta":523,"style":523},"language-sql shiki shiki-themes github-light","foo::string | bar::int | baz::float\n","sql","",[127,525,526],{"__ignoreMap":523},[527,528,531,535,538,541],"span",{"class":529,"line":530},"line",1,[527,532,534],{"class":533},"sgsFI","foo::string | bar::",[527,536,461],{"class":537},"sD7c4",[527,539,540],{"class":533}," | baz::",[527,542,543],{"class":537},"float\n",[123,545,546],{},"For attributes with mixed types across spans (not recommended), you can query multiple types:",[518,548,550],{"className":520,"code":549,"language":522,"meta":523,"style":523},"foo::string | foo::int\n",[127,551,552],{"__ignoreMap":523},[527,553,554,557],{"class":529,"line":530},[527,555,556],{"class":533},"foo::string | foo::",[527,558,559],{"class":537},"int\n",[123,561,562,565],{},[217,563,564],{},"Note:"," Uptrace uses type information as a hint for reading columnar data, not for type conversion.",[196,567,569],{"id":568},"units","Units",[123,571,572],{},"Specify attribute units by adding the unit name as a suffix to improve data interpretation and readability:",[230,574,575,585],{},[233,576,577],{},[236,578,579,582],{},[239,580,581],{},"Attribute",[239,583,584],{},"Unit",[246,586,587,599,611,623],{},[236,588,589,594],{},[251,590,591],{},[127,592,593],{},"http_read_bytes",[251,595,596],{},[127,597,598],{},"bytes",[236,600,601,606],{},[251,602,603],{},[127,604,605],{},"request_dur_ms_seconds",[251,607,608],{},[127,609,610],{},"seconds",[236,612,613,618],{},[251,614,615],{},[127,616,617],{},"elapsed_milliseconds",[251,619,620],{},[127,621,622],{},"milliseconds",[236,624,625,630],{},[251,626,627],{},[127,628,629],{},"memory_utilization",[251,631,632],{},[127,633,634],{},"utilization",[123,636,637],{},"If you cannot modify the attribute name, use aliases in queries:",[518,639,641],{"className":520,"code":640,"language":522,"meta":523,"style":523},"sum(heap_size) as heap_size_bytes\n",[127,642,643],{"__ignoreMap":523},[527,644,645,649,652,655],{"class":529,"line":530},[527,646,648],{"class":647},"sYu0t","sum",[527,650,651],{"class":533},"(heap_size) ",[527,653,654],{"class":537},"as",[527,656,657],{"class":533}," heap_size_bytes\n",[196,659,661],{"id":660},"string-literals","String Literals",[123,663,664],{},"Strings can be defined using single quotes, double quotes, or backticks:",[518,666,668],{"className":520,"code":667,"language":522,"meta":523,"style":523},"\"I'm a string\\n\"           -- Double quotes with escape sequences\n'I\\'m a string\\n'          -- Single quotes with escape sequences\n`^some-prefix-(\\w+)$`      -- Backticks (no escape sequences, useful for regex)\n",[127,669,670,680,692],{"__ignoreMap":523},[527,671,672,676],{"class":529,"line":530},[527,673,675],{"class":674},"sYBdl","\"I'm a string\\n\"",[527,677,679],{"class":678},"sAwPA","           -- Double quotes with escape sequences\n",[527,681,683,686,689],{"class":529,"line":682},2,[527,684,685],{"class":674},"'I\\'",[527,687,688],{"class":533},"m a string\\n",[527,690,691],{"class":674},"'          -- Single quotes with escape sequences\n",[527,693,695,698,701],{"class":529,"line":694},3,[527,696,697],{"class":674},"`^some-prefix-(",[527,699,700],{"class":647},"\\w",[527,702,703],{"class":674},"+)$`      -- Backticks (no escape sequences, useful for regex)\n",[147,705,707],{"id":706},"query-clauses","Query Clauses",[196,709,711],{"id":710},"filters","Filtering with WHERE",[123,713,714,715,718],{},"Use ",[127,716,717],{},"where"," clauses to filter spans and events by their attributes. The following examples demonstrate common filtering patterns:",[230,720,721,730],{},[233,722,723],{},[236,724,725,728],{},[239,726,727],{},"Filter Example",[239,729,244],{},[246,731,732,741,751,761,771,784,798,811],{},[236,733,734,738],{},[251,735,736],{},[127,737,129],{},[251,739,740],{},"Filter spans with error status (case-sensitive)",[236,742,743,748],{},[251,744,745],{},[127,746,747],{},"where _display_name like \"hello%\"",[251,749,750],{},"Filter span names starting with \"hello\" (case-insensitive)",[236,752,753,758],{},[251,754,755],{},[127,756,757],{},"where _display_name like \"%hello\"",[251,759,760],{},"Filter span names ending with \"hello\" (case-insensitive)",[236,762,763,768],{},[251,764,765],{},[127,766,767],{},"where _display_name contains \"hello\"",[251,769,770],{},"Filter span names containing \"hello\" (case-insensitive)",[236,772,773,778],{},[251,774,775],{},[127,776,777],{},"where _display_name contains \"foo|bar\"",[251,779,780,781],{},"Same as ",[127,782,783],{},"_display_name contains \"foo\" OR _display_name contains \"bar\"",[236,785,786,791],{},[251,787,788],{},[127,789,790],{},"where _dur_ms > 1ms",[251,792,793,794,797],{},"Duration greater than 1 millisecond (equivalent to ",[127,795,796],{},"_dur_ms > 1000",")",[236,799,800,805],{},[251,801,802],{},[127,803,804],{},"where http_request_content_length > 1kb",[251,806,807,808,797],{},"Content length greater than 1 kilobyte (equivalent to ",[127,809,810],{},"http_request_content_length > 1024",[236,812,813,818],{},[251,814,815],{},[127,816,817],{},"where foo exists",[251,819,820,821,392],{},"Filter spans that have the ",[127,822,823],{},"foo",[222,825,827],{"id":826},"supported-units-in-filters","Supported Units in Filters",[155,829,830,848],{},[158,831,832,835,836,839,840,843,844,847],{},[217,833,834],{},"Time units:"," ",[127,837,838],{},"μs"," (microseconds), ",[127,841,842],{},"ms"," (milliseconds), ",[127,845,846],{},"s"," (seconds)",[158,849,850,835,853,856,857,860,861,864,865,868],{},[217,851,852],{},"Size units:",[127,854,855],{},"kb"," (kilobytes), ",[127,858,859],{},"mb"," (megabytes), ",[127,862,863],{},"gb"," (gigabytes), ",[127,866,867],{},"tb"," (terabytes)",[196,870,872],{"id":871},"filtering-results-with-having","Filtering Results with HAVING",[123,874,714,875,878],{},[127,876,877],{},"having"," to filter aggregated query results after grouping:",[518,880,882],{"className":520,"code":881,"language":522,"meta":523,"style":523},"group by service_name | having p50(_dur_ms) > 100ms\n",[127,883,884],{"__ignoreMap":523},[527,885,886,889,892,895,897,900,902],{"class":529,"line":530},[527,887,888],{"class":537},"group by",[527,890,891],{"class":537}," service_name",[527,893,894],{"class":533}," | ",[527,896,877],{"class":537},[527,898,899],{"class":533}," p50(_dur_ms) ",[527,901,477],{"class":537},[527,903,904],{"class":533}," 100ms\n",[196,906,95],{"id":185},[123,908,909,910,913],{},"You can use ",[162,911,912],{"href":96},"search"," to filter query results using a simpler syntax:",[518,915,917],{"className":520,"code":916,"language":522,"meta":523,"style":523},"search foo|bar -hello\n",[127,918,919],{"__ignoreMap":523},[527,920,921,924,927],{"class":529,"line":530},[527,922,923],{"class":533},"search foo|bar ",[527,925,926],{"class":537},"-",[527,928,929],{"class":533},"hello\n",[123,931,932,933,935],{},"This approach is more concise than complex ",[127,934,717],{}," clauses for basic text matching.",[196,937,939],{"id":938},"groupings","Grouping with GROUP BY",[123,941,942,943,945],{},"Group spans using ",[127,944,888],{}," clauses, similar to SQL. The following examples show common grouping patterns:",[230,947,948,957],{},[233,949,950],{},[236,951,952,955],{},[239,953,954],{},"Example",[239,956,244],{},[246,958,959,968,981,996,1009],{},[236,960,961,965],{},[251,962,963],{},[127,964,133],{},[251,966,967],{},"Groups similar spans together",[236,969,970,975],{},[251,971,972],{},[127,973,974],{},"group by host_name",[251,976,977,978,392],{},"Groups spans by the ",[127,979,980],{},"host_name",[236,982,983,988],{},[251,984,985],{},[127,986,987],{},"group by service_name, service_version",[251,989,990,991,166,993],{},"Groups spans by combination of ",[127,992,399],{},[127,994,995],{},"service_version",[236,997,998,1003],{},[251,999,1000],{},[127,1001,1002],{},"group by lower(attribute)",[251,1004,1005,1006],{},"Groups by lowercase value of ",[127,1007,1008],{},"attribute",[236,1010,1011,1016],{},[251,1012,1013],{},[127,1014,1015],{},"extract(host_name, `^server-(\\w+)$`) as host",[251,1017,1018,1019],{},"Extracts and groups by a fragment from ",[127,1020,980],{},[123,1022,1023,1024,1028,1029,1031],{},"You can use any ",[162,1025,1027],{"href":1026},"#transform-functions","transformation function"," in the ",[127,1030,888],{}," clause to modify values before grouping.",[147,1033,1035],{"id":1034},"functions","Functions",[196,1037,1039],{"id":1038},"aggregations","Aggregate Functions",[123,1041,1042],{},"Aggregate functions perform calculations on sets of values and return single values. They are commonly used with grouping to summarize data.",[230,1044,1045,1056],{},[233,1046,1047],{},[236,1048,1049,1052,1054],{},[239,1050,1051],{},"Function",[239,1053,954],{},[239,1055,244],{},[246,1057,1058,1073,1088,1103,1118,1136,1150,1173,1191,1206],{},[236,1059,1060,1065,1070],{},[251,1061,1062],{},[127,1063,1064],{},"count",[251,1066,1067],{},[127,1068,1069],{},"count()",[251,1071,1072],{},"Number of matched spans\u002Flogs\u002Fevents",[236,1074,1075,1080,1085],{},[251,1076,1077],{},[127,1078,1079],{},"any",[251,1081,1082],{},[127,1083,1084],{},"any(_name)",[251,1086,1087],{},"Any (random) span name",[236,1089,1090,1095,1100],{},[251,1091,1092],{},[127,1093,1094],{},"anyLast",[251,1096,1097],{},[127,1098,1099],{},"anyLast(_name)",[251,1101,1102],{},"Any last span name",[236,1104,1105,1110,1115],{},[251,1106,1107],{},[127,1108,1109],{},"avg",[251,1111,1112],{},[127,1113,1114],{},"avg(_dur_ms)",[251,1116,1117],{},"Average span duration",[236,1119,1120,1128,1133],{},[251,1121,1122,206,1125],{},[127,1123,1124],{},"min",[127,1126,1127],{},"max",[251,1129,1130],{},[127,1131,1132],{},"max(_dur_ms)",[251,1134,1135],{},"Minimum\u002Fmaximum span duration",[236,1137,1138,1142,1147],{},[251,1139,1140],{},[127,1141,648],{},[251,1143,1144],{},[127,1145,1146],{},"sum(http_request_content_length)",[251,1148,1149],{},"Total sum of values",[236,1151,1152,1166,1170],{},[251,1153,1154,206,1157,206,1160,206,1163],{},[127,1155,1156],{},"p50",[127,1158,1159],{},"p75",[127,1161,1162],{},"p90",[127,1164,1165],{},"p99",[251,1167,1168],{},[127,1169,137],{},[251,1171,1172],{},"Span duration percentiles",[236,1174,1175,1183,1188],{},[251,1176,1177,206,1180],{},[127,1178,1179],{},"top3",[127,1181,1182],{},"top10",[251,1184,1185],{},[127,1186,1187],{},"top3(code_function)",[251,1189,1190],{},"Top N most popular values",[236,1192,1193,1198,1203],{},[251,1194,1195],{},[127,1196,1197],{},"uniq",[251,1199,1200],{},[127,1201,1202],{},"uniq(http_client_ip)",[251,1204,1205],{},"Number of unique values",[236,1207,1208,1213,1218],{},[251,1209,1210],{},[127,1211,1212],{},"apdex",[251,1214,1215],{},[127,1216,1217],{},"apdex(500ms, 3s)",[251,1219,1220,1226],{},[162,1221,1225],{"href":1222,"rel":1223},"https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FApdex",[1224],"nofollow","Apdex"," score",[222,1228,1230],{"id":1229},"conditional-aggregates","Conditional Aggregates",[123,1232,1233,1234,1239],{},"Uptrace supports ClickHouse ",[162,1235,1238],{"href":1236,"rel":1237},"https:\u002F\u002Fclickhouse.com\u002Fdocs\u002Fen\u002Fsql-reference\u002Faggregate-functions\u002Fcombinators#-if",[1224],"if"," combinator on aggregate functions for conditional calculations:",[155,1241,1242,1248],{},[158,1243,1244,1247],{},[127,1245,1246],{},"countIf(_status_code = \"error\")"," - Count spans with error status",[158,1249,1250,1253],{},[127,1251,1252],{},"p50If(_dur_ms, service_name = \"service1\")"," - P50 duration for specific service",[222,1255,1257],{"id":1256},"virtual-columns","Virtual Columns",[123,1259,1260],{},"Uptrace provides shortcuts for common aggregations to simplify queries:",[230,1262,1263,1273],{},[233,1264,1265],{},[236,1266,1267,1270],{},[239,1268,1269],{},"Virtual Column",[239,1271,1272],{},"Equivalent Expression",[246,1274,1275],{},[236,1276,1277,1282],{},[251,1278,1279],{},[127,1280,1281],{},"_error_rate",[251,1283,1284],{},[127,1285,1286],{},"countIf(_status_code = \"error\") \u002F count()",[196,1288,1290],{"id":1289},"transform-functions","Transform Functions",[123,1292,1293],{},"Transform functions accept a value and return a new value for each matched span\u002Flog\u002Fevent. These functions are useful for data manipulation and formatting.",[230,1295,1296,1306],{},[233,1297,1298],{},[236,1299,1300,1302,1304],{},[239,1301,1051],{},[239,1303,954],{},[239,1305,244],{},[246,1307,1308,1323,1338,1353,1368,1383,1398,1416,1431,1446,1465,1480,1495],{},[236,1309,1310,1315,1320],{},[251,1311,1312],{},[127,1313,1314],{},"lower",[251,1316,1317],{},[127,1318,1319],{},"lower(log_severity)",[251,1321,1322],{},"Converts string to lowercase",[236,1324,1325,1330,1335],{},[251,1326,1327],{},[127,1328,1329],{},"upper",[251,1331,1332],{},[127,1333,1334],{},"upper(log_severity)",[251,1336,1337],{},"Converts string to uppercase",[236,1339,1340,1345,1350],{},[251,1341,1342],{},[127,1343,1344],{},"perMin",[251,1346,1347],{},[127,1348,1349],{},"perMin(count())",[251,1351,1352],{},"Divides value by the number of minutes in the time interval",[236,1354,1355,1360,1365],{},[251,1356,1357],{},[127,1358,1359],{},"perSec",[251,1361,1362],{},[127,1363,1364],{},"perSec(count())",[251,1366,1367],{},"Divides value by the number of seconds in the time interval",[236,1369,1370,1375,1380],{},[251,1371,1372],{},[127,1373,1374],{},"trimPrefix(str, prefix)",[251,1376,1377],{},[127,1378,1379],{},"trimPrefix(str, \"prefix\")",[251,1381,1382],{},"Removes the specified leading prefix string",[236,1384,1385,1390,1395],{},[251,1386,1387],{},[127,1388,1389],{},"trimSuffix(str, suffix)",[251,1391,1392],{},[127,1393,1394],{},"trimSuffix(str, \"suffix\")",[251,1396,1397],{},"Removes the specified trailing suffix string",[236,1399,1400,1405,1413],{},[251,1401,1402],{},[127,1403,1404],{},"extract(haystack, pattern)",[251,1406,1407,1410,1411],{},[127,1408,1409],{},"extract(host_name, ","^uptrace-prod-(\\w+)$",[127,1412,797],{},[251,1414,1415],{},"Extracts a fragment using regular expression",[236,1417,1418,1423,1428],{},[251,1419,1420],{},[127,1421,1422],{},"replace(haystack, substring, replacement)",[251,1424,1425],{},[127,1426,1427],{},"replace(host_name, 'uptrace-prod-', '')",[251,1429,1430],{},"Replaces all occurrences of substring",[236,1432,1433,1438,1443],{},[251,1434,1435],{},[127,1436,1437],{},"replaceRegexp(haystack, pattern, replacement)",[251,1439,1440],{},[127,1441,1442],{},"replaceRegexp(host, `^`, 'prefix ')",[251,1444,1445],{},"Replaces all occurrences matching regular expression pattern",[236,1447,1448,1453,1458],{},[251,1449,1450],{},[127,1451,1452],{},"arrayJoin",[251,1454,1455],{},[127,1456,1457],{},"arrayJoin(db_sql_tables)",[251,1459,1460,1461],{},"See ClickHouse ",[162,1462,1452],{"href":1463,"rel":1464},"https:\u002F\u002Fclickhouse.com\u002Fdocs\u002Fen\u002Fsql-reference\u002Ffunctions\u002Farray-join",[1224],[236,1466,1467,1472,1477],{},[251,1468,1469],{},[127,1470,1471],{},"parseInt64",[251,1473,1474],{},[127,1475,1476],{},"parseInt64(str_with_int)",[251,1478,1479],{},"Parses string as 64-bit integer",[236,1481,1482,1487,1492],{},[251,1483,1484],{},[127,1485,1486],{},"parseFloat64",[251,1488,1489],{},[127,1490,1491],{},"parseFloat64(str_with_float)",[251,1493,1494],{},"Parses string as 64-bit float",[236,1496,1497,1502,1507],{},[251,1498,1499],{},[127,1500,1501],{},"parseDateTime",[251,1503,1504],{},[127,1505,1506],{},"parseDateTime(str_with_time)",[251,1508,1509],{},"Parses string as date with time",[222,1511,1513],{"id":1512},"time-rounding-functions","Time Rounding Functions",[123,1515,1516],{},"Time rounding functions are particularly useful for time-series analysis and creating time-based aggregations:",[230,1518,1519,1527],{},[233,1520,1521],{},[236,1522,1523,1525],{},[239,1524,1051],{},[239,1526,244],{},[246,1528,1529,1539,1549,1559,1569,1579,1589],{},[236,1530,1531,1536],{},[251,1532,1533],{},[127,1534,1535],{},"toStartOfDay",[251,1537,1538],{},"Rounds down to start of day",[236,1540,1541,1546],{},[251,1542,1543],{},[127,1544,1545],{},"toStartOfHour",[251,1547,1548],{},"Rounds down to start of hour",[236,1550,1551,1556],{},[251,1552,1553],{},[127,1554,1555],{},"toStartOfMinute",[251,1557,1558],{},"Rounds down to start of minute",[236,1560,1561,1566],{},[251,1562,1563],{},[127,1564,1565],{},"toStartOfSecond",[251,1567,1568],{},"Rounds down to start of second",[236,1570,1571,1576],{},[251,1572,1573],{},[127,1574,1575],{},"toStartOfFiveMinutes",[251,1577,1578],{},"Rounds down to start of 5-minute interval",[236,1580,1581,1586],{},[251,1582,1583],{},[127,1584,1585],{},"toStartOfTenMinutes",[251,1587,1588],{},"Rounds down to start of 10-minute interval",[236,1590,1591,1596],{},[251,1592,1593],{},[127,1594,1595],{},"toStartOfFifteenMinutes",[251,1597,1598],{},"Rounds down to start of 15-minute interval",[147,1600,1602],{"id":1601},"complete-query-examples","Complete Query Examples",[123,1604,1605],{},"You can combine filters, grouping, and aggregates to create powerful queries for comprehensive observability analysis.",[196,1607,1609],{"id":1608},"daily-unique-visitors-excluding-bots","Daily Unique Visitors (Excluding Bots)",[518,1611,1613],{"className":520,"code":1612,"language":522,"meta":523,"style":523},"where user_agent_is_bot not exists | uniq(client_address) | group by toStartOfDay(_time)\n",[127,1614,1615],{"__ignoreMap":523},[527,1616,1617,1619,1622,1625,1628,1631,1633],{"class":529,"line":530},[527,1618,717],{"class":537},[527,1620,1621],{"class":533}," user_agent_is_bot ",[527,1623,1624],{"class":537},"not",[527,1626,1627],{"class":537}," exists",[527,1629,1630],{"class":533}," | uniq(client_address) | ",[527,1632,888],{"class":537},[527,1634,1635],{"class":533}," toStartOfDay(_time)\n",[123,1637,1638],{},"This query identifies unique visitors per day while excluding bot traffic.",[196,1640,1642],{"id":1641},"error-rate-by-service","Error Rate by Service",[518,1644,1646],{"className":520,"code":1645,"language":522,"meta":523,"style":523},"group by service_name | having count() > 100 | select service_name, _error_rate\n",[127,1647,1648],{"__ignoreMap":523},[527,1649,1650,1652,1654,1656,1658,1661,1664,1666,1669,1671,1674,1676],{"class":529,"line":530},[527,1651,888],{"class":537},[527,1653,891],{"class":537},[527,1655,894],{"class":533},[527,1657,877],{"class":537},[527,1659,1660],{"class":647}," count",[527,1662,1663],{"class":533},"() ",[527,1665,477],{"class":537},[527,1667,1668],{"class":647}," 100",[527,1670,894],{"class":533},[527,1672,1673],{"class":537},"select",[527,1675,891],{"class":537},[527,1677,1678],{"class":533},", _error_rate\n",[123,1680,1681],{},"This query calculates error rates for services with significant traffic (more than 100 requests).",[196,1683,1685],{"id":1684},"top-10-slowest-operations","Top 10 Slowest Operations",[518,1687,1689],{"className":520,"code":1688,"language":522,"meta":523,"style":523},"where _dur_ms > 100ms | group by _name | top10(_name)\n",[127,1690,1691],{"__ignoreMap":523},[527,1692,1693,1695,1698,1700,1703,1705],{"class":529,"line":530},[527,1694,717],{"class":537},[527,1696,1697],{"class":533}," _dur_ms ",[527,1699,477],{"class":537},[527,1701,1702],{"class":533}," 100ms | ",[527,1704,888],{"class":537},[527,1706,1707],{"class":533}," _name | top10(_name)\n",[123,1709,1710],{},"This query identifies the slowest operations based on 99th percentile duration.",[123,1712,1713],{},[142,1714],{"alt":45,"src":1715},"\u002Ffeatures\u002Fquerying-spans\u002Fquerying.png",[147,1717,1719],{"id":1718},"performance","Query Performance Optimization",[123,1721,1722],{},"If your queries are taking too long to complete, apply these optimization strategies to improve performance:",[196,1724,1726],{"id":1725},"narrow-the-time-range","Narrow the Time Range",[155,1728,1729,1732],{},[158,1730,1731],{},"Select shorter time periods when possible (e.g., \"Last 1 hour\" instead of \"Last 24 hours\")",[158,1733,1734],{},"Consider the data volume when selecting time ranges",[196,1736,1738],{"id":1737},"use-system-filters","Use System Filters",[155,1740,1741,1744,1751],{},[158,1742,1743],{},"Select specific systems when analyzing particular types of requests",[158,1745,1746,1747,1750],{},"Example: Select ",[127,1748,1749],{},"httpserver:all"," system for HTTP request analysis",[158,1752,1753],{},"This reduces the data scope significantly",[196,1755,1757],{"id":1756},"add-group-filters","Add Group Filters",[155,1759,1760,1767,1773],{},[158,1761,1762,1763,1766],{},"Further narrow scope with ",[127,1764,1765],{},"_group_id"," filters",[158,1768,1769,1770],{},"Example: ",[127,1771,1772],{},"where _group_id = 123456789",[158,1774,1775],{},"Group filters are highly efficient for targeted analysis",[196,1777,1779],{"id":1778},"leverage-indexed-attributes","Leverage Indexed Attributes",[155,1781,1782,1789,1797],{},[158,1783,714,1784,1788],{},[162,1785,1787],{"href":1786},"\u002Fopentelemetry\u002Fsemconv","OpenTelemetry semantic conventions"," for attribute names",[158,1790,1791,1792,1796],{},"Uptrace optimizes ",[162,1793,1795],{"href":1794},"\u002Fopentelemetry\u002Fsemconv#indexed-attributes","certain attributes"," better than others",[158,1798,1799],{},"Indexed attributes provide faster query performance",[196,1801,1803],{"id":1802},"query-structure-best-practices","Query Structure Best Practices",[155,1805,1806,1809,1812,1818],{},[158,1807,1808],{},"Apply filters before grouping when possible to reduce data volume",[158,1810,1811],{},"Use specific filters rather than broad pattern matching",[158,1813,1814,1815,1817],{},"Limit the number of groups in ",[127,1816,888],{}," clauses",[158,1819,1820,1821,1823],{},"Consider using ",[127,1822,877],{}," clauses to filter aggregated results",[147,1825,1827],{"id":1826},"common-query-patterns","Common Query Patterns",[196,1829,1831],{"id":1830},"error-analysis","Error Analysis",[518,1833,1835],{"className":520,"code":1834,"language":522,"meta":523,"style":523},"-- Find error patterns by service\nwhere _status_code = \"error\" | group by service_name, _name |\nselect service_name, _name, count(), p50(_dur_ms)\n",[127,1836,1837,1842,1863],{"__ignoreMap":523},[527,1838,1839],{"class":529,"line":530},[527,1840,1841],{"class":678},"-- Find error patterns by service\n",[527,1843,1844,1846,1849,1851,1854,1856,1858,1860],{"class":529,"line":682},[527,1845,717],{"class":537},[527,1847,1848],{"class":533}," _status_code ",[527,1850,438],{"class":537},[527,1852,1853],{"class":674}," \"error\"",[527,1855,894],{"class":533},[527,1857,888],{"class":537},[527,1859,891],{"class":537},[527,1861,1862],{"class":533},", _name |\n",[527,1864,1865,1867,1869,1872,1874],{"class":529,"line":694},[527,1866,1673],{"class":537},[527,1868,891],{"class":537},[527,1870,1871],{"class":533},", _name, ",[527,1873,1064],{"class":647},[527,1875,1876],{"class":533},"(), p50(_dur_ms)\n",[196,1878,1880],{"id":1879},"performance-monitoring","Performance Monitoring",[518,1882,1884],{"className":520,"code":1883,"language":522,"meta":523,"style":523},"-- Monitor slow requests across services\nwhere _dur_ms > 1s | group by service_name |\nselect service_name, count(), p95(_dur_ms), p99(_dur_ms)\n",[127,1885,1886,1891,1909],{"__ignoreMap":523},[527,1887,1888],{"class":529,"line":530},[527,1889,1890],{"class":678},"-- Monitor slow requests across services\n",[527,1892,1893,1895,1897,1899,1902,1904,1906],{"class":529,"line":682},[527,1894,717],{"class":537},[527,1896,1697],{"class":533},[527,1898,477],{"class":537},[527,1900,1901],{"class":533}," 1s | ",[527,1903,888],{"class":537},[527,1905,891],{"class":537},[527,1907,1908],{"class":533}," |\n",[527,1910,1911,1913,1915,1917,1919],{"class":529,"line":694},[527,1912,1673],{"class":537},[527,1914,891],{"class":537},[527,1916,206],{"class":533},[527,1918,1064],{"class":647},[527,1920,1921],{"class":533},"(), p95(_dur_ms), p99(_dur_ms)\n",[196,1923,1925],{"id":1924},"traffic-analysis","Traffic Analysis",[518,1927,1929],{"className":520,"code":1928,"language":522,"meta":523,"style":523},"-- Analyze request volume over time\ngroup by toStartOfHour(_time), service_name |\nselect _time, service_name, count() as request_count\n",[127,1930,1931,1936,1947],{"__ignoreMap":523},[527,1932,1933],{"class":529,"line":530},[527,1934,1935],{"class":678},"-- Analyze request volume over time\n",[527,1937,1938,1940,1943,1945],{"class":529,"line":682},[527,1939,888],{"class":537},[527,1941,1942],{"class":533}," toStartOfHour(_time), ",[527,1944,399],{"class":537},[527,1946,1908],{"class":533},[527,1948,1949,1951,1954,1956,1958,1960,1962,1964],{"class":529,"line":694},[527,1950,1673],{"class":537},[527,1952,1953],{"class":533}," _time, ",[527,1955,399],{"class":537},[527,1957,206],{"class":533},[527,1959,1064],{"class":647},[527,1961,1663],{"class":533},[527,1963,654],{"class":537},[527,1965,1966],{"class":533}," request_count\n",[147,1968,1970],{"id":1969},"see-also","See Also",[155,1972,1973,1979,1985],{},[158,1974,1975,1978],{},[162,1976,1977],{"href":96},"Searching spans and logs"," - For simpler search syntax",[158,1980,1981,1984],{},[162,1982,1983],{"href":1786},"OpenTelemetry Semantic Conventions"," - For optimized attribute naming",[158,1986,1987,1991],{},[162,1988,1990],{"href":1989},"grouping","Grouping Strategies"," - Advanced grouping techniques",[1993,1994,1995],"style",{},"html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}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 pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}",{"title":523,"searchDepth":1997,"depth":682,"links":1998},4,[1999,2000,2006,2012,2016,2021,2028,2033],{"id":149,"depth":682,"text":150},{"id":193,"depth":682,"text":194,"children":2001},[2002,2003,2004,2005],{"id":198,"depth":694,"text":199},{"id":408,"depth":694,"text":409},{"id":568,"depth":694,"text":569},{"id":660,"depth":694,"text":661},{"id":706,"depth":682,"text":707,"children":2007},[2008,2009,2010,2011],{"id":710,"depth":694,"text":711},{"id":871,"depth":694,"text":872},{"id":185,"depth":694,"text":95},{"id":938,"depth":694,"text":939},{"id":1034,"depth":682,"text":1035,"children":2013},[2014,2015],{"id":1038,"depth":694,"text":1039},{"id":1289,"depth":694,"text":1290},{"id":1601,"depth":682,"text":1602,"children":2017},[2018,2019,2020],{"id":1608,"depth":694,"text":1609},{"id":1641,"depth":694,"text":1642},{"id":1684,"depth":694,"text":1685},{"id":1718,"depth":682,"text":1719,"children":2022},[2023,2024,2025,2026,2027],{"id":1725,"depth":694,"text":1726},{"id":1737,"depth":694,"text":1738},{"id":1756,"depth":694,"text":1757},{"id":1778,"depth":694,"text":1779},{"id":1802,"depth":694,"text":1803},{"id":1826,"depth":682,"text":1827,"children":2029},[2030,2031,2032],{"id":1830,"depth":694,"text":1831},{"id":1879,"depth":694,"text":1880},{"id":1924,"depth":694,"text":1925},{"id":1969,"depth":682,"text":1970},"Master the Uptrace span query language including identifiers, filters, grouping, and aggregates for traces, logs, and events.","md",null,{"readingTime":2038},{"text":2039,"minutes":2040,"time":2041,"words":2042},"6 min read",5.1,306000,1020,{"title":21,"description":2034},"1U359cuii3KQX-7pzAPVhvRHCgl6EGXLJSYIs5SA_Qk",[2046,2048],{"title":17,"path":18,"stem":19,"description":2047,"children":-1},"Optimize grouping by choosing stable span names, leveraging display.name, and providing custom fingerprints when needed.",{"title":25,"path":26,"stem":27,"description":2049,"children":-1},"Query distributed traces by filtering spans, logs, and events across services using the multi-row trace query syntax.",1778588615776]