fix: move interface to telemetrystore

docs/api/openapi.yml

@@ -5943,6 +5943,25 @@ components:
       - asc
       - desc
       type: string
+    Querybuildertypesv5PreviewStatement:
+      properties:
+        db.statement.args:
+          items: {}
+          type: array
+        db.statement.query:
+          type: string
+        estimate:
+          items:
+            $ref: '#/components/schemas/TelemetrystoreEstimateEntry'
+          type: array
+        granules:
+          $ref: '#/components/schemas/TelemetrystoreGranules'
+      required:
+      - db.statement.query
+      - db.statement.args
+      - estimate
+      - granules
+      type: object
     Querybuildertypesv5PromQuery:
       properties:
         disabled:
@@ -6263,6 +6282,40 @@ components:
       required:
       - type
       type: object
+    Querybuildertypesv5QueryPreview:
+      properties:
+        error: {}
+        statements:
+          items:
+            $ref: '#/components/schemas/Querybuildertypesv5PreviewStatement'
+          type: array
+        valid:
+          type: boolean
+        warnings:
+          items:
+            type: string
+          type: array
+      required:
+      - valid
+      - error
+      - warnings
+      - statements
+      type: object
+    Querybuildertypesv5QueryRangePreviewResponse:
+      description: Response from the v5 query range preview (dry-run) endpoint. For
+        each query in the composite query, returns the underlying ClickHouse statement(s)
+        it renders to without executing them (one per PromQL metric selector; exactly
+        one for builder/ClickHouse/trace-operator queries), with the optional EXPLAIN
+        ESTIMATE and granule analysis attached per statement when requested.
+      properties:
+        compositeQuery:
+          additionalProperties:
+            $ref: '#/components/schemas/Querybuildertypesv5QueryPreview'
+          nullable: true
+          type: object
+      required:
+      - compositeQuery
+      type: object
     Querybuildertypesv5QueryRangeRequest:
       description: Request body for the v5 query range endpoint. Supports builder
         queries (traces, logs, metrics), formulas, joins, trace operators, PromQL,
@@ -7613,6 +7666,96 @@ components:
       - key
       - value
       type: object
+    TelemetrystoreEstimateEntry:
+      properties:
+        database:
+          type: string
+        marks:
+          format: int64
+          type: integer
+        parts:
+          format: int64
+          type: integer
+        rows:
+          format: int64
+          type: integer
+        table:
+          type: string
+      required:
+      - database
+      - table
+      - parts
+      - rows
+      - marks
+      type: object
+    TelemetrystoreGranules:
+      nullable: true
+      properties:
+        initial:
+          format: int64
+          type: integer
+        reads:
+          items:
+            $ref: '#/components/schemas/TelemetrystoreMergeTreeRead'
+          type: array
+        selected:
+          format: int64
+          type: integer
+        skipped:
+          format: int64
+          type: integer
+      required:
+      - initial
+      - selected
+      - skipped
+      - reads
+      type: object
+    TelemetrystoreIndexStep:
+      properties:
+        condition:
+          type: string
+        initialGranules:
+          format: int64
+          type: integer
+        initialParts:
+          format: int64
+          type: integer
+        keys:
+          items:
+            type: string
+          type: array
+        name:
+          type: string
+        selectedGranules:
+          format: int64
+          type: integer
+        selectedParts:
+          format: int64
+          type: integer
+        type:
+          type: string
+      required:
+      - type
+      - name
+      - keys
+      - condition
+      - initialParts
+      - selectedParts
+      - initialGranules
+      - selectedGranules
+      type: object
+    TelemetrystoreMergeTreeRead:
+      properties:
+        steps:
+          items:
+            $ref: '#/components/schemas/TelemetrystoreIndexStep'
+          type: array
+        table:
+          type: string
+      required:
+      - table
+      - steps
+      type: object
     TelemetrytypesFieldContext:
       enum:
       - metric
@@ -22526,6 +22669,75 @@ paths:
       summary: Query range
       tags:
       - querier
+  /api/v5/query_range/preview:
+    post:
+      deprecated: false
+      description: 'Validate a composite query without executing it. Accepts the same
+        payload as the query range endpoint. By default (verbose=true) returns, for
+        each query, the rendered underlying ClickHouse statement(s) with each statement''s
+        EXPLAIN ESTIMATE (per-table parts/rows/marks) and granule index analysis (candidate/surviving
+        granules and the per-index pruning funnel). Pass ?verbose=false for the lightweight
+        per-query verdict (valid/error/warnings) with no rendered SQL and no ClickHouse
+        round trips. Intended for agentic/dry-run consumption: per-query errors are
+        reported in the response rather than failing the whole request.'
+      operationId: QueryRangePreviewV5
+      parameters:
+      - in: query
+        name: verbose
+        schema:
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Querybuildertypesv5QueryRangeRequest'
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Querybuildertypesv5QueryRangePreviewResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: Query range preview
+      tags:
+      - querier
   /api/v5/substitute_vars:
     post:
       deprecated: false

ee/querier/handler.go

@@ -101,6 +101,10 @@ func (h *handler) QueryRange(rw http.ResponseWriter, req *http.Request) {
 	h.community.QueryRange(rw, req)
 }
 
+func (h *handler) QueryRangePreview(rw http.ResponseWriter, req *http.Request) {
+	h.community.QueryRangePreview(rw, req)
+}
+
 func (h *handler) QueryRawStream(rw http.ResponseWriter, req *http.Request) {
 	h.community.QueryRawStream(rw, req)
 }

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

@@ -12,6 +12,8 @@ import type {
 } from 'react-query';
 
 import type {
+	QueryRangePreviewV5200,
+	QueryRangePreviewV5Params,
 	QueryRangeV5200,
 	Querybuildertypesv5QueryRangeRequestDTO,
 	RenderErrorResponseDTO,
@@ -104,6 +106,107 @@ export const useQueryRangeV5 = <
 > => {
 	return useMutation(getQueryRangeV5MutationOptions(options));
 };
+/**
+ * Validate a composite query without executing it. Accepts the same payload as the query range endpoint. By default (verbose=true) returns, for each query, the rendered underlying ClickHouse statement(s) with each statement's EXPLAIN ESTIMATE (per-table parts/rows/marks) and granule index analysis (candidate/surviving granules and the per-index pruning funnel). Pass ?verbose=false for the lightweight per-query verdict (valid/error/warnings) with no rendered SQL and no ClickHouse round trips. Intended for agentic/dry-run consumption: per-query errors are reported in the response rather than failing the whole request.
+ * @summary Query range preview
+ */
+export const queryRangePreviewV5 = (
+	querybuildertypesv5QueryRangeRequestDTO?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>,
+	params?: QueryRangePreviewV5Params,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<QueryRangePreviewV5200>({
+		url: `/api/v5/query_range/preview`,
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		data: querybuildertypesv5QueryRangeRequestDTO,
+		params,
+		signal,
+	});
+};
+
+export const getQueryRangePreviewV5MutationOptions = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangePreviewV5>>,
+		TError,
+		{
+			data?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>;
+			params?: QueryRangePreviewV5Params;
+		},
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof queryRangePreviewV5>>,
+	TError,
+	{
+		data?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>;
+		params?: QueryRangePreviewV5Params;
+	},
+	TContext
+> => {
+	const mutationKey = ['queryRangePreviewV5'];
+	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 queryRangePreviewV5>>,
+		{
+			data?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>;
+			params?: QueryRangePreviewV5Params;
+		}
+	> = (props) => {
+		const { data, params } = props ?? {};
+
+		return queryRangePreviewV5(data, params);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type QueryRangePreviewV5MutationResult = NonNullable<
+	Awaited<ReturnType<typeof queryRangePreviewV5>>
+>;
+export type QueryRangePreviewV5MutationBody =
+	| BodyType<Querybuildertypesv5QueryRangeRequestDTO>
+	| undefined;
+export type QueryRangePreviewV5MutationError =
+	ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Query range preview
+ */
+export const useQueryRangePreviewV5 = <
+	TError = ErrorType<RenderErrorResponseDTO>,
+	TContext = unknown,
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangePreviewV5>>,
+		TError,
+		{
+			data?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>;
+			params?: QueryRangePreviewV5Params;
+		},
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof queryRangePreviewV5>>,
+	TError,
+	{
+		data?: BodyType<Querybuildertypesv5QueryRangeRequestDTO>;
+		params?: QueryRangePreviewV5Params;
+	},
+	TContext
+> => {
+	return useMutation(getQueryRangePreviewV5MutationOptions(options));
+};
 /**
  * Replace variables in a query
  * @summary Replace variables

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -7339,6 +7339,125 @@ export interface Querybuildertypesv5FormatOptionsDTO {
 	formatTableResultForUI?: boolean;
 }
 
+export interface TelemetrystoreEstimateEntryDTO {
+	/**
+	 * @type string
+	 */
+	database: string;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	marks: number;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	parts: number;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	rows: number;
+	/**
+	 * @type string
+	 */
+	table: string;
+}
+
+export interface TelemetrystoreIndexStepDTO {
+	/**
+	 * @type string
+	 */
+	condition: string;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	initialGranules: number;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	initialParts: number;
+	/**
+	 * @type array
+	 */
+	keys: string[];
+	/**
+	 * @type string
+	 */
+	name: string;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	selectedGranules: number;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	selectedParts: number;
+	/**
+	 * @type string
+	 */
+	type: string;
+}
+
+export interface TelemetrystoreMergeTreeReadDTO {
+	/**
+	 * @type array
+	 */
+	steps: TelemetrystoreIndexStepDTO[];
+	/**
+	 * @type string
+	 */
+	table: string;
+}
+
+export type TelemetrystoreGranulesDTOAnyOf = {
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	initial: number;
+	/**
+	 * @type array
+	 */
+	reads: TelemetrystoreMergeTreeReadDTO[];
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	selected: number;
+	/**
+	 * @type integer
+	 * @format int64
+	 */
+	skipped: number;
+};
+
+/**
+ * @nullable
+ */
+export type TelemetrystoreGranulesDTO = TelemetrystoreGranulesDTOAnyOf | null;
+
+export interface Querybuildertypesv5PreviewStatementDTO {
+	/**
+	 * @type array
+	 */
+	'db.statement.args': unknown[];
+	/**
+	 * @type string
+	 */
+	'db.statement.query': string;
+	/**
+	 * @type array
+	 */
+	estimate: TelemetrystoreEstimateEntryDTO[];
+	granules: TelemetrystoreGranulesDTO | null;
+}
+
 export interface Querybuildertypesv5TimeSeriesDataDTO {
 	/**
 	 * @type array,null
@@ -7420,6 +7539,41 @@ export type Querybuildertypesv5QueryDataDTO =
 			results?: unknown[] | null;
 	  });
 
+export interface Querybuildertypesv5QueryPreviewDTO {
+	error: unknown;
+	/**
+	 * @type array
+	 */
+	statements: Querybuildertypesv5PreviewStatementDTO[];
+	/**
+	 * @type boolean
+	 */
+	valid: boolean;
+	/**
+	 * @type array
+	 */
+	warnings: string[];
+}
+
+export type Querybuildertypesv5QueryRangePreviewResponseDTOCompositeQueryAnyOf =
+	{ [key: string]: Querybuildertypesv5QueryPreviewDTO };
+
+/**
+ * @nullable
+ */
+export type Querybuildertypesv5QueryRangePreviewResponseDTOCompositeQuery =
+	Querybuildertypesv5QueryRangePreviewResponseDTOCompositeQueryAnyOf | null;
+
+/**
+ * Response from the v5 query range preview (dry-run) endpoint. For each query in the composite query, returns the underlying ClickHouse statement(s) it renders to without executing them (one per PromQL metric selector; exactly one for builder/ClickHouse/trace-operator queries), with the optional EXPLAIN ESTIMATE and granule analysis attached per statement when requested.
+ */
+export interface Querybuildertypesv5QueryRangePreviewResponseDTO {
+	/**
+	 * @type object,null
+	 */
+	compositeQuery: Querybuildertypesv5QueryRangePreviewResponseDTOCompositeQuery;
+}
+
 export enum Querybuildertypesv5VariableTypeDTO {
 	query = 'query',
 	dynamic = 'dynamic',
@@ -11182,6 +11336,22 @@ export type QueryRangeV5200 = {
 	status: string;
 };
 
+export type QueryRangePreviewV5Params = {
+	/**
+	 * @type string
+	 * @description undefined
+	 */
+	verbose?: string;
+};
+
+export type QueryRangePreviewV5200 = {
+	data: Querybuildertypesv5QueryRangePreviewResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type ReplaceVariables200 = {
 	data: Querybuildertypesv5QueryRangeRequestDTO;
 	/**

pkg/apiserver/signozapiserver/querier.go

@@ -451,6 +451,23 @@ func (provider *provider) addQuerierRoutes(router *mux.Router) error {
 		return err
 	}
 
+	if err := router.Handle("/api/v5/query_range/preview", handler.New(provider.authzMiddleware.ViewAccess(provider.querierHandler.QueryRangePreview), handler.OpenAPIDef{
+		ID:                  "QueryRangePreviewV5",
+		Tags:                []string{"querier"},
+		Summary:             "Query range preview",
+		Description:         "Validate a composite query without executing it. Accepts the same payload as the query range endpoint. By default (verbose=true) returns, for each query, the rendered underlying ClickHouse statement(s) with each statement's EXPLAIN ESTIMATE (per-table parts/rows/marks) and granule index analysis (candidate/surviving granules and the per-index pruning funnel). Pass ?verbose=false for the lightweight per-query verdict (valid/error/warnings) with no rendered SQL and no ClickHouse round trips. Intended for agentic/dry-run consumption: per-query errors are reported in the response rather than failing the whole request.",
+		Request:             new(qbtypes.QueryRangeRequest),
+		RequestQuery:        new(qbtypes.QueryRangePreviewParams),
+		RequestContentType:  "application/json",
+		Response:            new(qbtypes.QueryRangePreviewResponse),
+		ResponseContentType: "application/json",
+		SuccessStatusCode:   http.StatusOK,
+		ErrorStatusCodes:    []int{http.StatusBadRequest},
+		SecuritySchemes:     newSecuritySchemes(types.RoleViewer),
+	})).Methods(http.MethodPost).GetError(); err != nil {
+		return err
+	}
+
 	if err := router.Handle("/api/v5/substitute_vars", handler.New(provider.authzMiddleware.ViewAccess(provider.querierHandler.ReplaceVariables), handler.OpenAPIDef{
 		ID:                  "ReplaceVariables",
 		Tags:                []string{"querier"},

pkg/prometheus/clickhouseprometheus/capture.go

@@ -0,0 +1,88 @@
+package clickhouseprometheus
+
+import (
+	"context"
+	"sync"
+
+	"github.com/SigNoz/signoz/pkg/prometheus"
+	"github.com/prometheus/prometheus/prompb"
+	"github.com/prometheus/prometheus/storage"
+)
+
+// statementRecorder collects the statements a PromQL evaluation would run.
+// Safe for concurrent use: the engine may Select selectors concurrently.
+type statementRecorder struct {
+	mu         sync.Mutex
+	statements []prometheus.CapturedStatement
+}
+
+func (r *statementRecorder) record(query string, args []any) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.statements = append(r.statements, prometheus.CapturedStatement{Query: query, Args: args})
+}
+
+func (r *statementRecorder) Statements() []prometheus.CapturedStatement {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]prometheus.CapturedStatement, len(r.statements))
+	copy(out, r.statements)
+	return out
+}
+
+// captureClient builds the same SQL as the real client but records it and
+// returns an empty result instead of executing.
+type captureClient struct {
+	*client
+	recorder *statementRecorder
+}
+
+func (c *captureClient) Read(ctx context.Context, query *prompb.Query, _ bool) (storage.SeriesSet, error) {
+	// Raw-SQL passthrough ({job="rawsql", query="..."}): record the raw query.
+	if len(query.Matchers) == 2 {
+		var hasJob bool
+		var queryString string
+		for _, m := range query.Matchers {
+			if m.Type == prompb.LabelMatcher_EQ && m.Name == "job" && m.Value == "rawsql" {
+				hasJob = true
+			}
+			if m.Type == prompb.LabelMatcher_EQ && m.Name == "query" {
+				queryString = m.Value
+			}
+		}
+		if hasJob && queryString != "" {
+			c.recorder.record(queryString, nil)
+			return storage.EmptySeriesSet(), nil
+		}
+	}
+
+	var metricName string
+	for _, matcher := range query.Matchers {
+		if matcher.Name == "__name__" {
+			metricName = matcher.Value
+		}
+	}
+
+	// Build the executing path's queries, but only record them.
+	subQuery, args, err := c.queryToClickhouseQuery(ctx, query, metricName, true)
+	if err != nil {
+		return nil, err
+	}
+	samplesQuery, samplesArgs := buildSamplesQuery(int64(query.StartTimestampMs), int64(query.EndTimestampMs), metricName, subQuery, args)
+	c.recorder.record(samplesQuery, samplesArgs)
+
+	return storage.EmptySeriesSet(), nil
+}
+
+// captureQueryable adapts the capturing read client to storage.Queryable.
+type captureQueryable struct {
+	inner storage.SampleAndChunkQueryable
+}
+
+func (c captureQueryable) Querier(mint, maxt int64) (storage.Querier, error) {
+	querier, err := c.inner.Querier(mint, maxt)
+	if err != nil {
+		return nil, err
+	}
+	return storage.NewMergeQuerier(nil, []storage.Querier{querier}, storage.ChainedSeriesMerge), nil
+}

pkg/prometheus/clickhouseprometheus/client.go

@@ -204,8 +204,9 @@ func (client *client) getFingerprintsFromClickhouseQuery(ctx context.Context, qu
 	return fingerprints, nil
 }
 
-func (client *client) querySamples(ctx context.Context, start int64, end int64, fingerprints map[uint64][]prompb.Label, metricName string, subQuery string, args []any) ([]*prompb.TimeSeries, error) {
-	ctx = client.withClickhousePrometheusContext(ctx, "querySamples")
+// buildSamplesQuery renders the samples SQL (and args) that fetches data
+// points for the series selected by subQuery.
+func buildSamplesQuery(start int64, end int64, metricName string, subQuery string, args []any) (string, []any) {
 	argCount := len(args)
 
 	query := fmt.Sprintf(`
@@ -217,6 +218,13 @@ func (client *client) querySamples(ctx context.Context, start int64, end int64,
 
 	allArgs := append([]any{metricName}, args...)
 	allArgs = append(allArgs, start, end)
+	return query, allArgs
+}
+
+func (client *client) querySamples(ctx context.Context, start int64, end int64, fingerprints map[uint64][]prompb.Label, metricName string, subQuery string, args []any) ([]*prompb.TimeSeries, error) {
+	ctx = client.withClickhousePrometheusContext(ctx, "querySamples")
+
+	query, allArgs := buildSamplesQuery(start, end, metricName, subQuery, args)
 
 	rows, err := client.telemetryStore.ClickhouseDB().Query(ctx, query, allArgs...)
 	if err != nil {

pkg/prometheus/clickhouseprometheus/client_query_test.go

@@ -5,8 +5,8 @@ import (
 	"sort"
 	"testing"
 
-	"github.com/SigNoz/signoz/pkg/telemetrystore/telemetrystoretest"
 	cmock "github.com/SigNoz/clickhouse-go-mock"
+	"github.com/SigNoz/signoz/pkg/telemetrystore/telemetrystoretest"
 	"github.com/stretchr/testify/require"
 
 	"github.com/DATA-DOG/go-sqlmock"

pkg/prometheus/clickhouseprometheus/provider.go

@@ -64,3 +64,15 @@ func (provider *provider) Querier(mint, maxt int64) (storage.Querier, error) {
 
 	return storage.NewMergeQuerier(nil, []storage.Querier{querier}, storage.ChainedSeriesMerge), nil
 }
+
+// CapturingStorage implements prometheus.StatementCapturer. Uses a fresh
+// recorder per call so concurrent dry-runs don't share state.
+func (provider *provider) CapturingStorage() (storage.Queryable, prometheus.StatementRecorder) {
+	recorder := &statementRecorder{}
+	capture := &captureClient{
+		client:   &client{settings: provider.settings, telemetryStore: provider.telemetryStore},
+		recorder: recorder,
+	}
+	queryable := remote.NewSampleAndChunkQueryableClient(capture, labels.EmptyLabels(), []*labels.Matcher{}, false, stCallback)
+	return captureQueryable{inner: queryable}, recorder
+}

pkg/prometheus/prometheus.go

@@ -15,3 +15,23 @@ type Prometheus interface {
 	Storage() storage.Queryable
 	Parser() Parser
 }
+
+// CapturedStatement is one datastore statement a PromQL query would run,
+// captured without executing.
+type CapturedStatement struct {
+	Query string
+	Args  []any
+}
+
+// StatementRecorder reads back the statements captured against a capturing
+// Storage (see StatementCapturer).
+type StatementRecorder interface {
+	Statements() []CapturedStatement
+}
+
+// StatementCapturer is an optional Prometheus-provider capability, discovered
+// via type assertion: it returns a Storage that records each Select's statement
+// without executing it, plus a recorder to read them back.
+type StatementCapturer interface {
+	CapturingStorage() (storage.Queryable, StatementRecorder)
+}

pkg/querier/api.go

@@ -73,6 +73,53 @@ func (handler *handler) QueryRange(rw http.ResponseWriter, req *http.Request) {
 
 	render.Success(rw, http.StatusOK, queryRangeResponse)
 }
+
+// QueryRangePreview is the dry-run counterpart of QueryRange: it validates and
+// renders each query without executing it.
+func (handler *handler) QueryRangePreview(rw http.ResponseWriter, req *http.Request) {
+	ctx := req.Context()
+	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{
+		instrumentationtypes.CodeNamespace:    "querier",
+		instrumentationtypes.CodeFunctionName: "QueryRangePreview",
+	})
+
+	claims, err := authtypes.ClaimsFromContext(ctx)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	var queryRangeRequest qbtypes.QueryRangeRequest
+	if err := json.NewDecoder(req.Body).Decode(&queryRangeRequest); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	// Validation is deferred to QueryRangePreview, which reports per-query
+	// errors instead of failing fast.
+
+	orgID, err := valuer.NewUUID(claims.OrgID)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	previewParams := qbtypes.QueryRangePreviewParams{Verbose: req.URL.Query().Get("verbose")}
+	previewOpts, err := previewParams.Validate()
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	preview, err := handler.querier.QueryRangePreview(ctx, orgID, &queryRangeRequest, previewOpts)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	render.Success(rw, http.StatusOK, preview)
+}
+
 func (handler *handler) QueryRawStream(rw http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 

pkg/querier/builder_query.go

@@ -34,6 +34,7 @@ type builderQuery[T any] struct {
 }
 
 var _ qbtypes.Query = (*builderQuery[any])(nil)
+var _ qbtypes.StatementProvider = (*builderQuery[any])(nil)
 
 func newBuilderQuery[T any](
 	logger *slog.Logger,
@@ -203,6 +204,11 @@ func (q *builderQuery[T]) isWindowList() bool {
 	return true
 }
 
+// Statement renders the SQL without executing it, for the preview path.
+func (q *builderQuery[T]) Statement(ctx context.Context) (*qbtypes.Statement, error) {
+	return q.stmtBuilder.Build(ctx, q.fromMS, q.toMS, q.kind, q.spec, q.variables)
+}
+
 func (q *builderQuery[T]) Execute(ctx context.Context) (*qbtypes.Result, error) {
 
 	// can we do window based pagination?

pkg/querier/clickhouse_query.go

@@ -32,6 +32,7 @@ type chSQLQuery struct {
 }
 
 var _ qbtypes.Query = (*chSQLQuery)(nil)
+var _ qbtypes.StatementProvider = (*chSQLQuery)(nil)
 
 func newchSQLQuery(
 	logger *slog.Logger,
@@ -99,6 +100,15 @@ func (q *chSQLQuery) renderVars(query string, vars map[string]qbtypes.VariableIt
 	return newQuery.String(), nil
 }
 
+// Statement renders the SQL without executing it, for the preview path.
+func (q *chSQLQuery) Statement(_ context.Context) (*qbtypes.Statement, error) {
+	rendered, err := q.renderVars(q.query.Query, q.vars, q.fromMS, q.toMS)
+	if err != nil {
+		return nil, err
+	}
+	return &qbtypes.Statement{Query: rendered, Args: q.args}, nil
+}
+
 func (q *chSQLQuery) Execute(ctx context.Context) (*qbtypes.Result, error) {
 	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{
 		instrumentationtypes.QueryDuration: instrumentationtypes.DurationBucket(q.fromMS, q.toMS),

pkg/querier/interfaces.go

@@ -14,6 +14,8 @@ type Querier interface {
 	QueryRange(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest) (*qbtypes.QueryRangeResponse, error)
 	QueryRawStream(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest, client *qbtypes.RawStream)
 	statsreporter.StatsCollector
+	// QueryRangePreview validates and renders the queries without executing them.
+	QueryRangePreview(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest, opts qbtypes.QueryRangePreviewOptions) (*qbtypes.QueryRangePreviewResponse, error)
 }
 
 // BucketCache is the interface for bucket-based caching.
@@ -26,6 +28,8 @@ type BucketCache interface {
 
 type Handler interface {
 	QueryRange(rw http.ResponseWriter, req *http.Request)
+	// QueryRangePreview is the dry-run endpoint: validate and render without executing.
+	QueryRangePreview(rw http.ResponseWriter, req *http.Request)
 	QueryRawStream(rw http.ResponseWriter, req *http.Request)
 	ReplaceVariables(rw http.ResponseWriter, req *http.Request)
 }

pkg/querier/preview.go

@@ -0,0 +1,338 @@
+package querier
+
+import (
+	"context"
+	"fmt"
+	"slices"
+	"strings"
+	"sync"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// QueryRangePreview validates and renders each query without executing it.
+// When opts.Verbose, it also attaches each statement's EXPLAIN ESTIMATE and
+// granule analysis.
+func (q *querier) QueryRangePreview(
+	ctx context.Context,
+	orgID valuer.UUID,
+	req *qbtypes.QueryRangeRequest,
+	opts qbtypes.QueryRangePreviewOptions,
+) (*qbtypes.QueryRangePreviewResponse, error) {
+
+	validationOpts, err := req.ValidateRequestScope()
+	if err != nil {
+		return nil, err
+	}
+
+	dependencyQueries, err := q.constructTraceOperatorDependencyMap(req.CompositeQuery.Queries)
+	if err != nil {
+		return nil, err
+	}
+
+	results := make(map[string]qbtypes.QueryPreview, len(req.CompositeQuery.Queries))
+
+	prepared := make(map[string]qbtypes.QueryPreview, len(req.CompositeQuery.Queries))
+	missingMetricQuerySet := make(map[string]bool)
+	for idx := range req.CompositeQuery.Queries {
+		name := req.CompositeQuery.Queries[idx].GetQueryName()
+		ps := qbtypes.QueryPreview{Warnings: []string{}, Statements: []qbtypes.PreviewStatement{}}
+
+		if vErr := req.CompositeQuery.Queries[idx].Validate(validationOpts...); vErr != nil {
+			ps.Error = vErr
+			prepared[name] = ps
+			continue
+		}
+
+		env := []qbtypes.QueryEnvelope{req.CompositeQuery.Queries[idx]}
+		ps.Warnings = append(ps.Warnings, q.adjustStepInterval(env, req.Start, req.End)...)
+
+		missingMetricQueries, metricWarnings, mErr := q.resolveMetricMetadata(ctx, orgID, env, req.Start, req.End)
+		if mErr != nil {
+			// Report this query's error but keep previewing the rest.
+			ps.Error = mErr
+		} else {
+			ps.Warnings = append(ps.Warnings, metricWarnings...)
+			if len(missingMetricQueries) > 0 {
+				missingMetricQuerySet[name] = true
+				if len(metricWarnings) == 0 {
+					if metricNames := missingMetricNames(env[0]); len(metricNames) > 0 {
+						ps.Warnings = append(ps.Warnings, fmt.Sprintf(
+							"query %q references metric(s) %s with no data available; it will return an empty result",
+							name, strings.Join(metricNames, ", ")))
+					}
+				}
+			}
+		}
+
+		req.CompositeQuery.Queries[idx] = env[0]
+		prepared[name] = ps
+	}
+
+	skip := make(map[string]bool, len(prepared))
+	for name, ps := range prepared {
+		if ps.Error != nil || missingMetricQuerySet[name] {
+			skip[name] = true
+		}
+	}
+	providers, buildErrs := q.buildPreviewProviders(req, dependencyQueries, missingMetricQuerySet, skip)
+
+	// Render each executing query's statement and collect the ClickHouse-bound
+	// analysis work to run concurrently.
+	var previewTasks []qbtypes.PreviewTask
+	for _, query := range req.CompositeQuery.Queries {
+		name := query.GetQueryName()
+		ps := prepared[name]
+
+		if ps.Error != nil {
+			results[name] = ps
+			continue
+		}
+		if missingMetricQuerySet[name] {
+			results[name] = ps
+			continue
+		}
+		if bErr := buildErrs[name]; bErr != nil {
+			ps.Error = bErr
+			results[name] = ps
+			continue
+		}
+
+		provider, ok := providers[name]
+		if !ok {
+			if !rendersStandaloneStatement(query.Type) {
+				ps.Warnings = append(ps.Warnings, fmt.Sprintf(
+					"query type %q has no standalone statement to preview; it is evaluated from the queries it references", query.Type.StringValue()))
+				results[name] = ps
+				continue
+			}
+			ps.Error = errors.NewInternalf(errors.CodeInternal, "query produced no provider")
+			results[name] = ps
+			continue
+		}
+
+		stmtProvider, ok := provider.(qbtypes.StatementProvider)
+		if !ok {
+			ps.Error = errors.NewInternalf(errors.CodeInternal, "query does not support preview")
+			results[name] = ps
+			continue
+		}
+
+		stmt, sErr := stmtProvider.Statement(ctx)
+		if sErr != nil {
+			ps.Error = sErr
+			results[name] = ps
+			continue
+		}
+
+		ps.Warnings = append(ps.Warnings, stmt.Warnings...)
+
+		if query.Type == qbtypes.QueryTypeClickHouseSQL {
+			if bindErr := q.telemetryStore.Plan(ctx, stmt.Query, stmt.Args...); bindErr != nil {
+				if errors.Ast(bindErr, errors.TypeInvalidInput) || errors.Ast(bindErr, errors.TypeNotFound) {
+					ps.Error = bindErr
+					results[name] = ps
+					continue
+				}
+				ps.Warnings = append(ps.Warnings, "could not validate ClickHouse SQL: "+bindErr.Error())
+			}
+		}
+
+		if !opts.Verbose {
+			results[name] = ps
+			continue
+		}
+
+		if query.Type == qbtypes.QueryTypePromQL {
+			if pq, ok := provider.(*promqlQuery); ok {
+				sqlStmts, pErr := pq.PreviewStatements(ctx)
+				if pErr != nil {
+					ps.Warnings = append(ps.Warnings, "could not render underlying ClickHouse SQL: "+pErr.Error())
+				} else {
+					for _, s := range sqlStmts {
+						ps.Statements = append(ps.Statements, qbtypes.PreviewStatement{Query: s.Query, Args: orEmpty(s.Args), Estimate: []telemetrystore.EstimateEntry{}})
+					}
+				}
+			}
+		} else {
+			ps.Statements = []qbtypes.PreviewStatement{{Query: stmt.Query, Args: orEmpty(stmt.Args), Estimate: []telemetrystore.EstimateEntry{}}}
+		}
+
+		results[name] = ps
+
+		for j := range ps.Statements {
+			previewTasks = append(previewTasks, qbtypes.PreviewTask{Name: name, StmtIdx: j, Query: ps.Statements[j].Query, Args: ps.Statements[j].Args})
+		}
+	}
+
+	q.runPreviewTasks(ctx, previewTasks, results)
+
+	return &qbtypes.QueryRangePreviewResponse{
+		CompositeQuery: results,
+	}, nil
+}
+
+// missingMetricNames returns the distinct metric names referenced by a metric
+// builder query, or nil for a non-metric query.
+func missingMetricNames(env qbtypes.QueryEnvelope) []string {
+	spec, ok := env.Spec.(qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation])
+	if !ok {
+		return nil
+	}
+	names := make([]string, 0, len(spec.Aggregations))
+	for _, agg := range spec.Aggregations {
+		if agg.MetricName != "" && !slices.Contains(names, agg.MetricName) {
+			names = append(names, agg.MetricName)
+		}
+	}
+	return names
+}
+
+func (q *querier) buildPreviewProviders(
+	req *qbtypes.QueryRangeRequest,
+	dependencyQueries map[string]bool,
+	missingMetricQuerySet map[string]bool,
+	skip map[string]bool,
+) (providers map[string]qbtypes.Query, errs map[string]error) {
+	providers = make(map[string]qbtypes.Query)
+	errs = make(map[string]error)
+
+	event := &qbtypes.QBEvent{} // preview emits no analytics
+
+	for _, query := range req.CompositeQuery.Queries {
+		name := query.GetQueryName()
+		if skip[name] {
+			continue
+		}
+
+		sub := *req // shallow copy: only CompositeQuery and RequestType are swapped
+
+		// deps is the set buildQueries skips: empty for a standalone query, the
+		// operator's referenced siblings for a trace operator.
+		var deps map[string]bool
+
+		switch {
+		case query.GetType() == qbtypes.QueryTypeTraceOperator:
+			refs, rErr := q.traceOperatorPreviewComposite(req, query)
+			if rErr != nil {
+				errs[name] = rErr
+				continue
+			}
+			sub.CompositeQuery = qbtypes.CompositeQuery{Queries: refs}
+			deps = dependencyQueries
+		case dependencyQueries[name]:
+			sub.RequestType = qbtypes.RequestTypeRaw
+			sub.CompositeQuery = qbtypes.CompositeQuery{Queries: []qbtypes.QueryEnvelope{query}}
+		default:
+			sub.CompositeQuery = qbtypes.CompositeQuery{Queries: []qbtypes.QueryEnvelope{query}}
+		}
+
+		built, _, bErr := q.buildQueries(&sub, deps, missingMetricQuerySet, event)
+		if bErr != nil {
+			errs[name] = bErr
+			continue
+		}
+
+		if provider, ok := built[name]; ok {
+			providers[name] = provider
+		}
+	}
+	return providers, errs
+}
+
+// rendersStandaloneStatement reports whether a query type renders its own
+// statement. Formula/join/sub-query don't — they reference other queries.
+func rendersStandaloneStatement(t qbtypes.QueryType) bool {
+	switch t {
+	case qbtypes.QueryTypeBuilder,
+		qbtypes.QueryTypePromQL,
+		qbtypes.QueryTypeClickHouseSQL,
+		qbtypes.QueryTypeTraceOperator:
+		return true
+	default:
+		return false
+	}
+}
+
+func (q *querier) traceOperatorPreviewComposite(req *qbtypes.QueryRangeRequest, operator qbtypes.QueryEnvelope) ([]qbtypes.QueryEnvelope, error) {
+	spec, ok := operator.Spec.(qbtypes.QueryBuilderTraceOperator)
+	if !ok {
+		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid trace operator query spec %T", operator.Spec)
+	}
+	if err := spec.ParseExpression(); err != nil {
+		return nil, err
+	}
+
+	referenced := make(map[string]bool)
+	for _, name := range spec.CollectReferencedQueries(spec.ParsedExpression) {
+		referenced[name] = true
+	}
+
+	queries := make([]qbtypes.QueryEnvelope, 0, len(referenced)+1)
+	for _, qe := range req.CompositeQuery.Queries {
+		if referenced[qe.GetQueryName()] {
+			queries = append(queries, qe)
+		}
+	}
+	return append(queries, operator), nil
+}
+
+func (q *querier) runPreviewTasks(ctx context.Context, tasks []qbtypes.PreviewTask, previews map[string]qbtypes.QueryPreview) {
+	if len(tasks) == 0 {
+		return
+	}
+
+	type outcome struct {
+		granules *telemetrystore.Granules
+		estimate []telemetrystore.EstimateEntry
+		warnings []string
+	}
+	outcomes := make([]outcome, len(tasks))
+
+	var wg sync.WaitGroup
+	for i := range tasks {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			t := tasks[i]
+			var out outcome
+			if granules, ok, scErr := q.telemetryStore.Indexes(ctx, t.Query, t.Args...); scErr != nil {
+				out.warnings = append(out.warnings, "could not compute granule stats: "+scErr.Error())
+			} else if ok {
+				out.granules = &granules
+			}
+			if estimate, eErr := q.telemetryStore.Estimate(ctx, t.Query, t.Args...); eErr != nil {
+				out.warnings = append(out.warnings, "could not run EXPLAIN ESTIMATE: "+eErr.Error())
+			} else {
+				out.estimate = estimate
+			}
+			outcomes[i] = out
+		}(i)
+	}
+	wg.Wait()
+
+	for i := range tasks {
+		ps := previews[tasks[i].Name]
+		if idx := tasks[i].StmtIdx; idx >= 0 && idx < len(ps.Statements) {
+			if outcomes[i].granules != nil {
+				ps.Statements[idx].Granules = outcomes[i].granules
+			}
+			if len(outcomes[i].estimate) > 0 {
+				ps.Statements[idx].Estimate = outcomes[i].estimate
+			}
+		}
+		ps.Warnings = append(ps.Warnings, outcomes[i].warnings...)
+		previews[tasks[i].Name] = ps
+	}
+}
+
+// orEmpty returns s, or a non-nil empty slice when s is nil.
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}

pkg/querier/promql_query.go

@@ -101,6 +101,7 @@ type promqlQuery struct {
 }
 
 var _ qbv5.Query = (*promqlQuery)(nil)
+var _ qbv5.StatementProvider = (*promqlQuery)(nil)
 
 func newPromqlQuery(
 	logger *slog.Logger,
@@ -220,6 +221,62 @@ func (q *promqlQuery) renderVars(query string, vars map[string]qbv5.VariableItem
 	return newQuery.String(), nil
 }
 
+// Statement renders the PromQL string (no SQL args) without executing it, for
+// the preview path.
+func (q *promqlQuery) Statement(_ context.Context) (*qbv5.Statement, error) {
+	rendered, err := q.renderVars(q.query.Query, q.vars, q.tr.From, q.tr.To)
+	if err != nil {
+		return nil, err
+	}
+	return &qbv5.Statement{Query: rendered}, nil
+}
+
+// PreviewStatements returns the ClickHouse statement(s) this PromQL query would
+// run, captured by driving the engine with a Storage that records each selector's
+// SQL and returns no data. Returns nil if capture is unsupported.
+func (q *promqlQuery) PreviewStatements(ctx context.Context) ([]prometheus.CapturedStatement, error) {
+	storer, ok := q.promEngine.(prometheus.StatementCapturer)
+	if !ok {
+		return nil, nil
+	}
+
+	rendered, err := q.renderVars(q.query.Query, q.vars, q.tr.From, q.tr.To)
+	if err != nil {
+		return nil, err
+	}
+
+	start := int64(querybuilder.ToNanoSecs(q.tr.From))
+	end := int64(querybuilder.ToNanoSecs(q.tr.To))
+
+	capStorage, recorder := storer.CapturingStorage()
+	qry, err := q.promEngine.Engine().NewRangeQuery(
+		ctx,
+		capStorage,
+		nil,
+		rendered,
+		time.Unix(0, start),
+		time.Unix(0, end),
+		q.query.Step.Duration,
+	)
+	if err != nil {
+		if e := tryEnhancePromQLExecError(err); e != nil {
+			return nil, e
+		}
+		return nil, enhancePromQLError(rendered, err)
+	}
+	defer qry.Close()
+
+	// Exec drives a Select per selector (recording SQL) but reads no data.
+	if res := qry.Exec(ctx); res.Err != nil {
+		if e := tryEnhancePromQLExecError(res.Err); e != nil {
+			return nil, e
+		}
+		return nil, errors.Newf(errors.TypeInternal, errors.CodeInternal, "query execution error: %v", res.Err)
+	}
+
+	return recorder.Statements(), nil
+}
+
 func (q *promqlQuery) Execute(ctx context.Context) (*qbv5.Result, error) {
 
 	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{

pkg/querier/trace_operator_query.go

@@ -23,6 +23,7 @@ type traceOperatorQuery struct {
 }
 
 var _ qbtypes.Query = (*traceOperatorQuery)(nil)
+var _ qbtypes.StatementProvider = (*traceOperatorQuery)(nil)
 
 func (q *traceOperatorQuery) Fingerprint() string {
 	return ""
@@ -32,6 +33,11 @@ func (q *traceOperatorQuery) Window() (uint64, uint64) {
 	return q.fromMS, q.toMS
 }
 
+// Statement renders the SQL without executing it, for the preview path.
+func (q *traceOperatorQuery) Statement(ctx context.Context) (*qbtypes.Statement, error) {
+	return q.stmtBuilder.Build(ctx, q.fromMS, q.toMS, q.kind, q.spec, q.compositeQuery)
+}
+
 func (q *traceOperatorQuery) Execute(ctx context.Context) (*qbtypes.Result, error) {
 	stmt, err := q.stmtBuilder.Build(
 		ctx,

pkg/querybuilder/where_clause_visitor.go

@@ -145,7 +145,7 @@ func PrepareWhereClause(query string, opts FilterExprVisitorOpts) (PreparedWhere
 			"Found %d syntax errors while parsing the search expression.",
 			len(parserErrorListener.SyntaxErrors),
 		)
-		additionals := make([]string, len(parserErrorListener.SyntaxErrors))
+		additionals := make([]string, 0, len(parserErrorListener.SyntaxErrors))
 		for _, err := range parserErrorListener.SyntaxErrors {
 			if err.Error() != "" {
 				additionals = append(additionals, err.Error())

pkg/telemetrystore/clickhousetelemetrystore/provider.go

@@ -130,18 +130,31 @@ func New(ctx context.Context, providerSettings factory.ProviderSettings, config
 		return nil, err
 	}
 
-	return &provider{
+	p := &provider{
 		settings:       settings,
 		clickHouseConn: chConn,
 		cluster:        config.Clickhouse.Cluster,
 		hooks:          hooks,
-	}, nil
+	}
+	return p, nil
 }
 
 func (p *provider) ClickhouseDB() clickhouse.Conn {
 	return p
 }
 
+func (p *provider) Estimate(ctx context.Context, stmt string, args ...any) ([]telemetrystore.EstimateEntry, error) {
+	return telemetrystore.RunExplainEstimate(ctx, p, stmt, args...)
+}
+
+func (p *provider) Plan(ctx context.Context, stmt string, args ...any) error {
+	return telemetrystore.RunExplainPlan(ctx, p, stmt, args...)
+}
+
+func (p *provider) Indexes(ctx context.Context, stmt string, args ...any) (telemetrystore.Granules, bool, error) {
+	return telemetrystore.RunExplainIndexes(ctx, p, stmt, args...)
+}
+
 func (p *provider) Cluster() string {
 	return p.cluster
 }

pkg/telemetrystore/explain.go

@@ -0,0 +1,257 @@
+package telemetrystore
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+
+	"github.com/ClickHouse/clickhouse-go/v2"
+	"github.com/SigNoz/signoz/pkg/errors"
+)
+
+// EstimateEntry is ClickHouse's EXPLAIN ESTIMATE for one table read: the parts,
+// rows, and marks it estimates it will scan.
+type EstimateEntry struct {
+	Database string `json:"database" required:"true" nullable:"false"`
+	Table    string `json:"table" required:"true" nullable:"false"`
+	Parts    int64  `json:"parts" required:"true" nullable:"false"`
+	Rows     int64  `json:"rows" required:"true" nullable:"false"`
+	Marks    int64  `json:"marks" required:"true" nullable:"false"`
+}
+
+// Granules is the granule-skip breakdown for one statement, summed from
+// `EXPLAIN json = 1, indexes = 1` across every ReadFromMergeTree node.
+type Granules struct {
+	Initial  int64           `json:"initial" required:"true" nullable:"false"`
+	Selected int64           `json:"selected" required:"true" nullable:"false"`
+	Skipped  int64           `json:"skipped" required:"true" nullable:"false"`
+	Reads    []MergeTreeRead `json:"reads" required:"true" nullable:"false"`
+}
+
+// MergeTreeRead is the index-pruning funnel for one ReadFromMergeTree node. Steps
+// run in sequence, so each step's Initial* matches the previous Selected*.
+type MergeTreeRead struct {
+	Table string      `json:"table" required:"true" nullable:"false"`
+	Steps []IndexStep `json:"steps" required:"true" nullable:"false"`
+}
+
+// IndexStep is one index applied during a MergeTree read: parts and granules
+// entering (Initial*) and surviving (Selected*) it. Type is the index kind
+// (MinMax, Partition, PrimaryKey, or Skip).
+type IndexStep struct {
+	Type             string   `json:"type" required:"true" nullable:"false"`
+	Name             string   `json:"name" required:"true" nullable:"false"`
+	Keys             []string `json:"keys" required:"true" nullable:"false"`
+	Condition        string   `json:"condition" required:"true" nullable:"false"`
+	InitialParts     int64    `json:"initialParts" required:"true" nullable:"false"`
+	SelectedParts    int64    `json:"selectedParts" required:"true" nullable:"false"`
+	InitialGranules  int64    `json:"initialGranules" required:"true" nullable:"false"`
+	SelectedGranules int64    `json:"selectedGranules" required:"true" nullable:"false"`
+}
+
+// ExplainPlanNode is a node in ClickHouse's `EXPLAIN json = 1, indexes = 1`
+// output, parsed to derive the granule-skip breakdown.
+type ExplainPlanNode struct {
+	NodeType    string             `json:"Node Type"`
+	Description string             `json:"Description"`
+	Indexes     []ExplainPlanIndex `json:"Indexes"`
+	Plans       []ExplainPlanNode  `json:"Plans"`
+}
+
+// ExplainPlanIndex is one index entry under a ReadFromMergeTree node, reporting
+// the parts/granules entering and surviving the index.
+type ExplainPlanIndex struct {
+	Type             string   `json:"Type"`
+	Name             string   `json:"Name"`
+	Keys             []string `json:"Keys"`
+	Condition        string   `json:"Condition"`
+	InitialParts     *int64   `json:"Initial Parts"`
+	SelectedParts    *int64   `json:"Selected Parts"`
+	InitialGranules  *int64   `json:"Initial Granules"`
+	SelectedGranules *int64   `json:"Selected Granules"`
+}
+
+// RunExplainEstimate backs TelemetryStore.Estimate.
+func RunExplainEstimate(ctx context.Context, conn clickhouse.Conn, stmt string, args ...any) ([]EstimateEntry, error) {
+	if err := ValidateExplainStatement(stmt); err != nil {
+		return nil, err
+	}
+
+	rows, err := conn.Query(ctx, "EXPLAIN ESTIMATE "+stmt, args...)
+	if err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "failed to run EXPLAIN ESTIMATE")
+	}
+	defer rows.Close()
+
+	colTypes := rows.ColumnTypes()
+	var entries []EstimateEntry
+	for rows.Next() {
+		dest := make([]any, len(colTypes))
+		for i, ct := range colTypes {
+			dest[i] = reflect.New(ct.ScanType()).Interface()
+		}
+		if err := rows.Scan(dest...); err != nil {
+			return nil, errors.WrapInternalf(err, errors.CodeInternal, "failed to scan EXPLAIN ESTIMATE row")
+		}
+		var entry EstimateEntry
+		for i, ct := range colTypes {
+			val := reflect.ValueOf(dest[i]).Elem().Interface()
+			switch strings.ToLower(ct.Name()) {
+			case "database":
+				entry.Database = fmt.Sprintf("%v", val)
+			case "table":
+				entry.Table = fmt.Sprintf("%v", val)
+			case "parts":
+				entry.Parts = toInt64(val)
+			case "rows":
+				entry.Rows = toInt64(val)
+			case "marks":
+				entry.Marks = toInt64(val)
+			}
+		}
+		entries = append(entries, entry)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "EXPLAIN ESTIMATE row iteration failed")
+	}
+	return entries, nil
+}
+
+// RunExplainPlan backs TelemetryStore.Plan, returning the driver error when stmt
+// does not parse or bind.
+func RunExplainPlan(ctx context.Context, conn clickhouse.Conn, stmt string, args ...any) error {
+	if err := ValidateExplainStatement(stmt); err != nil {
+		return err
+	}
+
+	rows, err := conn.Query(ctx, "EXPLAIN PLAN "+stmt, args...)
+	if err != nil {
+		return err
+	}
+	rows.Close()
+	return nil
+}
+
+// RunExplainIndexes backs TelemetryStore.Indexes, summing the breakdown
+// across every ReadFromMergeTree node.
+func RunExplainIndexes(ctx context.Context, conn clickhouse.Conn, stmt string, args ...any) (Granules, bool, error) {
+	if err := ValidateExplainStatement(stmt); err != nil {
+		return Granules{}, false, err
+	}
+
+	rows, err := conn.Query(ctx, "EXPLAIN json = 1, indexes = 1 "+stmt, args...)
+	if err != nil {
+		return Granules{}, false, errors.WrapInternalf(err, errors.CodeInternal, "failed to run EXPLAIN for granule stats")
+	}
+	defer rows.Close()
+
+	// json=1 emits one JSON document; join rows in case the driver splits it.
+	var sb strings.Builder
+	for rows.Next() {
+		var line string
+		if err := rows.Scan(&line); err != nil {
+			return Granules{}, false, errors.WrapInternalf(err, errors.CodeInternal, "failed to scan EXPLAIN json row")
+		}
+		sb.WriteString(line)
+		sb.WriteByte('\n')
+	}
+	if err := rows.Err(); err != nil {
+		return Granules{}, false, errors.WrapInternalf(err, errors.CodeInternal, "EXPLAIN json row iteration failed")
+	}
+
+	var plans []struct {
+		Plan ExplainPlanNode `json:"Plan"`
+	}
+	if err := json.Unmarshal([]byte(sb.String()), &plans); err != nil {
+		return Granules{}, false, errors.WrapInternalf(err, errors.CodeInternal, "failed to parse EXPLAIN json")
+	}
+
+	var totalInitial, totalSelected int64
+	reads := []MergeTreeRead{}
+	for i := range plans {
+		collectMergeTreeReads(&plans[i].Plan, &reads, &totalInitial, &totalSelected)
+	}
+	if totalInitial <= 0 {
+		// No MergeTree index analysis — nothing to report.
+		return Granules{}, false, nil
+	}
+	if totalSelected < 0 {
+		totalSelected = 0
+	}
+	skippedGranules := totalInitial - totalSelected
+	if skippedGranules < 0 {
+		skippedGranules = 0
+	}
+	return Granules{
+		Initial:  totalInitial,
+		Selected: totalSelected,
+		Skipped:  skippedGranules,
+		Reads:    reads,
+	}, true, nil
+}
+
+func collectMergeTreeReads(node *ExplainPlanNode, reads *[]MergeTreeRead, totalInitial, totalSelected *int64) {
+	if node.NodeType == "ReadFromMergeTree" && len(node.Indexes) > 0 {
+		steps := make([]IndexStep, 0, len(node.Indexes))
+		var initial, selected *int64
+		for i := range node.Indexes {
+			idx := node.Indexes[i]
+			if idx.InitialGranules != nil && initial == nil {
+				initial = idx.InitialGranules
+			}
+			if idx.SelectedGranules != nil {
+				selected = idx.SelectedGranules
+			}
+			steps = append(steps, IndexStep{
+				Type:             idx.Type,
+				Name:             idx.Name,
+				Keys:             orEmpty(idx.Keys),
+				Condition:        idx.Condition,
+				InitialParts:     derefInt64(idx.InitialParts),
+				SelectedParts:    derefInt64(idx.SelectedParts),
+				InitialGranules:  derefInt64(idx.InitialGranules),
+				SelectedGranules: derefInt64(idx.SelectedGranules),
+			})
+		}
+		if initial != nil && selected != nil {
+			*totalInitial += *initial
+			*totalSelected += *selected
+		}
+		*reads = append(*reads, MergeTreeRead{Table: node.Description, Steps: steps})
+	}
+	for i := range node.Plans {
+		collectMergeTreeReads(&node.Plans[i], reads, totalInitial, totalSelected)
+	}
+}
+
+// toInt64 coerces a driver-scanned numeric value to int64 (0 if non-numeric).
+func toInt64(v any) int64 {
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return rv.Int()
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return int64(rv.Uint())
+	case reflect.Float32, reflect.Float64:
+		return int64(rv.Float())
+	default:
+		return 0
+	}
+}
+
+func derefInt64(p *int64) int64 {
+	if p == nil {
+		return 0
+	}
+	return *p
+}
+
+// orEmpty returns s, or a non-nil empty slice when s is nil.
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}

pkg/telemetrystore/explain_statement.go

@@ -0,0 +1,122 @@
+package telemetrystore
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+)
+
+// ErrCodeUnsafeStatement is returned when a statement is not a single statement
+// safe to wrap in an EXPLAIN prefix.
+var ErrCodeUnsafeStatement = errors.MustNewCode("unsafe_statement")
+
+// scanState is the lexer state while scanning a statement.
+type scanState int
+
+const (
+	scanNormal scanState = iota
+	scanSingle
+	scanDouble
+	scanBacktick
+	scanLineComment
+	scanBlockComment
+)
+
+// ValidateExplainStatement rejects stacked statements (e.g. `SELECT 1; DROP TABLE t`),
+// the only injection vector left once values are bound and the EXPLAIN prefix is fixed.
+// It scans stmt as ClickHouse SQL — ignoring ';' inside string literals, quoted
+// identifiers, and comments — and rejects any content after a top-level ';'.
+func ValidateExplainStatement(stmt string) error {
+	if strings.TrimSpace(stmt) == "" {
+		return errors.NewInvalidInputf(ErrCodeUnsafeStatement, "statement is empty")
+	}
+
+	state := scanNormal
+	// terminated is set at a top-level ';'; after it only whitespace, ';', and
+	// comments may appear — anything else is a second statement.
+	terminated := false
+
+	for i := 0; i < len(stmt); i++ {
+		c := stmt[i]
+		switch state {
+		case scanNormal:
+			if terminated {
+				switch {
+				case isSQLSpace(c) || c == ';':
+					// harmless trailing whitespace / empty statements
+				case c == '-' && i+1 < len(stmt) && stmt[i+1] == '-':
+					state = scanLineComment
+					i++
+				case c == '/' && i+1 < len(stmt) && stmt[i+1] == '*':
+					state = scanBlockComment
+					i++
+				default:
+					return errors.NewInvalidInputf(ErrCodeUnsafeStatement, "statement must be a single statement; content found after ';'")
+				}
+				continue
+			}
+			switch {
+			case c == '\'':
+				state = scanSingle
+			case c == '"':
+				state = scanDouble
+			case c == '`':
+				state = scanBacktick
+			case c == '-' && i+1 < len(stmt) && stmt[i+1] == '-':
+				state = scanLineComment
+				i++
+			case c == '/' && i+1 < len(stmt) && stmt[i+1] == '*':
+				state = scanBlockComment
+				i++
+			case c == ';':
+				terminated = true
+			}
+		case scanSingle:
+			i = skipQuoted(stmt, i, '\'', &state)
+		case scanDouble:
+			i = skipQuoted(stmt, i, '"', &state)
+		case scanBacktick:
+			i = skipQuoted(stmt, i, '`', &state)
+		case scanLineComment:
+			if c == '\n' {
+				state = scanNormal
+			}
+		case scanBlockComment:
+			if c == '*' && i+1 < len(stmt) && stmt[i+1] == '/' {
+				state = scanNormal
+				i++
+			}
+		}
+	}
+
+	return nil
+}
+
+// skipQuoted advances one character within a quoted literal/identifier delimited
+// by quote. A backslash or doubled quote escapes; an unescaped quote ends the
+// literal (resetting *state). It returns the index to resume from (caller adds one).
+func skipQuoted(s string, i int, quote byte, state *scanState) int {
+	c := s[i]
+	switch c {
+	case '\\':
+		// skip the escaped character
+		return i + 1
+	case quote:
+		if i+1 < len(s) && s[i+1] == quote {
+			// doubled quote: stay inside the literal
+			return i + 1
+		}
+		*state = scanNormal
+	}
+	return i
+}
+
+// isSQLSpace reports whether c is SQL statement whitespace.
+func isSQLSpace(c byte) bool {
+	switch c {
+	case ' ', '\t', '\n', '\r', '\v', '\f':
+		return true
+	default:
+		return false
+	}
+}

pkg/telemetrystore/explain_statement_test.go

@@ -0,0 +1,46 @@
+package telemetrystore
+
+import "testing"
+
+func TestValidateExplainStatement(t *testing.T) {
+	cases := []struct {
+		name string
+		stmt string
+		ok   bool
+	}{
+		{"simple select", "SELECT 1", true},
+		{"with cte", "WITH x AS (SELECT 1) SELECT * FROM x", true},
+		{"trailing semicolon", "SELECT 1;", true},
+		{"trailing semicolon and space", "SELECT 1;  \n", true},
+		{"double trailing semicolon", "SELECT 1;;", true},
+		{"trailing line comment", "SELECT 1; -- done", true},
+		{"trailing block comment", "SELECT 1; /* done */", true},
+		{"semicolon inside string", "SELECT 'a; b' AS x", true},
+		{"semicolon inside backtick ident", "SELECT 1 AS `a;b`", true},
+		{"semicolon inside double-quoted ident", "SELECT 1 AS \"a;b\"", true},
+		{"semicolon inside line comment", "SELECT 1 -- a; b", true},
+		{"semicolon inside block comment", "SELECT /* a; b */ 1", true},
+		{"escaped quote then semicolon in string", "SELECT 'a\\'; DROP' AS x", true},
+		{"doubled quote then semicolon in string", "SELECT 'a''; DROP' AS x", true},
+
+		{"empty", "", false},
+		{"whitespace only", "   \n\t", false},
+		{"stacked statement", "SELECT 1; DROP TABLE t", false},
+		{"stacked statement no space", "SELECT 1;DROP TABLE t", false},
+		{"stacked after string close", "SELECT 'a'; DROP TABLE t", false},
+		{"stacked string statement", "SELECT 1; 'x'", false},
+		{"stacked after comment", "SELECT 1; /* c */ SELECT 2", false},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateExplainStatement(tc.stmt)
+			if tc.ok && err != nil {
+				t.Fatalf("expected valid, got error: %v", err)
+			}
+			if !tc.ok && err == nil {
+				t.Fatalf("expected error, got nil")
+			}
+		})
+	}
+}

pkg/telemetrystore/telemetrystore.go

@@ -7,11 +7,20 @@ import (
 )
 
 type TelemetryStore interface {
-	// ClickhouseDB returns the clickhouse database connection.
+	// ClickhouseDB returns the clickhouse connection, which can also EXPLAIN.
 	ClickhouseDB() clickhouse.Conn
 
 	// Cluster returns the cluster name.
 	Cluster() string
+
+	// Estimate returns the per-table scan estimate from EXPLAIN ESTIMATE.
+	Estimate(ctx context.Context, stmt string, args ...any) ([]EstimateEntry, error)
+
+	// Plan runs EXPLAIN PLAN to check stmt parses and binds.
+	Plan(ctx context.Context, stmt string, args ...any) error
+
+	// Indexes returns the granule-skip breakdown from EXPLAIN json = 1, indexes = 1.
+	Indexes(ctx context.Context, stmt string, args ...any) (Granules, bool, error)
 }
 
 type TelemetryStoreHook interface {

pkg/telemetrystore/telemetrystoretest/provider.go

@@ -1,10 +1,12 @@
 package telemetrystoretest
 
 import (
+	"context"
+
 	"github.com/ClickHouse/clickhouse-go/v2"
 	"github.com/DATA-DOG/go-sqlmock"
-	"github.com/SigNoz/signoz/pkg/telemetrystore"
 	cmock "github.com/SigNoz/clickhouse-go-mock"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
 )
 
 var _ telemetrystore.TelemetryStore = (*Provider)(nil)
@@ -36,6 +38,21 @@ func (p *Provider) Cluster() string {
 	return "cluster"
 }
 
+// Estimate runs EXPLAIN ESTIMATE against the mock connection.
+func (p *Provider) Estimate(ctx context.Context, stmt string, args ...any) ([]telemetrystore.EstimateEntry, error) {
+	return telemetrystore.RunExplainEstimate(ctx, p.clickhouseDB.(clickhouse.Conn), stmt, args...)
+}
+
+// Plan runs EXPLAIN PLAN against the mock connection.
+func (p *Provider) Plan(ctx context.Context, stmt string, args ...any) error {
+	return telemetrystore.RunExplainPlan(ctx, p.clickhouseDB.(clickhouse.Conn), stmt, args...)
+}
+
+// Indexes runs EXPLAIN indexes against the mock connection.
+func (p *Provider) Indexes(ctx context.Context, stmt string, args ...any) (telemetrystore.Granules, bool, error) {
+	return telemetrystore.RunExplainIndexes(ctx, p.clickhouseDB.(clickhouse.Conn), stmt, args...)
+}
+
 // Mock returns the underlying Clickhouse mock instance for setting expectations.
 func (p *Provider) Mock() cmock.ClickConnMockCommon {
 	return p.clickhouseDB

pkg/types/querybuildertypes/querybuildertypesv5/preview.go

@@ -0,0 +1,10 @@
+package querybuildertypesv5
+
+// PreviewTask is one rendered statement queued for granule/estimate analysis.
+// StmtIdx is where its results merge back into the query's Statements.
+type PreviewTask struct {
+	Name    string
+	StmtIdx int
+	Query   string
+	Args    []any
+}

pkg/types/querybuildertypes/querybuildertypesv5/qb.go

@@ -58,3 +58,8 @@ type TraceOperatorStatementBuilder interface {
 	// Build builds the trace operator query.
 	Build(ctx context.Context, start, end uint64, requestType RequestType, query QueryBuilderTraceOperator, compositeQuery *CompositeQuery) (*Statement, error)
 }
+
+// StatementProvider renders a query's underlying statement without executing it.
+type StatementProvider interface {
+	Statement(ctx context.Context) (*Statement, error)
+}

pkg/types/querybuildertypes/querybuildertypesv5/resp.go

@@ -10,6 +10,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
 	"github.com/swaggest/jsonschema-go"
@@ -64,6 +66,64 @@ type QueryRangeResponse struct {
 	QBEvent *QBEvent `json:"-"`
 }
 
+// QueryRangePreviewResponse is the dry-run output: one QueryPreview per query,
+// keyed by the request's query names.
+type QueryRangePreviewResponse struct {
+	CompositeQuery map[string]QueryPreview `json:"compositeQuery" required:"true" nullable:"true"`
+}
+
+// QueryRangePreviewOptions carries per-call options for the dry-run endpoint.
+type QueryRangePreviewOptions struct {
+	Verbose bool
+}
+
+// QueryRangePreviewParams are the query-string parameters of the dry-run endpoint.
+type QueryRangePreviewParams struct {
+	Verbose string `query:"verbose"`
+}
+
+// PrepareJSONSchema adds description to the QueryRangePreviewResponse schema.
+func (q *QueryRangePreviewResponse) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Response from the v5 query range preview (dry-run) endpoint. For each query in the composite query, returns the underlying ClickHouse statement(s) it renders to without executing them (one per PromQL metric selector; exactly one for builder/ClickHouse/trace-operator queries), with the optional EXPLAIN ESTIMATE and granule analysis attached per statement when requested.")
+	return nil
+}
+
+// QueryPreview is the dry-run result for a single query.
+type QueryPreview struct {
+	Valid      bool               `json:"valid" required:"true" nullable:"false"`
+	Error      error              `json:"error" required:"true"`
+	Warnings   []string           `json:"warnings" required:"true" nullable:"false"`
+	Statements []PreviewStatement `json:"statements" required:"true" nullable:"false"`
+}
+
+// PreviewStatement is one rendered ClickHouse statement with its args and, when
+// requested, its EXPLAIN ESTIMATE and granule breakdown. The query/args JSON
+// keys follow the OpenTelemetry db.statement.* convention.
+type PreviewStatement struct {
+	Query    string                         `json:"db.statement.query" required:"true" nullable:"false"`
+	Args     []any                          `json:"db.statement.args" required:"true" nullable:"false"`
+	Estimate []telemetrystore.EstimateEntry `json:"estimate" required:"true" nullable:"false"`
+	Granules *telemetrystore.Granules       `json:"granules" required:"true" nullable:"true"`
+}
+
+// MarshalJSON renders Error in its structured form (code/message/suggestions)
+// rather than the empty object a bare error produces. The nullable:"false"
+// arrays are non-nil from the producer, so they marshal as [] rather than null.
+func (p QueryPreview) MarshalJSON() ([]byte, error) {
+	type alias QueryPreview
+	out := struct {
+		alias
+		Error *errors.JSON `json:"error"`
+	}{alias: alias(p)}
+	out.alias.Error = nil
+	// Derive the verdict so the two can't desync.
+	out.Valid = p.Error == nil
+	if p.Error != nil {
+		out.Error = errors.AsJSON(p.Error)
+	}
+	return json.Marshal(out)
+}
+
 var _ jsonschema.Preparer = &QueryRangeResponse{}
 
 // PrepareJSONSchema adds description to the QueryRangeResponse schema.
@@ -256,7 +316,6 @@ type RawStream struct {
 	Error chan error
 }
 
-
 func roundToNonZeroDecimals(val float64, n int) float64 {
 	if val == 0 || math.IsNaN(val) || math.IsInf(val, 0) {
 		return val

pkg/types/querybuildertypes/querybuildertypesv5/validation.go

@@ -575,6 +575,75 @@ func (r *QueryRangeRequest) Validate(opts ...ValidationOption) error {
 	return nil
 }
 
+// ValidateRequestScope validates request-level invariants (not individual query
+// specs) and returns the request type's ValidationOptions. The dry-run path uses
+// this so per-query errors can be attributed individually via QueryEnvelope.Validate
+// instead of failing fast like Validate does.
+func (r *QueryRangeRequest) ValidateRequestScope() ([]ValidationOption, error) {
+	if r.RequestType != RequestTypeRawStream && r.Start >= r.End {
+		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "start time must be before end time")
+	}
+
+	var opts []ValidationOption
+	switch r.RequestType {
+	case RequestTypeRaw, RequestTypeRawStream, RequestTypeTrace, RequestTypeTimeSeries, RequestTypeScalar:
+		opts = GetValidationOptions(r.RequestType)
+	default:
+		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid request type: %s", r.RequestType).
+			WithAdditional("Valid request types are: raw, timeseries, scalar")
+	}
+
+	if r.RequestType == RequestTypeRaw || r.RequestType == RequestTypeRawStream || r.RequestType == RequestTypeTrace {
+		for _, envelope := range r.CompositeQuery.Queries {
+			if envelope.GetSignal() == telemetrytypes.SignalMetrics {
+				return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "raw request type is not supported for metric queries")
+			}
+		}
+	}
+
+	if len(r.CompositeQuery.Queries) == 0 {
+		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "at least one query is required")
+	}
+
+	// Builder query names must be unique across the composite query.
+	queryNames := make(map[string]bool)
+	for _, envelope := range r.CompositeQuery.Queries {
+		if envelope.Type == QueryTypeBuilder || envelope.Type == QueryTypeSubQuery {
+			name := envelope.GetQueryName()
+			if name != "" {
+				if queryNames[name] {
+					return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "duplicate query name '%s'", name)
+				}
+				queryNames[name] = true
+			}
+		}
+	}
+
+	if err := r.validateAllQueriesNotDisabled(); err != nil {
+		return nil, err
+	}
+
+	return opts, nil
+}
+
+// Validate parses the preview query-string parameters. Verbose defaults to true
+// and accepts true/1/false/0; any other value is rejected.
+func (p *QueryRangePreviewParams) Validate() (QueryRangePreviewOptions, error) {
+	switch strings.ToLower(strings.TrimSpace(p.Verbose)) {
+	case "", "true", "1":
+		return QueryRangePreviewOptions{Verbose: true}, nil
+	case "false", "0":
+		return QueryRangePreviewOptions{Verbose: false}, nil
+	}
+	return QueryRangePreviewOptions{}, errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid verbose value %q (allowed: true, false)", p.Verbose)
+}
+
+// Validate validates a single query envelope's spec — the per-query counterpart
+// to ValidateRequestScope, letting the dry-run report errors independently.
+func (e QueryEnvelope) Validate(opts ...ValidationOption) error {
+	return validateQueryEnvelope(e, opts...)
+}
+
 // validateAllQueriesNotDisabled validates that at least one query in the composite query is enabled.
 func (r *QueryRangeRequest) validateAllQueriesNotDisabled() error {
 	for _, envelope := range r.CompositeQuery.Queries {