Cloud & Automation
Report Engine Architecture: Request to Result
Trace a report request through gateway, security, validation, cache, Fabric query, result construction and monitoring.
On this page
Short answer: a report request passes through six stages: gateway, authorization, validation, cache lookup, query, and result delivery. Each stage should fail with its own explicit response and leave one log record that names the stage. Synchronous responses suit small, fast reports; anything that can outlive an HTTP timeout should become an asynchronous job the client polls.
Request lifecycle
API Management
Step 1: Receive request
Assign a request ID, accept a correlation ID
Report Engine
Step 2: Validate request
Report, format, date range, row and byte limits
Report Engine
Step 3: Resolve tenant & security
Tenant from trusted claims; authorize report and filters
Storage account
Step 4: Check cache
Tenant-aware key; fresh output → skip to step 6 or 8
Microsoft Fabric
Step 5: Query Fabric if needed
Approved template, bound parameters, timeout
Only on a cache miss
Report Engine
Step 6: Build result
Shape rows into JSON, CSV or Parquet
Storage account
Step 7: Store output / cache result
Write to the tenant’s folder with a TTL
Report Engine
Step 8: Return response
JSON body or short-lived download link
The client reaches API Management or a gateway, which establishes identity, request size limits, and coarse throttling. The report engine performs report authorization, tenant validation, parameter validation, and finer workload limits before any query work begins.
Cache decision
- RequestValidated, tenant resolved
- Cache key
tenantreportparametersformatversion - Look upIn
report-cache, under{tenant}/{report}/… - Cached and fresh?Within the report’s TTL
Yes Cache hit
- Authorize again for this caller
- Read the stored output
- Return result
No Cache miss
- Query Fabric (approved template)
- Build output: JSON, CSV or Parquet
- Store under the tenant’s path, with a TTL
- Return result
Tenant-aware: same report, same parameters, different tenants
- contoso
contoso · sales-by-region · 2026-09 · csv · v3report-cache/contoso/sales-by-region/… - fabrikam
fabrikam · sales-by-region · 2026-09 · csv · v3report-cache/fabrikam/sales-by-region/…
Two keys, two folders: never shared.
Build a canonical cache key from trusted tenant identity, report type, normalized date range, dimensions, filters, format, and report version. The same safe logical request produces the same key. A hit still requires authorization. A miss proceeds to the controlled query layer and may cache the finished result with TTL and freshness metadata.
Query and result
The query layer selects an approved query template for Fabric Warehouse or Lakehouse SQL endpoint and binds validated values. The result builder enforces row and byte limits, produces JSON, CSV, Parquet or another allowed format, and stores large artifacts privately. Download URLs are short lived and checked against tenant identity.
Observability
Record request_id, correlation_id, tenant_id, client_id, api_key_id, report_name, requested_at, started_at, completed_at, duration_ms, cache_hit, query_duration_ms, rows_returned, output_bytes, status, and error_code. These fields connect directly to the Monitoring pillar and support capacity, reliability, audit, and cost analysis.
Failure handling by stage
A request that fails should tell the caller what to do next and tell the operator where it stopped.
| Stage | Typical failure | Response | Record |
|---|---|---|---|
| Gateway | Missing or invalid credentials; consumer over its rate limit | 401, or 429 with Retry-After |
Consumer ID, limit that was hit |
| Authorization | Caller not allowed this tenant or report | 403 | Caller, tenant, report; never the data that would have been returned |
| Validation | Unknown dimension, end before start, range or row limit exceeded | 400 with the rule that failed | The rule and the offending parameter, with sensitive values redacted |
| Cache | Entry unreadable or partially written | Treat as a miss; do not fail the request | Cache key, read error |
| Query | Timeout, capacity throttling, transient connection error | 503 or 504, with Retry-After when retrying makes sense |
Query template, duration, error code, rows read if known |
| Result | Output larger than allowed; storage write failed | 400 telling the caller to narrow the request or use an export; 500 for a storage failure | Rows and bytes produced, storage path |
Two rules keep this table honest. Return a validation failure before any query runs, so a bad request costs nothing. And set the query timeout shorter than the gateway’s, so the engine, not the gateway, decides what the caller receives.
When to switch to an asynchronous request
If a report can take longer than the client or gateway will wait, return a job instead of holding the connection. The Asynchronous Request-Reply pattern describes the exchange:
POST /reports/revenue-by-channel/runs
→ 202 Accepted
Location: /reports/runs/7d1f…
Retry-After: 10
GET /reports/runs/7d1f…
→ 200 OK {"status": "running"}
GET /reports/runs/7d1f…
→ 303 See Other
Location: /reports/runs/7d1f…/result
The job carries the same request ID as the original call, so the log and the job status describe one execution. Cancellation should stop the query, not only the polling: a client that gives up should not leave a query running against your capacity.
One log record per request
{
"request_id": "7d1f…",
"correlation_id": "c41a…",
"tenant_id": "contoso",
"client_id": "partner-portal",
"report_name": "revenue-by-channel",
"report_version": 3,
"stage_reached": "result",
"status": "succeeded",
"cache_hit": false,
"requested_at": "2026-11-06T08:14:03.120Z",
"completed_at": "2026-11-06T08:14:05.902Z",
"duration_ms": 2782,
"query_duration_ms": 2410,
"rows_returned": 3120,
"output_bytes": 188416,
"error_code": null
}
stage_reached is the field that turns a failure count into a diagnosis: a spike of failures at validation is a client problem, at query a capacity or warehouse problem, at result a size or storage problem. Measuring API and report request volume shows how to aggregate these records.
Related
- What is a report engine?
- Pre-rendered reports vs live queries
- Building a multi-tenant report engine on Azure and Microsoft Fabric, sections 13 (asynchronous report generation) and 14 (an end-to-end request)
- Report engine architecture reference
Sources
- Azure Architecture Center: Asynchronous Request-Reply pattern, Throttling pattern, Retry pattern
- Microsoft Learn: rate-limit-by-key policy (429 responses), SAS overview
Checked November 2026. Status codes follow common HTTP practice; align them with your API’s existing conventions.
Was this helpful?
What could be better?
Thanks — that helps me improve Javi Builds.
Continue learning
- Cheat sheetMicrosoft Fabric Workspace Settings Cheat SheetThe Microsoft Fabric workspace settings that change how a data engineering workspace behaves: Spark pools, environments and jobs, domain assignment, OneLake shortcut caching and diagnostics, and data workflow (Apache Airflow job) runtime pools, with what to verify for each.Open cheat sheet
- ArticleDesigning a Report Engine for UI and API ConsumersDesign one governed report backend for interactive UI pages, external APIs, downloads and large asynchronous exports.Read article
What should I build next?
I'm building Javi Builds around practical problems data engineers actually face. Tell me what you'd like to see next.
Stay in the loop
Get the Javi Builds updates you actually care about.
Check your inbox
I sent you a confirmation link. Your subscription will be active after you confirm it.