From c8157d4f020811f6d254fae702baf30d6d7a4514 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 30 Dec 2025 13:50:50 -0500 Subject: [PATCH 1/5] docs: add wrangler analytics-engine command documentation - Add analytics-engine command to Wrangler commands reference - Create new 'Querying from CLI' page in Analytics Engine docs - Update get-started guide to show Wrangler as a query option --- .../analytics-engine/cli-querying.mdx | 113 ++++++++++++++++++ .../analytics-engine/get-started.mdx | 19 ++- .../docs/workers/wrangler/commands.mdx | 40 +++++++ 3 files changed, 166 insertions(+), 6 deletions(-) create mode 100644 src/content/docs/analytics/analytics-engine/cli-querying.mdx diff --git a/src/content/docs/analytics/analytics-engine/cli-querying.mdx b/src/content/docs/analytics/analytics-engine/cli-querying.mdx new file mode 100644 index 000000000000000..c2a1bfda7b3c852 --- /dev/null +++ b/src/content/docs/analytics/analytics-engine/cli-querying.mdx @@ -0,0 +1,113 @@ +--- +title: Querying from CLI +pcx_content_type: reference +sidebar: + order: 5 +head: + - tag: title + content: Querying Workers Analytics Engine from CLI +--- + +import { PackageManagers } from "~/components"; + +You can query Workers Analytics Engine datasets directly from the command line using Wrangler. This is useful for ad-hoc queries, debugging, and scripting. + +## Prerequisites + +Before you can query Analytics Engine from the CLI, you need: + +1. [Wrangler installed](/workers/wrangler/install-and-update/) (version 4.0.0 or later) +2. Authentication configured via `wrangler login` or a `CLOUDFLARE_API_TOKEN` environment variable with the `Account Analytics Read` permission + +## Basic usage + +Run a query directly: + + + +Run a query from a file: + + + +## Output formats + +By default, results are displayed as a table when running interactively, or as JSON when piped to another command. + +You can explicitly set the output format: + +```sh +# Table format (default for interactive) +npx wrangler analytics-engine run "SELECT * FROM my_dataset" --format=table + +# JSON format (default for non-interactive) +npx wrangler analytics-engine run "SELECT * FROM my_dataset" --format=json +``` + +JSON output is useful for piping to other tools like `jq`: + +```sh +npx wrangler analytics-engine run "SELECT * FROM my_dataset" --format=json | jq '.data[0]' +``` + +## Example queries + +### List all datasets + +```sh +npx wrangler analytics-engine run "SHOW TABLES" +``` + +### Query with time filtering + +```sh +npx wrangler analytics-engine run "SELECT blob1 AS city, AVG(double1) AS avg_temp FROM weather WHERE timestamp > NOW() - INTERVAL '1' DAY GROUP BY city" +``` + +### Query from a file + +Create a file `query.sql`: + +```sql +SELECT + intDiv(toUInt32(timestamp), 300) * 300 AS t, + blob1 AS city, + SUM(_sample_interval * double1) / SUM(_sample_interval) AS avg_temp +FROM weather +WHERE timestamp >= NOW() - INTERVAL '1' DAY +GROUP BY t, city +ORDER BY t, city +``` + +Then run: + +```sh +npx wrangler analytics-engine run --file=query.sql +``` + +## Using in scripts + +The CLI is useful for automation and scripting. For example, you can create a daily report: + +```bash +#!/bin/bash + +# Query yesterday's data and save to a file +npx wrangler analytics-engine run \ + "SELECT blob1 AS endpoint, SUM(_sample_interval) AS request_count FROM api_requests WHERE timestamp >= NOW() - INTERVAL '1' DAY GROUP BY endpoint ORDER BY request_count DESC" \ + --format=json > daily_report.json +``` + +## Related resources + +- [SQL API reference](/analytics/analytics-engine/sql-api/) - Direct HTTP API access +- [SQL reference](/analytics/analytics-engine/sql-reference/) - Full SQL syntax documentation +- [Querying from a Worker](/analytics/analytics-engine/worker-querying/) - Query from within a Worker +- [Querying from Grafana](/analytics/analytics-engine/grafana/) - Visualize data in Grafana diff --git a/src/content/docs/analytics/analytics-engine/get-started.mdx b/src/content/docs/analytics/analytics-engine/get-started.mdx index 9231242c6fe04f2..8bc2d66024ef7be 100644 --- a/src/content/docs/analytics/analytics-engine/get-started.mdx +++ b/src/content/docs/analytics/analytics-engine/get-started.mdx @@ -61,16 +61,17 @@ Currently, the `writeDataPoint()` API accepts ordered arrays of values. This mea ## 3. Query data using the SQL API -You can query the data you have written in two ways: +You can query the data you have written in several ways: -* [**SQL API**](/analytics/analytics-engine/sql-api) — Best for writing your own queries and integrating with external tools like Grafana. -* [**GraphQL API**](/analytics/graphql-api/) — This is the same API that powers the Cloudflare dashboard. +* [**Wrangler CLI**](/analytics/analytics-engine/cli-querying/) — Query directly from the command line using `wrangler analytics-engine`. +* [**SQL API**](/analytics/analytics-engine/sql-api/) — Best for writing your own queries and integrating with external tools like Grafana. +* [**GraphQL API**](/analytics/graphql-api/) — This is the same API that powers the Cloudflare dashboard. -For the purpose of this example, we will use the SQL API. +For the purpose of this example, we will use Wrangler or the SQL API. ### Create an API token -Create an [API Token](https://dash.cloudflare.com/profile/api-tokens) that has the `Account Analytics Read` permission. +Create an [API Token](https://dash.cloudflare.com/profile/api-tokens) that has the `Account Analytics Read` permission. If you are using Wrangler and have already run `wrangler login`, you can skip this step. ### Write your first query @@ -92,7 +93,13 @@ LIMIT 10 We are using a custom averaging function to take [sampling](/analytics/analytics-engine/sql-api/#sampling) into account. ::: -You can run this query by making an HTTP request to the SQL API: +You can run this query using Wrangler: + +```sh +npx wrangler analytics-engine run "SELECT blob1 AS city, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity FROM WEATHER WHERE double1 > 0 GROUP BY city ORDER BY avg_humidity DESC LIMIT 10" +``` + +Or by making an HTTP request to the SQL API: ```bash curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \ diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index c74fb1f739f9783..f040c19afd0daa6 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -47,6 +47,7 @@ Wrangler offers a number of commands to manage your Cloudflare Workers. - [`pages`](#pages) - Configure Cloudflare Pages. - [`pipelines`](#pipelines) - Configure Cloudflare Pipelines. - [`queues`](#queues) - Configure Workers Queues. +- [`analytics-engine`](#analytics-engine) - Query Workers Analytics Engine datasets. - [`login`](#login) - Authorize Wrangler with your Cloudflare account using OAuth. - [`logout`](#logout) - Remove Wrangler's authorization for accessing your account. - [`whoami`](#whoami) - Retrieve your user information and test your authentication configuration. @@ -613,6 +614,45 @@ Manage your Workers [Queues](/queues/) configurations. --- +## `analytics-engine` + +Query [Workers Analytics Engine](/analytics/analytics-engine/) datasets using the SQL API. + +```txt +wrangler analytics-engine run [OPTIONS] +``` + +- `QUERY` + - The SQL query to execute. Required if `--file` is not provided. +- `--file` + - Path to a file containing the SQL query to execute. Required if `QUERY` is not provided. +- `--format` + - Output format for query results. Defaults to `table` when running in a TTY, `json` otherwise. + + + +### Examples + +Query a dataset directly: + +```sh +npx wrangler analytics-engine run "SELECT * FROM my_dataset LIMIT 10" +``` + +Query from a file: + +```sh +npx wrangler analytics-engine run --file=query.sql +``` + +Output as JSON: + +```sh +npx wrangler analytics-engine run "SELECT * FROM my_dataset" --format=json +``` + +--- + ## `login` Authorize Wrangler with your Cloudflare account using OAuth. Wrangler will attempt to automatically open your web browser to login with your Cloudflare account. From edd553b783f77c4109ae537b00140af1c6555f1b Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 30 Dec 2025 14:00:54 -0500 Subject: [PATCH 2/5] docs: address review feedback and add changelog - Add ae alias note to command reference - Change to [QUERY] with clarifying note - Use npx wrangler consistently (remove PackageManagers) - Fix section title to imperative mood - Add changelog entry for Analytics Engine CLI --- ...25-12-30-wrangler-analytics-engine-cli.mdx | 20 +++++++++++++++++++ .../analytics-engine/cli-querying.mdx | 20 +++++++------------ .../docs/workers/wrangler/commands.mdx | 10 +++++++--- 3 files changed, 34 insertions(+), 16 deletions(-) create mode 100644 src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx diff --git a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx new file mode 100644 index 000000000000000..3eacee9d2b5713b --- /dev/null +++ b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx @@ -0,0 +1,20 @@ +--- +title: Query Analytics Engine from the command line +description: Wrangler now supports querying Workers Analytics Engine datasets directly from the CLI. +products: + - workers-analytics-engine + - workers +date: 2025-12-30 +--- + +Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code. + +Workers Analytics Engine lets you ingest high-cardinality data at scale and query it using SQL. Use it to build custom analytics, usage-based billing, or observability tools. With the new `wrangler analytics-engine` command, you can run ad-hoc queries, debug data pipelines, and automate reports from your terminal. + +```sh +npx wrangler analytics-engine run "SELECT blob1 AS city, AVG(double1) AS avg_temp FROM weather GROUP BY city" +``` + +Output defaults to table format in interactive terminals and JSON when piped to other tools like `jq`. Use `--file` to run queries from a SQL file. + +To get started, see [Querying from CLI](/analytics/analytics-engine/cli-querying/) or the [wrangler analytics-engine command reference](/workers/wrangler/commands/#analytics-engine). diff --git a/src/content/docs/analytics/analytics-engine/cli-querying.mdx b/src/content/docs/analytics/analytics-engine/cli-querying.mdx index c2a1bfda7b3c852..1c20a48769bff59 100644 --- a/src/content/docs/analytics/analytics-engine/cli-querying.mdx +++ b/src/content/docs/analytics/analytics-engine/cli-querying.mdx @@ -8,8 +8,6 @@ head: content: Querying Workers Analytics Engine from CLI --- -import { PackageManagers } from "~/components"; - You can query Workers Analytics Engine datasets directly from the command line using Wrangler. This is useful for ad-hoc queries, debugging, and scripting. ## Prerequisites @@ -23,19 +21,15 @@ Before you can query Analytics Engine from the CLI, you need: Run a query directly: - +```sh +npx wrangler analytics-engine run "SELECT * FROM my_dataset LIMIT 10" +``` Run a query from a file: - +```sh +npx wrangler analytics-engine run --file=query.sql +``` ## Output formats @@ -92,7 +86,7 @@ Then run: npx wrangler analytics-engine run --file=query.sql ``` -## Using in scripts +## Use in scripts The CLI is useful for automation and scripting. For example, you can create a daily report: diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index f040c19afd0daa6..6eefde63732a3f4 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -618,14 +618,18 @@ Manage your Workers [Queues](/queues/) configurations. Query [Workers Analytics Engine](/analytics/analytics-engine/) datasets using the SQL API. +:::note +`ae` is available as a shorthand alias for `analytics-engine`. +::: + ```txt -wrangler analytics-engine run [OPTIONS] +wrangler analytics-engine run [QUERY] [OPTIONS] ``` - `QUERY` - - The SQL query to execute. Required if `--file` is not provided. + - The SQL query to execute. Either `QUERY` or `--file` must be provided. - `--file` - - Path to a file containing the SQL query to execute. Required if `QUERY` is not provided. + - Path to a file containing the SQL query to execute. Either `--file` or `QUERY` must be provided. - `--format` - Output format for query results. Defaults to `table` when running in a TTY, `json` otherwise. From a3f510d41402efb21a4f9568d9167d519095ae31 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 30 Dec 2025 14:02:01 -0500 Subject: [PATCH 3/5] Apply suggestion from @elithrar --- .../workers/2025-12-30-wrangler-analytics-engine-cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx index 3eacee9d2b5713b..9c7e739b2f179cc 100644 --- a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx +++ b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx @@ -7,7 +7,7 @@ products: date: 2025-12-30 --- -Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code. +Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code, plugins or ad-hoc `curl` commands. Workers Analytics Engine lets you ingest high-cardinality data at scale and query it using SQL. Use it to build custom analytics, usage-based billing, or observability tools. With the new `wrangler analytics-engine` command, you can run ad-hoc queries, debug data pipelines, and automate reports from your terminal. From 7bad298dd54183c535cfc859d91c324abd64aad4 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 30 Dec 2025 14:03:18 -0500 Subject: [PATCH 4/5] docs: add writeDataPoint example to changelog for context --- .../2025-12-30-wrangler-analytics-engine-cli.mdx | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx index 9c7e739b2f179cc..2c23c6e322172e8 100644 --- a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx +++ b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx @@ -7,12 +7,24 @@ products: date: 2025-12-30 --- -Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code, plugins or ad-hoc `curl` commands. +Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code or ad-hoc `curl` commands. Workers Analytics Engine lets you ingest high-cardinality data at scale and query it using SQL. Use it to build custom analytics, usage-based billing, or observability tools. With the new `wrangler analytics-engine` command, you can run ad-hoc queries, debug data pipelines, and automate reports from your terminal. +For example, if your Worker tracks product usage: + +```js +env.USAGE.writeDataPoint({ + indexes: ["customer_12345"], + blobs: ["acme-app", "user_789", "file.upload", "enterprise"], + doubles: [1, 2048000], // count, bytes +}); +``` + +You can query that data directly from your terminal: + ```sh -npx wrangler analytics-engine run "SELECT blob1 AS city, AVG(double1) AS avg_temp FROM weather GROUP BY city" +npx wrangler analytics-engine run "SELECT blob1 AS app, blob3 AS action, SUM(double1) AS total FROM usage GROUP BY app, action ORDER BY total DESC" ``` Output defaults to table format in interactive terminals and JSON when piped to other tools like `jq`. Use `--file` to run queries from a SQL file. From 9719b2ec38eed2f4754b188d9e9e2ec18960e471 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Tue, 30 Dec 2025 14:05:15 -0500 Subject: [PATCH 5/5] docs: use TypeScriptExample component for code block --- .../workers/2025-12-30-wrangler-analytics-engine-cli.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx index 2c23c6e322172e8..7e62ec3c8bd9d41 100644 --- a/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx +++ b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx @@ -7,13 +7,17 @@ products: date: 2025-12-30 --- +import { TypeScriptExample } from "~/components"; + Wrangler now supports querying [Workers Analytics Engine](/analytics/analytics-engine/) directly from the command line, allowing you to quickly explore your datasets without writing code or ad-hoc `curl` commands. Workers Analytics Engine lets you ingest high-cardinality data at scale and query it using SQL. Use it to build custom analytics, usage-based billing, or observability tools. With the new `wrangler analytics-engine` command, you can run ad-hoc queries, debug data pipelines, and automate reports from your terminal. For example, if your Worker tracks product usage: -```js + + +```ts env.USAGE.writeDataPoint({ indexes: ["customer_12345"], blobs: ["acme-app", "user_789", "file.upload", "enterprise"], @@ -21,6 +25,8 @@ env.USAGE.writeDataPoint({ }); ``` + + You can query that data directly from your terminal: ```sh