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..7e62ec3c8bd9d41 --- /dev/null +++ b/src/content/changelog/workers/2025-12-30-wrangler-analytics-engine-cli.mdx @@ -0,0 +1,38 @@ +--- +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 +--- + +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: + + + +```ts +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 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. + +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 new file mode 100644 index 000000000000000..1c20a48769bff59 --- /dev/null +++ b/src/content/docs/analytics/analytics-engine/cli-querying.mdx @@ -0,0 +1,107 @@ +--- +title: Querying from CLI +pcx_content_type: reference +sidebar: + order: 5 +head: + - tag: title + content: Querying Workers Analytics Engine from CLI +--- + +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: + +```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 + +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 +``` + +## Use 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..6eefde63732a3f4 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,49 @@ Manage your Workers [Queues](/queues/) configurations. --- +## `analytics-engine` + +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 [QUERY] [OPTIONS] +``` + +- `QUERY` + - The SQL query to execute. Either `QUERY` or `--file` must be provided. +- `--file` + - 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. + + + +### 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.