--- title: "Check an analytics query being written" method: POST path: "/v1/query/analytics-draft" tags: ["Query Parsing"] --- # Check an analytics query being written `POST /v1/query/analytics-draft` ## Request - Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from) - URL: `https://docs.grepr.ai/v1/query/analytics-draft` - Auth: one of: - API key in header `GREPR-API-KEY` - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`) Checks request constraints and server limits for an analytics draft. When those pass, translates the whole query once and reports its first SQL failure. Diagnostics name the field when it is known, or the query as a whole. Draft feedback is advisory; submission still validates against the actual table and engine. The query is deliberately not bean-validated on the way in, so incomplete drafts receive diagnostics rather than a rejected request. ## Request body - AnalyticsDraftRequest - `datasetId` string: Dataset the query reads. Supplying it checks the scan budget against that dataset's ceiling and requires VIEW permission on it. - `query` StructuredAnalyticsQuery, required - `end` string, date-time, required: End of the time interval to query. - `from` string, required: Logical table alias to query. - `groupBy` string[]: Grepr SQL expressions or projection aliases used for grouping. An expression may reference projection aliases. - `having` string: Optional Grepr SQL expression applied after aggregation. The expression may reference projection aliases. - `limit` integer: Maximum number of result rows. - `orderBy` AnalyticsOrderBy[]: Ordering applied to the analytical results. - `direction` 'ASC' | 'DESC': Sort direction. - `expression` string, required: Grepr SQL expression or projection alias to order by. The expression may reference projection aliases. - `predicate` union, required: Predicate applied to rows before analytical aggregation. - object - `queries` EventPredicate[], required: List of predicates that must all match for this predicate to match. - `type` 'and-predicate', required: A predicate that matches when every child predicate matches. - `query` string - object - `query` string, required: The datadog query used by the predicate. See https://docs.datadoghq.com/tracing/trace_explorer/query_syntax - `type` 'datadog-query', required: A predicate that checks if an event matches a datadog query. - object - `filterTags` object: The set of tags to query for. If unspecified, all tags are queried. - `metricNames` string[], required: The names of the metrics to query. Must not be empty. - `query` string, required - `type` 'metric-predicate', required: A predicate that checks if an event matches a metrics query. - object - `query` string, required: The New Relic query used by the predicate. See https://docs.newrelic.com/docs/logs/ui-data/query-syntax-logs/ - `type` 'newrelic-query', required: A predicate that checks if an event matches a New Relic query. - object - `query` string, required: The Nrql query used by the predicate. See https://docs.newrelic.com/docs/nrql - `strict` boolean: Whether the query should be parsed in strict mode. - `type` 'nrql-query', required: A predicate that checks if an event matches an NRQL query. - `select` AnalyticsProjection[], required: Expressions returned by the query. - `alias` string: Optional result column name. - `expression` string, required: Grepr SQL expression to project. - `start` string, date-time, required: Start of the time interval to query. - `variables` object: Variables available while parsing the predicate. - `window` AnalyticsTimeWindow: Optional time window that buckets the results. Adds leading 'window_start' and 'window_end' result columns, which are always grouped. - `kind` 'TUMBLING' | 'SLIDING', required: Window layout: TUMBLING windows do not overlap; SLIDING windows start every 'slide'. - `size` string, ISO-8601, required: Window length as an ISO-8601 duration, a whole number of milliseconds. - `slide` string, ISO-8601: Distance between consecutive SLIDING window starts as an ISO-8601 duration, a whole number of milliseconds dividing 'size'. Absent for TUMBLING windows. - `timestamp` 'EVENT_TIMESTAMP' | 'RECEIVED_TIMESTAMP': Which timestamp the windows bucket by. - `scanBudgetBytes` integer, required: Bytes the run may scan, checked against the organization's ceiling. Zero stands for a budget field left empty and is reported as a diagnostic. ## Response `200` Diagnostics for the analytics draft. - AnalyticsDraftResponse - `diagnostics` AnalyticsDiagnostic[], required: Request constraints, followed by the first SQL failure when the request is complete, at most one per field. Empty means no draft errors were found; execution still validates the query against its actual table and engine. - `fix` AnalyticsDiagnosticFix: A change that resolves this diagnostic, when the server has verified one: today, the GROUP BY entry that makes an ungrouped SELECT expression valid. - `addGroupBy` string, required: A GROUP BY entry to append: the result column's alias, quoted when it starts with a digit, or its expression when it has no alias. The server has translated the query with this entry added and found it valid. - `message` string, required: What is wrong, as a finished sentence to show the person editing the query. - `path` string, required: Where the rule was broken, as a path into the request: 'select', 'select[1].expression', 'select[1].alias', 'groupBy[0]', 'window.size', 'window.slide', 'having', 'orderBy[2].expression', 'limit', 'scanBudgetBytes', 'predicate', or 'query' for a failure that names no single item. ## Other responses - `400`: The query is missing. - `401`: Unauthorized - `403`: The caller cannot view the requested dataset. --- [API](https://skmtc.dev/grepr/apis/grepr-api.md) - [All operations](https://skmtc.dev/grepr/apis/grepr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grepr/apis/grepr-api/revisions/2a5ce03a0bf0?raw)