chore: generate new openapi spec

ee/query-service/app/api/api.go

@@ -10,6 +10,7 @@ import (
 	"github.com/SigNoz/signoz/ee/query-service/usage"
 	"github.com/SigNoz/signoz/pkg/alertmanager"
 	"github.com/SigNoz/signoz/pkg/global"
+	"github.com/SigNoz/signoz/pkg/http/handler"
 	"github.com/SigNoz/signoz/pkg/http/middleware"
 	querierAPI "github.com/SigNoz/signoz/pkg/querier"
 	baseapp "github.com/SigNoz/signoz/pkg/query-service/app"
@@ -106,7 +107,10 @@ func (ah *APIHandler) RegisterRoutes(router *mux.Router, am *middleware.AuthZ) {
 	router.HandleFunc("/api/v4/query_range", am.ViewAccess(ah.queryRangeV4)).Methods(http.MethodPost)
 
 	// v5
-	router.HandleFunc("/api/v5/query_range", am.ViewAccess(ah.queryRangeV5)).Methods(http.MethodPost)
+	router.Handle("/api/v5/query_range", handler.New(
+		am.ViewAccess(ah.queryRangeV5),
+		querierAPI.QueryRangeV5OpenAPIDef,
+	)).Methods(http.MethodPost)
 
 	router.HandleFunc("/api/v5/substitute_vars", am.ViewAccess(ah.QuerierAPI.ReplaceVariables)).Methods(http.MethodPost)
 

frontend/src/api/generated/services/query/index.ts

@@ -0,0 +1,107 @@
+/**
+ * ! Do not edit manually
+ * * The file has been auto-generated using Orval for SigNoz
+ * * regenerate with 'yarn generate:api'
+ * SigNoz
+ */
+import type {
+	MutationFunction,
+	UseMutationOptions,
+	UseMutationResult,
+} from 'react-query';
+import { useMutation } from 'react-query';
+
+import { GeneratedAPIInstance } from '../../../index';
+import type {
+	Querybuildertypesv5QueryRangeRequestDTO,
+	QueryRangeV5200,
+	RenderErrorResponseDTO,
+} from '../sigNoz.schemas';
+
+type AwaitedInput<T> = PromiseLike<T> | T;
+
+type Awaited<O> = O extends AwaitedInput<infer T> ? T : never;
+
+/**
+ * Execute a composite query over a time range. Supports builder queries (traces, logs, metrics), formulas, trace operators, PromQL, and ClickHouse SQL.
+ * @summary Query range
+ */
+export const queryRangeV5 = (
+	querybuildertypesv5QueryRangeRequestDTO: Querybuildertypesv5QueryRangeRequestDTO,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<QueryRangeV5200>({
+		url: `/api/v5/query_range`,
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		data: querybuildertypesv5QueryRangeRequestDTO,
+		signal,
+	});
+};
+
+export const getQueryRangeV5MutationOptions = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		TError,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof queryRangeV5>>,
+	TError,
+	{ data: Querybuildertypesv5QueryRangeRequestDTO },
+	TContext
+> => {
+	const mutationKey = ['queryRangeV5'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+		  'mutationKey' in options.mutation &&
+		  options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO }
+	> = (props) => {
+		const { data } = props ?? {};
+
+		return queryRangeV5(data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type QueryRangeV5MutationResult = NonNullable<
+	Awaited<ReturnType<typeof queryRangeV5>>
+>;
+export type QueryRangeV5MutationBody = Querybuildertypesv5QueryRangeRequestDTO;
+export type QueryRangeV5MutationError = RenderErrorResponseDTO;
+
+/**
+ * @summary Query range
+ */
+export const useQueryRangeV5 = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		TError,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof queryRangeV5>>,
+	TError,
+	{ data: Querybuildertypesv5QueryRangeRequestDTO },
+	TContext
+> => {
+	const mutationOptions = getQueryRangeV5MutationOptions(options);
+
+	return useMutation(mutationOptions);
+};

pkg/http/handler/handler.go

@@ -7,6 +7,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/http/render"
 	"github.com/swaggest/openapi-go"
+	"github.com/swaggest/openapi-go/openapi3"
 )
 
 type ServeOpenAPIFunc func(openapi.OperationContext)
@@ -59,7 +60,39 @@ func (handler *handler) ServeOpenAPI(opCtx openapi.OperationContext) {
 	}
 
 	// Add request structure
-	opCtx.AddReqStructure(handler.openAPIDef.Request, openapi.WithContentType(handler.openAPIDef.RequestContentType))
+	reqOpts := []openapi.ContentOption{openapi.WithContentType(handler.openAPIDef.RequestContentType)}
+	if len(handler.openAPIDef.RequestExamples) > 0 {
+		reqOpts = append(reqOpts, openapi.WithCustomize(func(cor openapi.ContentOrReference) {
+			rbOrRef, ok := cor.(*openapi3.RequestBodyOrRef)
+			if !ok || rbOrRef.RequestBody == nil {
+				return
+			}
+			ct := handler.openAPIDef.RequestContentType
+			if ct == "" {
+				ct = "application/json"
+			}
+			mt, exists := rbOrRef.RequestBody.Content[ct]
+			if !exists {
+				return
+			}
+			if mt.Examples == nil {
+				mt.Examples = make(map[string]openapi3.ExampleOrRef)
+			}
+			for _, ex := range handler.openAPIDef.RequestExamples {
+				val := ex.Value
+				oaExample := openapi3.Example{Value: &val}
+				if ex.Summary != "" {
+					oaExample.WithSummary(ex.Summary)
+				}
+				if ex.Description != "" {
+					oaExample.WithDescription(ex.Description)
+				}
+				mt.Examples[ex.Name] = openapi3.ExampleOrRef{Example: &oaExample}
+			}
+			rbOrRef.RequestBody.Content[ct] = mt
+		}))
+	}
+	opCtx.AddReqStructure(handler.openAPIDef.Request, reqOpts...)
 
 	// Add request query structure
 	opCtx.AddReqStructure(handler.openAPIDef.RequestQuery)

pkg/http/handler/openapi.go

@@ -9,6 +9,14 @@ import (
 	"github.com/swaggest/rest/openapi"
 )
 
+// OpenAPIExample is a named example for an OpenAPI operation.
+type OpenAPIExample struct {
+	Name        string
+	Summary     string
+	Description string
+	Value       any
+}
+
 // Def is the definition of an OpenAPI operation
 type OpenAPIDef struct {
 	ID                  string
@@ -18,6 +26,7 @@ type OpenAPIDef struct {
 	Request             any
 	RequestQuery        any
 	RequestContentType  string
+	RequestExamples     []OpenAPIExample
 	Response            any
 	ResponseContentType string
 	SuccessStatusCode   int

pkg/querier/builder_query.go

@@ -80,11 +80,12 @@ func (q *builderQuery[T]) Fingerprint() string {
 			case qbtypes.LogAggregation:
 				aggParts = append(aggParts, a.Expression)
 			case qbtypes.MetricAggregation:
-				aggParts = append(aggParts, fmt.Sprintf("%s:%s:%s:%s",
+				aggParts = append(aggParts, fmt.Sprintf("%s:%s:%s:%s:%s",
 					a.MetricName,
 					a.Temporality.StringValue(),
 					a.TimeAggregation.StringValue(),
 					a.SpaceAggregation.StringValue(),
+					a.SpaceAggregationParam.StringValue(),
 				))
 			}
 		}

pkg/querier/openapi.go

@@ -0,0 +1,454 @@
+package querier
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/http/handler"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
+)
+
+// QueryRangeV5OpenAPIDef is the OpenAPI definition for the /api/v5/query_range endpoint.
+var QueryRangeV5OpenAPIDef = handler.OpenAPIDef{
+	ID:                  "QueryRangeV5",
+	Tags:                []string{"query"},
+	Summary:             "Query range",
+	Description:         "Execute a composite query over a time range. Supports builder queries (traces, logs, metrics), formulas, trace operators, PromQL, and ClickHouse SQL.",
+	Request:             new(qbtypes.QueryRangeRequest),
+	RequestContentType:  "application/json",
+	RequestExamples:     queryRangeV5Examples,
+	Response:            new(qbtypes.QueryRangeResponse),
+	ResponseContentType: "application/json",
+	SuccessStatusCode:   http.StatusOK,
+	ErrorStatusCodes:    []int{http.StatusBadRequest},
+	SecuritySchemes: []handler.OpenAPISecurityScheme{
+		{Name: ctxtypes.AuthTypeAPIKey.StringValue(), Scopes: []string{"VIEWER"}},
+		{Name: ctxtypes.AuthTypeTokenizer.StringValue(), Scopes: []string{"VIEWER"}},
+	},
+}
+
+var queryRangeV5Examples = []handler.OpenAPIExample{
+	{
+		Name:    "traces_time_series",
+		Summary: "Time series: count spans grouped by service",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "span_count"},
+							},
+							"stepInterval": "60s",
+							"filter":       map[string]any{"expression": "service.name = 'frontend'"},
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+							"order":        []any{map[string]any{"key": map[string]any{"name": "span_count"}, "direction": "desc"}},
+							"limit":        10,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_time_series",
+		Summary: "Time series: count error logs grouped by service",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "log_count"},
+							},
+							"stepInterval": "60s",
+							"filter":       map[string]any{"expression": "severity_text = 'ERROR'"},
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+							"order":        []any{map[string]any{"key": map[string]any{"name": "log_count"}, "direction": "desc"}},
+							"limit":        10,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_gauge_time_series",
+		Summary: "Time series: latest gauge value averaged across series",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "system.cpu.utilization", "timeAggregation": "latest", "spaceAggregation": "avg"},
+							},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "host.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_rate_time_series",
+		Summary: "Time series: rate of cumulative counter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum"},
+							},
+							"stepInterval": 120,
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_histogram_time_series",
+		Summary: "Time series: p99 latency from histogram",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.bucket", "spaceAggregation": "p99"},
+							},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_raw",
+		Summary: "Raw: fetch raw log records",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"filter": map[string]any{"expression": "severity_text = 'ERROR'"},
+							"selectFields": []any{
+								map[string]any{"name": "body", "fieldContext": "log"},
+								map[string]any{"name": "service.name", "fieldContext": "resource"},
+							},
+							"order": []any{
+								map[string]any{"key": map[string]any{"name": "timestamp", "fieldContext": "log"}, "direction": "desc"},
+								map[string]any{"key": map[string]any{"name": "id"}, "direction": "desc"},
+							},
+							"limit":  50,
+							"offset": 0,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "traces_raw",
+		Summary: "Raw: fetch raw span records",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"filter": map[string]any{"expression": "service.name = 'frontend' AND has_error = true"},
+							"selectFields": []any{
+								map[string]any{"name": "name", "fieldContext": "span"},
+								map[string]any{"name": "duration_nano", "fieldContext": "span"},
+							},
+							"order": []any{
+								map[string]any{"key": map[string]any{"name": "timestamp", "fieldContext": "span"}, "direction": "desc"},
+							},
+							"limit": 100,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "traces_scalar",
+		Summary: "Scalar: total span count",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "span_count"},
+							},
+							"filter": map[string]any{"expression": "service.name = 'frontend'"},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_scalar",
+		Summary: "Scalar: total error log count",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "error_count"},
+							},
+							"filter": map[string]any{"expression": "severity_text = 'ERROR'"},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_scalar",
+		Summary: "Scalar: single reduced metric value",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum", "reduceTo": "sum"},
+							},
+							"stepInterval": "60s",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "formula",
+		Summary: "Formula: error rate from two trace queries",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":         "A",
+							"signal":       "traces",
+							"aggregations": []any{map[string]any{"expression": "countIf(has_error = true)"}},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":         "B",
+							"signal":       "traces",
+							"aggregations": []any{map[string]any{"expression": "count()"}},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+					map[string]any{
+						"type": "builder_formula",
+						"spec": map[string]any{
+							"name":       "error_rate",
+							"expression": "A / B * 100",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "promql",
+		Summary: "PromQL: request rate with UTF-8 metric name",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "promql",
+						"spec": map[string]any{
+							"name":  "request_rate",
+							"query": "sum(rate({\"http.server.duration.count\"}[5m])) by (\"service.name\")",
+							"step":  60,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_traces_time_series",
+		Summary: "ClickHouse SQL: traces time series with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "span_rate",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT toStartOfInterval(timestamp, INTERVAL 60 SECOND) AS ts, count() AS value" +
+								" FROM signoz_traces.distributed_signoz_index_v3" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_datetime AND timestamp <= $end_datetime" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp" +
+								" GROUP BY ts ORDER BY ts",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_logs_raw",
+		Summary: "ClickHouse SQL: raw logs with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "recent_errors",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT timestamp, body" +
+								" FROM signoz_logs.distributed_logs_v2" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_timestamp_nano AND timestamp <= $end_timestamp_nano" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp" +
+								" AND severity_text = 'ERROR'" +
+								" ORDER BY timestamp DESC LIMIT 100",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_traces_scalar",
+		Summary: "ClickHouse SQL: scalar aggregate with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "total_spans",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT count() AS value" +
+								" FROM signoz_traces.distributed_signoz_index_v3" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_datetime AND timestamp <= $end_datetime" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp",
+						},
+					},
+				},
+			},
+		},
+	},
+}

pkg/signoz/openapi.go

@@ -1,7 +1,10 @@
 package signoz
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
+	"net/http"
 	"os"
 	"reflect"
 
@@ -22,10 +25,13 @@ import (
 	"github.com/SigNoz/signoz/pkg/modules/promote"
 	"github.com/SigNoz/signoz/pkg/modules/session"
 	"github.com/SigNoz/signoz/pkg/modules/user"
+	"github.com/SigNoz/signoz/pkg/querier"
 	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
+	"github.com/gorilla/mux"
 	"github.com/swaggest/jsonschema-go"
 	"github.com/swaggest/openapi-go"
 	"github.com/swaggest/openapi-go/openapi3"
+	"gopkg.in/yaml.v2"
 )
 
 type OpenAPI struct {
@@ -57,6 +63,10 @@ func NewOpenAPI(ctx context.Context, instrumentation instrumentation.Instrumenta
 		return nil, err
 	}
 
+	// Register routes that live outside the APIServer modules
+	// so they are discovered by the OpenAPI walker.
+	registerQueryRoutes(apiserver.Router())
+
 	reflector := openapi3.NewReflector()
 	reflector.JSONSchemaReflector().DefaultOptions = append(reflector.JSONSchemaReflector().DefaultOptions, jsonschema.InterceptDefName(func(t reflect.Type, defaultDefName string) string {
 		if defaultDefName == "RenderSuccessResponse" {
@@ -90,10 +100,67 @@ func (openapi *OpenAPI) CreateAndWrite(path string) error {
 		return err
 	}
 
-	spec, err := openapi.reflector.Spec.MarshalYAML()
+	// The library's MarshalYAML does a JSON round-trip that converts all numbers
+	// to float64, causing large integers (e.g. epoch millisecond timestamps) to
+	// render in scientific notation (1.6409952e+12).
+	jsonData, err := openapi.reflector.Spec.MarshalJSON()
+	if err != nil {
+		return err
+	}
+
+	dec := json.NewDecoder(bytes.NewReader(jsonData))
+	dec.UseNumber()
+
+	var v any
+	if err := dec.Decode(&v); err != nil {
+		return err
+	}
+
+	convertJSONNumbers(v)
+
+	spec, err := yaml.Marshal(v)
 	if err != nil {
 		return err
 	}
 
 	return os.WriteFile(path, spec, 0o600)
 }
+
+// convertJSONNumbers recursively walks a decoded JSON structure and converts
+// json.Number values to int64 (preferred) or float64 so that YAML marshaling
+// renders them as plain numbers instead of quoted strings.
+func convertJSONNumbers(v interface{}) {
+	switch val := v.(type) {
+	case map[string]interface{}:
+		for k, elem := range val {
+			if n, ok := elem.(json.Number); ok {
+				if i, err := n.Int64(); err == nil {
+					val[k] = i
+				} else if f, err := n.Float64(); err == nil {
+					val[k] = f
+				}
+			} else {
+				convertJSONNumbers(elem)
+			}
+		}
+	case []interface{}:
+		for i, elem := range val {
+			if n, ok := elem.(json.Number); ok {
+				if i64, err := n.Int64(); err == nil {
+					val[i] = i64
+				} else if f, err := n.Float64(); err == nil {
+					val[i] = f
+				}
+			} else {
+				convertJSONNumbers(elem)
+			}
+		}
+	}
+}
+
+func registerQueryRoutes(router *mux.Router) {
+	router.Handle("/api/v5/query_range", handler.New(
+		func(http.ResponseWriter, *http.Request) {},
+		querier.QueryRangeV5OpenAPIDef,
+	)).Methods(http.MethodPost)
+}

pkg/telemetrymetrics/statement_builder.go

@@ -123,7 +123,7 @@ func (b *MetricQueryStatementBuilder) buildPipelineStatement(
 	origTimeAgg := query.Aggregations[0].TimeAggregation
 	origGroupBy := slices.Clone(query.GroupBy)
 
-	if query.Aggregations[0].SpaceAggregation.IsPercentile() &&
+	if (query.Aggregations[0].SpaceAggregation.IsPercentile() || query.Aggregations[0].SpaceAggregation == metrictypes.SpaceAggregationHistogramCount) &&
 		query.Aggregations[0].Type != metrictypes.ExpHistogramType {
 		// add le in the group by if doesn't exist
 		leExists := false
@@ -154,7 +154,11 @@ func (b *MetricQueryStatementBuilder) buildPipelineStatement(
 		}
 
 		// make the time aggregation rate and space aggregation sum
-		query.Aggregations[0].TimeAggregation = metrictypes.TimeAggregationRate
+		if query.Aggregations[0].SpaceAggregation.IsPercentile() {
+			query.Aggregations[0].TimeAggregation = metrictypes.TimeAggregationRate
+		} else {
+			query.Aggregations[0].TimeAggregation = metrictypes.TimeAggregationIncrease
+		}
 		query.Aggregations[0].SpaceAggregation = metrictypes.SpaceAggregationSum
 	}
 
@@ -524,7 +528,7 @@ func (b *MetricQueryStatementBuilder) buildSpatialAggregationCTE(
 		return "", nil, errors.Newf(
 			errors.TypeInvalidInput,
 			errors.CodeInvalidInput,
-			"invalid space aggregation, should be one of the following: [`sum`, `avg`, `min`, `max`, `count`, `p50`, `p75`, `p90`, `p95`, `p99`]",
+			"invalid space aggregation, should be one of the following: [`sum`, `avg`, `min`, `max`, `count`, `p50`, `p75`, `p90`, `p95`, `p99`, `histogram_count`]",
 		)
 	}
 	sb := sqlbuilder.NewSelectBuilder()
@@ -577,6 +581,34 @@ func (b *MetricQueryStatementBuilder) BuildFinalSelect(
 		sb.From("__spatial_aggregation_cte")
 		sb.GroupBy(querybuilder.GroupByKeys(query.GroupBy)...)
 		sb.GroupBy("ts")
+		if query.Having != nil && query.Having.Expression != "" {
+			rewriter := querybuilder.NewHavingExpressionRewriter()
+			rewrittenExpr := rewriter.RewriteForMetrics(query.Having.Expression, query.Aggregations)
+			sb.Having(rewrittenExpr)
+		}
+	} else if query.Aggregations[0].SpaceAggregation == metrictypes.SpaceAggregationHistogramCount {
+		sb.Select("ts")
+
+		for _, g := range query.GroupBy {
+			sb.SelectMore(fmt.Sprintf("`%s`", g.TelemetryFieldKey.Name))
+		}
+
+		switch query.Aggregations[0].SpaceAggregationParam.(type) {
+		case metrictypes.ComparisonSpaceAggregationParam:
+			aggQuery, err := AggregationQueryForHistogramCount(query.Aggregations[0].SpaceAggregationParam.(metrictypes.ComparisonSpaceAggregationParam))
+			if err != nil {
+				return nil, err
+			}
+			sb.SelectMore(aggQuery)
+		default:
+			return nil, errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, "no aggregation param provided for histogram count")
+		}
+
+		sb.From("__spatial_aggregation_cte")
+
+		sb.GroupBy(querybuilder.GroupByKeys(query.GroupBy)...)
+		sb.GroupBy("ts")
+
 		if query.Having != nil && query.Having.Expression != "" {
 			rewriter := querybuilder.NewHavingExpressionRewriter()
 			rewrittenExpr := rewriter.RewriteForMetrics(query.Having.Expression, query.Aggregations)

pkg/telemetrymetrics/tables.go

@@ -1,6 +1,7 @@
 package telemetrymetrics
 
 import (
+	"fmt"
 	"time"
 
 	"github.com/SigNoz/signoz/pkg/errors"
@@ -308,3 +309,17 @@ func AggregationColumnForSamplesTable(
 	}
 	return aggregationColumn, nil
 }
+
+func AggregationQueryForHistogramCount(params metrictypes.ComparisonSpaceAggregationParam) (string, error) {
+	histogramCountLimit := params.Limit
+
+	switch params.Operater {
+	case "<=":
+		return fmt.Sprintf("argMaxIf(value, toFloat64(le), toFloat64(le) <= %f) + (argMinIf(value, toFloat64(le), toFloat64(le) > %f) - argMaxIf(value, toFloat64(le), toFloat64(le) <= %f)) * (%f - maxIf(toFloat64(le), toFloat64(le) <= %f)) / (minIf(toFloat64(le), toFloat64(le) > %f) - maxIf(toFloat64(le), toFloat64(le) <= %f)) AS value", histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit), nil
+	case ">":
+		return fmt.Sprintf("argMax(value, toFloat64(le)) - (argMaxIf(value, toFloat64(le), toFloat64(le) < %f) + (argMinIf(value, toFloat64(le), toFloat64(le) >= %f) - argMaxIf(value, toFloat64(le), toFloat64(le) < %f)) * (%f - maxIf(toFloat64(le), toFloat64(le) < %f)) / (minIf(toFloat64(le), toFloat64(le) >= %f) - maxIf(toFloat64(le), toFloat64(le) <= %f))) AS value", histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit, histogramCountLimit), nil
+	default:
+		return "", errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, "invalid space aggregation operator, should be one of the following: [`<=`, `>`]")
+	}
+
+}

pkg/types/metrictypes/metrictypes.go

@@ -2,6 +2,7 @@ package metrictypes
 
 import (
 	"database/sql/driver"
+	"fmt"
 	"strings"
 
 	"github.com/SigNoz/signoz/pkg/errors"
@@ -172,7 +173,6 @@ var (
 
 func (TimeAggregation) Enum() []any {
 	return []any{
-		TimeAggregationUnspecified,
 		TimeAggregationLatest,
 		TimeAggregationSum,
 		TimeAggregationAvg,
@@ -190,22 +190,22 @@ type SpaceAggregation struct {
 }
 
 var (
-	SpaceAggregationUnspecified  = SpaceAggregation{valuer.NewString("")}
-	SpaceAggregationSum          = SpaceAggregation{valuer.NewString("sum")}
-	SpaceAggregationAvg          = SpaceAggregation{valuer.NewString("avg")}
-	SpaceAggregationMin          = SpaceAggregation{valuer.NewString("min")}
-	SpaceAggregationMax          = SpaceAggregation{valuer.NewString("max")}
-	SpaceAggregationCount        = SpaceAggregation{valuer.NewString("count")}
-	SpaceAggregationPercentile50 = SpaceAggregation{valuer.NewString("p50")}
-	SpaceAggregationPercentile75 = SpaceAggregation{valuer.NewString("p75")}
-	SpaceAggregationPercentile90 = SpaceAggregation{valuer.NewString("p90")}
-	SpaceAggregationPercentile95 = SpaceAggregation{valuer.NewString("p95")}
-	SpaceAggregationPercentile99 = SpaceAggregation{valuer.NewString("p99")}
+	SpaceAggregationUnspecified    = SpaceAggregation{valuer.NewString("")}
+	SpaceAggregationSum            = SpaceAggregation{valuer.NewString("sum")}
+	SpaceAggregationAvg            = SpaceAggregation{valuer.NewString("avg")}
+	SpaceAggregationMin            = SpaceAggregation{valuer.NewString("min")}
+	SpaceAggregationMax            = SpaceAggregation{valuer.NewString("max")}
+	SpaceAggregationCount          = SpaceAggregation{valuer.NewString("count")}
+	SpaceAggregationPercentile50   = SpaceAggregation{valuer.NewString("p50")}
+	SpaceAggregationPercentile75   = SpaceAggregation{valuer.NewString("p75")}
+	SpaceAggregationPercentile90   = SpaceAggregation{valuer.NewString("p90")}
+	SpaceAggregationPercentile95   = SpaceAggregation{valuer.NewString("p95")}
+	SpaceAggregationPercentile99   = SpaceAggregation{valuer.NewString("p99")}
+	SpaceAggregationHistogramCount = SpaceAggregation{valuer.NewString("histogram_count")}
 )
 
 func (SpaceAggregation) Enum() []any {
 	return []any{
-		SpaceAggregationUnspecified,
 		SpaceAggregationSum,
 		SpaceAggregationAvg,
 		SpaceAggregationMin,
@@ -216,6 +216,7 @@ func (SpaceAggregation) Enum() []any {
 		SpaceAggregationPercentile90,
 		SpaceAggregationPercentile95,
 		SpaceAggregationPercentile99,
+		SpaceAggregationHistogramCount,
 	}
 }
 
@@ -258,3 +259,22 @@ type MetricTableHints struct {
 type MetricValueFilter struct {
 	Value float64
 }
+
+type SpaceAggregationParam interface {
+	StringValue() string
+}
+
+type NoSpaceAggregationParam struct{}
+
+func (_ NoSpaceAggregationParam) StringValue() string {
+	return "{}"
+}
+
+type ComparisonSpaceAggregationParam struct {
+	Operater string  `json:"operator"`
+	Limit    float64 `json:"limit"`
+}
+
+func (cso ComparisonSpaceAggregationParam) StringValue() string {
+	return fmt.Sprintf("{\"operator\": \"%s\", \"limit\": \"%f\"}", cso.Operater, cso.Limit)
+}

pkg/types/querybuildertypes/querybuildertypesv5/builder_elements.go

@@ -10,10 +10,35 @@ import (
 	"github.com/SigNoz/signoz/pkg/types/metrictypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type Step struct{ time.Duration }
 
+var _ jsonschema.Exposer = Step{}
+
+// JSONSchema returns a custom schema for Step that accepts either a duration string or a number (seconds).
+func (Step) JSONSchema() (jsonschema.Schema, error) {
+	s := jsonschema.Schema{}
+	s.WithDescription("Step interval. Accepts a Go duration string (e.g., \"60s\", \"1m\", \"1h\") or a number representing seconds (e.g., 60).")
+
+	strSchema := jsonschema.Schema{}
+	strSchema.WithType(jsonschema.String.Type())
+	strSchema.WithExamples("60s", "5m", "1h")
+	strSchema.WithDescription("Duration string (e.g., \"60s\", \"5m\", \"1h\").")
+
+	numSchema := jsonschema.Schema{}
+	numSchema.WithType(jsonschema.Number.Type())
+	numSchema.WithExamples(60, 300, 3600)
+	numSchema.WithDescription("Duration in seconds.")
+
+	s.OneOf = []jsonschema.SchemaOrBool{
+		strSchema.ToSchemaOrBool(),
+		numSchema.ToSchemaOrBool(),
+	}
+	return s, nil
+}
+
 func (s *Step) UnmarshalJSON(b []byte) error {
 	if len(b) == 0 {
 		return nil
@@ -181,6 +206,14 @@ var (
 	OrderDirectionDesc = OrderDirection{valuer.NewString("desc")}
 )
 
+// Enum returns the acceptable values for OrderDirection.
+func (OrderDirection) Enum() []any {
+	return []any{
+		OrderDirectionAsc,
+		OrderDirectionDesc,
+	}
+}
+
 var (
 	OrderDirectionMap = map[string]OrderDirection{
 		"asc":  OrderDirectionAsc,
@@ -203,6 +236,19 @@ var (
 	ReduceToMedian  = ReduceTo{valuer.NewString("median")}
 )
 
+// Enum returns the acceptable values for ReduceTo.
+func (ReduceTo) Enum() []any {
+	return []any{
+		ReduceToSum,
+		ReduceToCount,
+		ReduceToAvg,
+		ReduceToMin,
+		ReduceToMax,
+		ReduceToLast,
+		ReduceToMedian,
+	}
+}
+
 // FunctionReduceTo applies the reduceTo operator to a time series and returns a new series with the reduced value
 // reduceTo can be one of: last, sum, avg, min, max, count, median
 // if reduceTo is not recognized, the function returns the original series
@@ -400,6 +446,8 @@ type MetricAggregation struct {
 	TimeAggregation metrictypes.TimeAggregation `json:"timeAggregation"`
 	// space aggregation to apply to the query
 	SpaceAggregation metrictypes.SpaceAggregation `json:"spaceAggregation"`
+	// param for space aggregation if needed
+	SpaceAggregationParam metrictypes.SpaceAggregationParam `json:"spaceAggregationParam"`
 	// table hints to use for the query
 	TableHints *metrictypes.MetricTableHints `json:"-"`
 	// value filter to apply to the query
@@ -408,6 +456,40 @@ type MetricAggregation struct {
 	ReduceTo ReduceTo `json:"reduceTo,omitempty"`
 }
 
+func (m *MetricAggregation) UnmarshalJSON(data []byte) error {
+	type Alias MetricAggregation
+	aux := &struct {
+		SpaceAggregationParam json.RawMessage `json:"spaceAggregationParam"`
+		*Alias
+	}{
+		Alias: (*Alias)(m),
+	}
+
+	if err := json.Unmarshal(data, &aux); err != nil {
+		return err
+	}
+
+	// If no param provided
+	if len(aux.SpaceAggregationParam) == 0 || string(aux.SpaceAggregationParam) == "null" {
+		m.SpaceAggregationParam = metrictypes.NoSpaceAggregationParam{}
+		return nil
+	}
+
+	switch m.SpaceAggregation {
+	case metrictypes.SpaceAggregationHistogramCount:
+		var p metrictypes.ComparisonSpaceAggregationParam
+		if err := json.Unmarshal(aux.SpaceAggregationParam, &p); err != nil {
+			return err
+		}
+		m.SpaceAggregationParam = p
+
+	default:
+		m.SpaceAggregationParam = metrictypes.NoSpaceAggregationParam{}
+	}
+
+	return nil
+}
+
 // Copy creates a deep copy of MetricAggregation
 func (m MetricAggregation) Copy() MetricAggregation {
 	c := m

pkg/types/querybuildertypes/querybuildertypesv5/functions.go

@@ -36,6 +36,30 @@ var (
 	FunctionNameFillZero      = FunctionName{valuer.NewString("fillZero")}
 )
 
+// Enum returns the acceptable values for FunctionName.
+func (FunctionName) Enum() []any {
+	return []any{
+		FunctionNameCutOffMin,
+		FunctionNameCutOffMax,
+		FunctionNameClampMin,
+		FunctionNameClampMax,
+		FunctionNameAbsolute,
+		FunctionNameRunningDiff,
+		FunctionNameLog2,
+		FunctionNameLog10,
+		FunctionNameCumulativeSum,
+		FunctionNameEWMA3,
+		FunctionNameEWMA5,
+		FunctionNameEWMA7,
+		FunctionNameMedian3,
+		FunctionNameMedian5,
+		FunctionNameMedian7,
+		FunctionNameTimeShift,
+		FunctionNameAnomaly,
+		FunctionNameFillZero,
+	}
+}
+
 // Validate checks if the FunctionName is valid and one of the known types
 func (fn FunctionName) Validate() error {
 	validFunctions := []FunctionName{

pkg/types/querybuildertypes/querybuildertypesv5/join.go

@@ -16,6 +16,17 @@ var (
 	JoinTypeCross = JoinType{valuer.NewString("cross")}
 )
 
+// Enum returns the acceptable values for JoinType.
+func (JoinType) Enum() []any {
+	return []any{
+		JoinTypeInner,
+		JoinTypeLeft,
+		JoinTypeRight,
+		JoinTypeFull,
+		JoinTypeCross,
+	}
+}
+
 type QueryRef struct {
 	Name string `json:"name"`
 }

pkg/types/querybuildertypes/querybuildertypesv5/query.go

@@ -2,6 +2,8 @@ package querybuildertypesv5
 
 import (
 	"context"
+
+	"github.com/swaggest/jsonschema-go"
 )
 
 type Query interface {
@@ -29,4 +31,12 @@ type ExecStats struct {
 	StepIntervals map[string]uint64 `json:"stepIntervals,omitempty"`
 }
 
+var _ jsonschema.Preparer = &ExecStats{}
+
+// PrepareJSONSchema adds description to the ExecStats schema.
+func (e *ExecStats) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Execution statistics for the query, including rows scanned, bytes scanned, and duration.")
+	return nil
+}
+
 type TimeRange struct{ From, To uint64 } // ms since epoch

pkg/types/querybuildertypes/querybuildertypesv5/query_type.go

@@ -16,3 +16,17 @@ var (
 	QueryTypeClickHouseSQL = QueryType{valuer.NewString("clickhouse_sql")}
 	QueryTypePromQL        = QueryType{valuer.NewString("promql")}
 )
+
+// Enum returns the acceptable values for QueryType.
+func (QueryType) Enum() []any {
+	return []any{
+		QueryTypeBuilder,
+		QueryTypeFormula,
+		// Not yet supported.
+		// QueryTypeSubQuery,
+		// QueryTypeJoin,
+		QueryTypeTraceOperator,
+		QueryTypeClickHouseSQL,
+		QueryTypePromQL,
+	}
+}

pkg/types/querybuildertypes/querybuildertypesv5/req.go

@@ -9,6 +9,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/types/metrictypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type QueryEnvelope struct {
@@ -18,6 +19,71 @@ type QueryEnvelope struct {
 	Spec any `json:"spec"`
 }
 
+// queryEnvelopeBuilderTrace is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=traces.
+type queryEnvelopeBuilderTrace struct {
+	Type QueryType                           `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[TraceAggregation] `json:"spec" description:"The trace builder query specification."`
+}
+
+// queryEnvelopeBuilderLog is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=logs.
+type queryEnvelopeBuilderLog struct {
+	Type QueryType                         `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[LogAggregation] `json:"spec" description:"The log builder query specification."`
+}
+
+// queryEnvelopeBuilderMetric is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=metrics.
+type queryEnvelopeBuilderMetric struct {
+	Type QueryType                            `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[MetricAggregation] `json:"spec" description:"The metric builder query specification."`
+}
+
+// queryEnvelopeFormula is the OpenAPI schema for a QueryEnvelope with type=builder_formula.
+type queryEnvelopeFormula struct {
+	Type QueryType           `json:"type" description:"The type of the query."`
+	Spec QueryBuilderFormula `json:"spec" description:"The formula specification."`
+}
+
+// queryEnvelopeJoin is the OpenAPI schema for a QueryEnvelope with type=builder_join.
+// type queryEnvelopeJoin struct {
+// 	Type QueryType        `json:"type" description:"The type of the query."`
+// 	Spec QueryBuilderJoin `json:"spec" description:"The join specification."`
+// }
+
+// queryEnvelopeTraceOperator is the OpenAPI schema for a QueryEnvelope with type=builder_trace_operator.
+type queryEnvelopeTraceOperator struct {
+	Type QueryType                 `json:"type" description:"The type of the query."`
+	Spec QueryBuilderTraceOperator `json:"spec" description:"The trace operator specification."`
+}
+
+// queryEnvelopePromQL is the OpenAPI schema for a QueryEnvelope with type=promql.
+type queryEnvelopePromQL struct {
+	Type QueryType `json:"type" description:"The type of the query."`
+	Spec PromQuery `json:"spec" description:"The PromQL query specification."`
+}
+
+// queryEnvelopeClickHouseSQL is the OpenAPI schema for a QueryEnvelope with type=clickhouse_sql.
+type queryEnvelopeClickHouseSQL struct {
+	Type QueryType       `json:"type" description:"The type of the query."`
+	Spec ClickHouseQuery `json:"spec" description:"The ClickHouse SQL query specification."`
+}
+
+var _ jsonschema.OneOfExposer = QueryEnvelope{}
+
+// JSONSchemaOneOf returns the oneOf variants for the QueryEnvelope discriminated union.
+// Each variant represents a different query type with its corresponding spec schema.
+func (QueryEnvelope) JSONSchemaOneOf() []any {
+	return []any{
+		queryEnvelopeBuilderTrace{},
+		queryEnvelopeBuilderLog{},
+		queryEnvelopeBuilderMetric{},
+		queryEnvelopeFormula{},
+		// queryEnvelopeJoin{},
+		queryEnvelopeTraceOperator{},
+		queryEnvelopePromQL{},
+		queryEnvelopeClickHouseSQL{},
+	}
+}
+
 // implement custom json unmarshaler for the QueryEnvelope
 func (q *QueryEnvelope) UnmarshalJSON(data []byte) error {
 	var shadow struct {
@@ -130,6 +196,12 @@ type CompositeQuery struct {
 	Queries []QueryEnvelope `json:"queries"`
 }
 
+// PrepareJSONSchema adds description to the CompositeQuery schema.
+func (c *CompositeQuery) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Composite query containing one or more query envelopes. Each query envelope specifies its type and corresponding spec.")
+	return nil
+}
+
 // UnmarshalJSON implements custom JSON unmarshaling to provide better error messages
 func (c *CompositeQuery) UnmarshalJSON(data []byte) error {
 	type Alias CompositeQuery
@@ -192,6 +264,16 @@ var (
 	TextBoxVariableType = VariableType{valuer.NewString("text")}
 )
 
+// Enum returns the acceptable values for VariableType.
+func (VariableType) Enum() []any {
+	return []any{
+		QueryVariableType,
+		DynamicVariableType,
+		CustomVariableType,
+		TextBoxVariableType,
+	}
+}
+
 type VariableItem struct {
 	Type  VariableType `json:"type"`
 	Value any          `json:"value"`
@@ -217,6 +299,12 @@ type QueryRangeRequest struct {
 	FormatOptions *FormatOptions `json:"formatOptions,omitempty"`
 }
 
+// PrepareJSONSchema adds description to the QueryRangeRequest schema.
+func (q *QueryRangeRequest) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Request body for the v5 query range endpoint. Supports builder queries (traces, logs, metrics), formulas, joins, trace operators, PromQL, and ClickHouse SQL queries.")
+	return nil
+}
+
 func (r *QueryRangeRequest) StepIntervalForQuery(name string) int64 {
 	stepsMap := make(map[string]int64)
 	for _, query := range r.CompositeQuery.Queries {

pkg/types/querybuildertypes/querybuildertypesv5/request_type.go

@@ -30,3 +30,15 @@ var (
 func (r RequestType) IsAggregation() bool {
 	return r == RequestTypeTimeSeries || r == RequestTypeScalar || r == RequestTypeDistribution
 }
+
+// Enum implements jsonschema.Enum; returns the acceptable values for RequestType.
+func (RequestType) Enum() []any {
+	return []any{
+		RequestTypeScalar,
+		RequestTypeTimeSeries,
+		RequestTypeRaw,
+		RequestTypeRawStream,
+		RequestTypeTrace,
+		// RequestTypeDistribution,
+	}
+}

pkg/types/querybuildertypes/querybuildertypesv5/resp.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type QBEvent struct {
@@ -42,6 +43,17 @@ type QueryData struct {
 	Results []any `json:"results"`
 }
 
+var _ jsonschema.OneOfExposer = QueryData{}
+
+// JSONSchemaOneOf documents the polymorphic result types in QueryData.Results.
+func (QueryData) JSONSchemaOneOf() []any {
+	return []any{
+		TimeSeriesData{},
+		ScalarData{},
+		RawData{},
+	}
+}
+
 type QueryRangeResponse struct {
 	Type RequestType `json:"type"`
 	Data QueryData   `json:"data"`
@@ -52,6 +64,14 @@ type QueryRangeResponse struct {
 	QBEvent *QBEvent `json:"-"`
 }
 
+var _ jsonschema.Preparer = &QueryRangeResponse{}
+
+// PrepareJSONSchema adds description to the QueryRangeResponse schema.
+func (q *QueryRangeResponse) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Response from the v5 query range endpoint. The data.results array contains typed results depending on the requestType: TimeSeriesData for time_series, ScalarData for scalar, or RawData for raw requests.")
+	return nil
+}
+
 type TimeSeriesData struct {
 	QueryName    string               `json:"queryName"`
 	Aggregations []*AggregationBucket `json:"aggregations"`
@@ -159,6 +179,14 @@ var (
 	ColumnTypeAggregation = ColumnType{valuer.NewString("aggregation")}
 )
 
+// Enum returns the acceptable values for ColumnType.
+func (ColumnType) Enum() []any {
+	return []any{
+		ColumnTypeGroup,
+		ColumnTypeAggregation,
+	}
+}
+
 type ColumnDescriptor struct {
 	telemetrytypes.TelemetryFieldKey
 	QueryName        string `json:"queryName"`

pkg/types/telemetrytypes/field_context.go

@@ -172,3 +172,18 @@ func isContextValidForSignal(ctx FieldContext, signal Signal) bool {
 	}
 	return true
 }
+
+// Enum returns the acceptable values for FieldContext.
+func (FieldContext) Enum() []any {
+	return []any{
+		FieldContextMetric,
+		FieldContextLog,
+		FieldContextSpan,
+		// FieldContextTrace,
+		FieldContextResource,
+		// FieldContextScope,
+		FieldContextAttribute,
+		// FieldContextEvent,
+		FieldContextBody,
+	}
+}

pkg/types/telemetrytypes/field_datatype.go

@@ -177,3 +177,19 @@ func (f FieldDataType) TagDataType() string {
 		return "string"
 	}
 }
+
+// Enum returns the acceptable values for FieldDataType.
+func (FieldDataType) Enum() []any {
+	return []any{
+		FieldDataTypeString,
+		FieldDataTypeBool,
+		FieldDataTypeFloat64,
+		FieldDataTypeInt64,
+		FieldDataTypeNumber,
+		// FieldDataTypeArrayString,
+		// FieldDataTypeArrayFloat64,
+		// FieldDataTypeArrayBool,
+		// FieldDataTypeArrayInt64,
+		// FieldDataTypeArrayNumber,
+	}
+}

pkg/types/telemetrytypes/signal.go

@@ -12,3 +12,12 @@ var (
 	SignalMetrics     = Signal{valuer.NewString("metrics")}
 	SignalUnspecified = Signal{valuer.NewString("")}
 )
+
+// Enum returns the acceptable values for Signal.
+func (Signal) Enum() []any {
+	return []any{
+		SignalTraces,
+		SignalLogs,
+		SignalMetrics,
+	}
+}

pkg/types/telemetrytypes/source.go

@@ -10,3 +10,10 @@ var (
 	SourceMeter       = Source{valuer.NewString("meter")}
 	SourceUnspecified = Source{valuer.NewString("")}
 )
+
+// Enum returns the acceptable values for Source.
+func (Source) Enum() []any {
+	return []any{
+		SourceMeter,
+	}
+}