Class: QueryService
Defined in: server/insights/services/query-service.ts:107
READ-ONLY query execution. Validates (shared structural + semantic),
compiles to Prisma.Sql, and executes on the replica when configured, else
the ambient primary. When a tenancy backstop is provided the run is
wrapped in withTenantTransaction on the SAME client, so the executor's
transaction reuses the GUC-pinned transaction (belt: compiler-injected
tenant predicate; suspenders: RLS GUC).
Constructors
Constructor
new QueryService(deps: QueryServiceDeps): QueryService;Defined in: server/insights/services/query-service.ts:108
Parameters
| Parameter | Type |
|---|---|
deps | QueryServiceDeps |
Returns
QueryService
Methods
run()
run(definition: {
aggregations?: {
alias: string;
field?: string;
fn: "min" | "max" | "count" | "avg" | "sum";
}[];
columns: string[];
filter?: FilterNode;
groupBy?: {
bucket?: "year" | "month" | "day" | "week" | "quarter";
field: string;
}[];
schemaVersion: 1;
sort: {
by: string;
direction: "asc" | "desc";
}[];
subject: string;
timezone: string;
totals?: boolean;
}, ctx: RunReportContext): Promise<ReportResult>;Defined in: server/insights/services/query-service.ts:110
Parameters
| Parameter | Type | Description |
|---|---|---|
definition | { aggregations?: { alias: string; field?: string; fn: "min" | "max" | "count" | "avg" | "sum"; }[]; columns: string[]; filter?: FilterNode; groupBy?: { bucket?: "year" | "month" | "day" | "week" | "quarter"; field: string; }[]; schemaVersion: 1; sort: { by: string; direction: "asc" | "desc"; }[]; subject: string; timezone: string; totals?: boolean; } | - |
definition.aggregations? | { alias: string; field?: string; fn: "min" | "max" | "count" | "avg" | "sum"; }[] | - |
definition.columns | string[] | The SELECT list — and the ONLY source of output columns, for grouped runs as much as detail runs: the compiler derives its projection from columns alone and never from groupBy/aggregations. So an empty columns has no compilable projection at all (not merely a semantically odd one), which makes it a STRUCTURAL failure and puts the check here rather than in validateDefinition. Keeping it in the schema also means every surface that parses a definition — run input, saved-report create/update, normalizeSavedReportDefinition on read, canned reports in the registry — fails closed without having to remember a second validation pass. |
definition.filter? | FilterNode | - |
definition.groupBy? | { bucket?: "year" | "month" | "day" | "week" | "quarter"; field: string; }[] | - |
definition.schemaVersion | 1 | - |
definition.sort | { by: string; direction: "asc" | "desc"; }[] | - |
definition.subject | string | - |
definition.timezone | string | - |
definition.totals? | boolean | - |
ctx | RunReportContext | - |
Returns
Promise<ReportResult>
runDistinctFieldValues()
runDistinctFieldValues(
subjectKey: string,
fieldKey: string,
ctx: Pick<RunReportContext, "organizationId" | "rowCap">
): Promise<ReportResult>;Defined in: server/insights/services/query-service.ts:138
Enumerate one groupable field for an internal capped picker. The ORDER BY
is deliberately independent of the public sortable capability: this is
a server-authored deterministic DISTINCT query, not a user-authored report
sort. Keeping the exception inside this narrow method preserves the public
validator while ensuring LIMIT never chooses an arbitrary option subset.
Parameters
| Parameter | Type |
|---|---|
subjectKey | string |
fieldKey | string |
ctx | Pick<RunReportContext, "organizationId" | "rowCap"> |
Returns
Promise<ReportResult>
runMetric()
runMetric(key: string, ctx: RunMetricContext): Promise<MetricResult>;Defined in: server/insights/services/query-service.ts:193
Parameters
| Parameter | Type |
|---|---|
key | string |
ctx | RunMetricContext |
Returns
Promise<MetricResult>