Skip to content

Commit afce9ee

Browse files
OxyjunOxyjun
authored
[D1] Adding info on wrangler d1 insights (#18678)
* Adding more info on the experimental d1 insight wrangler command. * Applying review suggestions. * Adding `insights` into D1 Wrangler commands page.
1 parent d4ece39 commit afce9ee

File tree

2 files changed

+174
-9
lines changed

2 files changed

+174
-9
lines changed

‎src/content/docs/d1/observability/metrics-analytics.mdx‎

Lines changed: 161 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ sidebar:
55
order: 10
66
---
77

8+
import { Details } from "~/components";
9+
810
D1 exposes database analytics that allow you to inspect query volume, query latency, and storage size across all and/or each database in your account.
911

1012
The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.
@@ -138,7 +140,7 @@ query {
138140
}
139141
```
140142

141-
## Query insights
143+
## Query `insights`
142144

143145
D1 provides metrics that let you understand and debug query performance. You can access these via GraphQL's `d1QueriesAdaptiveGroups` or `wrangler d1 insights` command.
144146

@@ -152,22 +154,173 @@ Run `wrangler d1 insights --help` to view current options.
152154

153155
:::
154156

155-
### Examples
157+
| Option | Description |
158+
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
159+
| `--timePeriod` | Fetch data from now to the provided time period (default: `1d`). |
160+
| `--sort-type` | The operation you want to sort insights by. Select between `sum` and `avg` (default: `sum`). |
161+
| `--sort-by` | The field you want to sort insights by. Select between `time`, `reads`, `writes`, and `count` (default: `time`). |
162+
| `--sort-direction` | The sort direction. Select between `ASC` and `DESC` (default: `DESC`). |
163+
| `--json` | A boolean value to specify whether to return the result as clean JSON (default: `false`). |
164+
| `--limit` | The maximum number of queries to be fetched. |
156165

157-
To find top 10 queries by execution count:
166+
<Details header="To find top 3 queries by execution count:">
158167

159168
```sh
160-
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=count --count=10
169+
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=count --limit=3
161170
```
171+
```sh output
172+
⛅️ wrangler 3.95.0
173+
-------------------
174+
175+
-------------------
176+
🚧 `wrangler d1 insights` is an experimental command.
177+
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
178+
-------------------
179+
180+
[
181+
{
182+
"query": "SELECT tbl_name as name,\n (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n FROM sqlite_master\n WHERE TYPE = \"table\"\n AND tbl_name NOT LIKE \"sqlite_%\"\n AND tbl_name NOT LIKE \"d1_%\"\n AND tbl_name NOT LIKE \"_cf_%\"\n ORDER BY tbl_name ASC;",
183+
"avgRowsRead": 2,
184+
"totalRowsRead": 4,
185+
"avgRowsWritten": 0,
186+
"totalRowsWritten": 0,
187+
"avgDurationMs": 0.49505,
188+
"totalDurationMs": 0.9901,
189+
"numberOfTimesRun": 2,
190+
"queryEfficiency": 0
191+
},
192+
{
193+
"query": "SELECT * FROM Customers",
194+
"avgRowsRead": 4,
195+
"totalRowsRead": 4,
196+
"avgRowsWritten": 0,
197+
"totalRowsWritten": 0,
198+
"avgDurationMs": 0.1873,
199+
"totalDurationMs": 0.1873,
200+
"numberOfTimesRun": 1,
201+
"queryEfficiency": 1
202+
},
203+
{
204+
"query": "SELECT * From Customers",
205+
"avgRowsRead": 0,
206+
"totalRowsRead": 0,
207+
"avgRowsWritten": 0,
208+
"totalRowsWritten": 0,
209+
"avgDurationMs": 1.0225,
210+
"totalDurationMs": 1.0225,
211+
"numberOfTimesRun": 1,
212+
"queryEfficiency": 0
213+
}
214+
]
215+
```
216+
</Details>
162217

163-
To find top 10 queries by average execution time:
218+
<Details header="To find top 3 queries by average execution time:">
164219

165220
```sh
166-
npx wrangler d1 insights <database_name> --sort-type=avg --sort-by=time --count=10
221+
npx wrangler d1 insights <database_name> --sort-type=avg --sort-by=time --limit=3
222+
```
223+
```sh output
224+
⛅️ wrangler 3.95.0
225+
-------------------
226+
227+
-------------------
228+
🚧 `wrangler d1 insights` is an experimental command.
229+
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
230+
-------------------
231+
232+
[
233+
{
234+
"query": "SELECT * From Customers",
235+
"avgRowsRead": 0,
236+
"totalRowsRead": 0,
237+
"avgRowsWritten": 0,
238+
"totalRowsWritten": 0,
239+
"avgDurationMs": 1.0225,
240+
"totalDurationMs": 1.0225,
241+
"numberOfTimesRun": 1,
242+
"queryEfficiency": 0
243+
},
244+
{
245+
"query": "SELECT tbl_name as name,\n (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n FROM sqlite_master\n WHERE TYPE = \"table\"\n AND tbl_name NOT LIKE \"sqlite_%\"\n AND tbl_name NOT LIKE \"d1_%\"\n AND tbl_name NOT LIKE \"_cf_%\"\n ORDER BY tbl_name ASC;",
246+
"avgRowsRead": 2,
247+
"totalRowsRead": 4,
248+
"avgRowsWritten": 0,
249+
"totalRowsWritten": 0,
250+
"avgDurationMs": 0.49505,
251+
"totalDurationMs": 0.9901,
252+
"numberOfTimesRun": 2,
253+
"queryEfficiency": 0
254+
},
255+
{
256+
"query": "SELECT * FROM Customers",
257+
"avgRowsRead": 4,
258+
"totalRowsRead": 4,
259+
"avgRowsWritten": 0,
260+
"totalRowsWritten": 0,
261+
"avgDurationMs": 0.1873,
262+
"totalDurationMs": 0.1873,
263+
"numberOfTimesRun": 1,
264+
"queryEfficiency": 1
265+
}
266+
]
167267
```
268+
</Details>
168269

169-
To find top 10 queries by rows written in last 7 days:
270+
<Details header="To find top 10 queries by rows written in last 7 days:">
170271

171272
```sh
172-
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=writes --count=10 --timePeriod=7d
273+
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=writes --limit=10 --timePeriod=7d
173274
```
275+
```sh output
276+
⛅️ wrangler 3.95.0
277+
-------------------
278+
279+
-------------------
280+
🚧 `wrangler d1 insights` is an experimental command.
281+
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
282+
-------------------
283+
284+
[
285+
{
286+
"query": "SELECT * FROM Customers",
287+
"avgRowsRead": 4,
288+
"totalRowsRead": 4,
289+
"avgRowsWritten": 0,
290+
"totalRowsWritten": 0,
291+
"avgDurationMs": 0.1873,
292+
"totalDurationMs": 0.1873,
293+
"numberOfTimesRun": 1,
294+
"queryEfficiency": 1
295+
},
296+
{
297+
"query": "SELECT * From Customers",
298+
"avgRowsRead": 0,
299+
"totalRowsRead": 0,
300+
"avgRowsWritten": 0,
301+
"totalRowsWritten": 0,
302+
"avgDurationMs": 1.0225,
303+
"totalDurationMs": 1.0225,
304+
"numberOfTimesRun": 1,
305+
"queryEfficiency": 0
306+
},
307+
{
308+
"query": "SELECT tbl_name as name,\n (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n FROM sqlite_master\n WHERE TYPE = \"table\"\n AND tbl_name NOT LIKE \"sqlite_%\"\n AND tbl_name NOT LIKE \"d1_%\"\n AND tbl_name NOT LIKE \"_cf_%\"\n ORDER BY tbl_name ASC;",
309+
"avgRowsRead": 2,
310+
"totalRowsRead": 4,
311+
"avgRowsWritten": 0,
312+
"totalRowsWritten": 0,
313+
"avgDurationMs": 0.49505,
314+
"totalDurationMs": 0.9901,
315+
"numberOfTimesRun": 2,
316+
"queryEfficiency": 0
317+
}
318+
]
319+
```
320+
</Details>
321+
322+
:::note
323+
The quantity `queryEfficiency` measures how efficient your query was. It is calculated as: the number of rows returned divided by the number of rows read.
324+
325+
Generally, you should try to get `queryEfficiency` as close to `1` as possible. Refer to [Use indexes](/d1/best-practices/use-indexes/) for more information on efficient querying.
326+
:::

‎src/content/docs/d1/wrangler-commands.mdx‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,16 @@ D1 Wrangler commands use REST APIs to interact with the control plane. This page
1414

1515
## Global commands
1616

17-
<Render file="wrangler-commands/global-flags" product="workers" />
17+
<Render file="wrangler-commands/global-flags" product="workers" />
18+
19+
## Experimental commands
20+
21+
### `insights`
22+
23+
Returns statistics about your queries.
24+
25+
```sh
26+
npx wrangler d1 insights <database_name> --<option>
27+
```
28+
29+
For more information, see [Query `insights`](/d1/observability/metrics-analytics/#query-insights).

0 commit comments

Comments
 (0)