1# GraphQL Analytics API Patterns & Best Practices
2 
3## Time-Series Queries
4 
5Use time dimension granularity matching your range (see Best Practices below).
6 
7```graphql
8query TrafficTimeSeries($zoneTag: string!, $start: Time!, $end: Time!) {
9  viewer {
10    zones(filter: { zoneTag: $zoneTag }) {
11      httpRequestsAdaptiveGroups(
12        filter: { datetime_gt: $start, datetime_lt: $end }
13        limit: 1000
14        orderBy: [datetimeFiveMinutes_ASC]  # or datetimeHour_ASC for longer ranges
15      ) {
16        count
17        dimensions { datetimeFiveMinutes }
18        sum { edgeResponseBytes }
19        ratio { status4xx status5xx }
20      }
21    }
22  }
23}
24```
25 
26## Top-N Queries
27 
28### Top Countries by Request Count
29 
30```graphql
31query TopCountries($zoneTag: string!, $start: Time!, $end: Time!) {
32  viewer {
33    zones(filter: { zoneTag: $zoneTag }) {
34      httpRequestsAdaptiveGroups(
35        filter: { datetime_gt: $start, datetime_lt: $end }
36        limit: 10
37        orderBy: [count_DESC]
38      ) {
39        count
40        dimensions { clientCountryName }
41      }
42    }
43  }
44}
45```
46 
47Use `orderBy: [sum_edgeResponseBytes_DESC]` for top paths by bandwidth. Add `edgeResponseStatus_geq: 400` to the filter for top error status codes.
48 
49## Workers Analytics
50 
51```graphql
52query WorkersOverview($accountTag: string!, $start: Time!, $end: Time!) {
53  viewer {
54    accounts(filter: { accountTag: $accountTag }) {
55      workersInvocationsAdaptive(
56        filter: { datetime_gt: $start, datetime_lt: $end }
57        limit: 100
58        orderBy: [sum_requests_DESC]
59      ) {
60        sum { requests errors subrequests wallTime }
61        quantiles { cpuTimeP50 cpuTimeP99 wallTimeP50 wallTimeP99 }
62        dimensions { scriptName }
63      }
64    }
65  }
66}
67```
68 
69Filter by `scriptName` for a specific Worker. Add `datetimeFiveMinutes` dimension + `orderBy: [datetimeFiveMinutes_ASC]` for error rate over time.
70 
71## Firewall / Security
72 
73```graphql
74query RecentFirewallEvents($zoneTag: string!, $start: Time!) {
75  viewer {
76    zones(filter: { zoneTag: $zoneTag }) {
77      firewallEventsAdaptive(
78        filter: { datetime_gt: $start }
79        limit: 50
80        orderBy: [datetime_DESC]
81      ) {
82        action source clientIP clientCountryName userAgent
83        clientRequestHTTPHost clientRequestPath ruleId datetime
84      }
85    }
86  }
87}
88```
89 
90For aggregated firewall stats, use `firewallEventsAdaptiveGroups` with `action: "block"` filter and group by `ruleId`, `source`, `datetimeHour`.
91 
92## DNS Analytics
93 
94```graphql
95query DNSQueryVolume($zoneTag: string!, $start: Time!, $end: Time!) {
96  viewer {
97    zones(filter: { zoneTag: $zoneTag }) {
98      dnsAnalyticsAdaptiveGroups(
99        filter: { datetime_gt: $start, datetime_lt: $end }
100        limit: 500
101        orderBy: [datetimeFiveMinutes_ASC]
102      ) {
103        count
104        dimensions { datetimeFiveMinutes }
105      }
106    }
107  }
108}
109```
110 
111## Storage Analytics (Account-Scoped)
112 
113R2, KV, and D1 use `date` (Date type) filters instead of `datetime` (Time type).
114 
115```graphql
116# R2 operations
117r2OperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
118  dimensions { date bucketName actionType }
119  sum { requests }
120}
121 
122# KV operations
123kvOperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
124  dimensions { date actionType }
125  sum { requests }
126}
127 
128# D1 analytics
129d1AnalyticsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
130  dimensions { date databaseId }
131  sum { readQueries writeQueries rowsRead rowsWritten }
132}
133```
134 
135## Cache Analytics
136 
137```graphql
138query CacheStatusBreakdown($zoneTag: string!, $start: Time!, $end: Time!) {
139  viewer {
140    zones(filter: { zoneTag: $zoneTag }) {
141      httpRequestsAdaptiveGroups(
142        filter: { datetime_gt: $start, datetime_lt: $end }
143        limit: 20
144        orderBy: [count_DESC]
145      ) {
146        count
147        dimensions { cacheStatus }
148        sum { edgeResponseBytes }
149      }
150    }
151  }
152}
153```
154 
155For cache hit ratio over time, use aliases to query the same dataset twice — once with `cacheStatus: "hit"` filter and once without — then compute the ratio client-side.
156 
157## Multi-Dataset Queries
158 
159A single request can query multiple datasets, avoiding extra HTTP round-trips:
160 
161```graphql
162query DashboardOverview($zoneTag: string!, $start: Time!, $end: Time!) {
163  viewer {
164    zones(filter: { zoneTag: $zoneTag }) {
165      httpTraffic: httpRequestsAdaptiveGroups(
166        filter: { datetime_gt: $start, datetime_lt: $end }, limit: 1
167      ) { count  sum { edgeResponseBytes }  ratio { status4xx status5xx } }
168      firewallEvents: firewallEventsAdaptiveGroups(
169        filter: { datetime_gt: $start, datetime_lt: $end }, limit: 5, orderBy: [count_DESC]
170      ) { count  dimensions { action source } }
171      dnsQueries: dnsAnalyticsAdaptiveGroups(
172        filter: { datetime_gt: $start, datetime_lt: $end }, limit: 1
173      ) { count }
174    }
175  }
176}
177```
178 
179## AI & Gateway Analytics
180 
181```graphql
182# Workers AI inference
183aiInferenceAdaptiveGroups(
184  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
185) {
186  count
187  sum { totalInputTokens totalOutputTokens totalRequestBytesIn }
188  dimensions { modelId datetimeHour }
189}
190 
191# AI Gateway requests
192aiGatewayRequestsAdaptiveGroups(
193  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
194) {
195  count
196  dimensions { gateway provider model datetimeHour }
197  sum { cachedTokensIn cachedTokensOut uncachedTokensIn uncachedTokensOut }
198}
199```
200 
201Both are account-scoped — nest under `accounts(filter: { accountTag: $accountTag })`.
202 
203## Best Practices
204 
205**Always include time filters.** Queries without time filters scan all data and are slow/expensive.
206 
207**Match time granularity to range:**
208 
209| Time Range | Recommended Dimension |
210|------------|----------------------|
211| < 6 hours | `datetimeMinute` or `datetimeFiveMinutes` |
212| 6-48 hours | `datetimeFiveMinutes` or `datetimeFifteenMinutes` |
213| 2-14 days | `datetimeHour` |
214| 14+ days | `date` |
215 
216**Use aliases** for querying the same dataset with different filters in one request.
217 
218**Request only needed fields.** Extra dimensions and metrics increase query cost.
219 
220## See Also
221 
222- [README.md](README.md) - Overview, decision tree, dataset index
223- [api.md](api.md) - Query structure, aggregation fields, filtering operators
224- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
225- [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting
226