Index of every page on this site: llms.txt
Skip to content

Query

Filter expressions

query accepts prefix-encoded filter expressions for --query, --page, --country, --device, --search-appearance:

PrefixOperator
(bare)equals
~foocontains
!~foonot contains
re:fooregex
!re:foonot regex
!foonot equals
# pages under /blog/ with brand mentions in the query
gscdump query --live --site example.com \
  --page '~/blog/' --query '~brand' --dimensions page,query

--limit and --format override saved defaultLimit and defaultFormat values. Without saved values, queries use 1000 rows and JSON. Limits must be positive integers. Formats must be table, json, or csv.

Rows come in click order, most clicks first. If date is a dimension, rows come in date order, oldest first. Store queries, Hosted mode queries, and live queries use the same order, so --limit keeps the same rows from each source.

Without dates, a query reads the last 28 days that end on the newest synced day of the table it reads. With --live, the window ends three days ago, Pacific time: the newest final GSC date. --start alone runs to that end date. --end alone reads the 28 days that end on it. Dates must use YYYY-MM-DD, and --start cannot follow --end.

--page accepts a path or a full URL. The Store compares paths, so https://example.com/a matches /a. Live queries expand a path to the Site's origin. For a domain property, a path matches that path on any host. Filtered dimensions choose the Store table too: -d query --page /a reads page_queries. If no Store table holds every dimension and filter, the query fails and names --live. If the matching table exists but has no synced rows, an authenticated query can answer live instead. Check meta.source before describing a result as saved Store data.

# Export query rows with a CSV header.
gscdump query --live --site example.com \
  --dimensions page,query --format csv --output rows.csv

For API request examples, see the Search Analytics query guide.

SQL over the Store

query --sql runs DuckDB SQL over one view per Store table. Run query --schema to list the views, their columns, and their date ranges.

gscdump query --format json --sql "
  SELECT p.page, SUM(q.clicks) AS clicks, gsc_position(q.sum_position, q.impressions) AS position
  FROM pages p JOIN page_queries q USING (site, search_type, url, date)
  WHERE p.search_type = 'web' AND p.date >= DATE '2026-08-01'
  GROUP BY p.page ORDER BY clicks DESC LIMIT 20"
ColumnMeaning
siteThe Site URL, such as sc-domain:example.com
search_typeweb, image, video, news, discover, or googleNews
url, pageThe page path. page is the same value as url
sum_positionZero-based position multiplied by impressions
  • The Store keeps every search type. Filter or group by search_type, or a SUM adds web, image, and Discover rows together.
  • gsc_position(sum_position, impressions) returns the impression-weighted average position. Use it with GROUP BY.
  • The views cover every Site in the Store. --site and --type narrow them.
  • Dates return as YYYY-MM-DD. Integers return as numbers, and an integer past 2^53 returns as a string.
  • If the SQL names a table with no synced data, the CLI prints a warning.

Routing

In Hosted mode, query reads the hosted record on gscdump.com and never calls Google. JSON output has meta.source: "hosted". If the hosted record cannot serve the dates yet, query stops and exits 1. It says why and names the next step:

Error: The Site's record is not readable yet.
Sync finished at 2026-10-01 03:16 UTC. gscdump prepares the record for reads after Sync. Try again in a few minutes.

--live needs Local mode. --sql and --schema read the local Store in either mode.

In Local mode, login is optional. Log in with your own Google credentials, or sync a local Store. query, analyze, and report pick one source for each run:

  • If the Store covers every date the run needs, the run reads the Store. This is also true while a sync runs.
  • If the Store has no data and Google is connected, a live-capable run asks Search Console. stderr names the live fallback. JSON output has meta.source: "live". Stored-only Analyzers and Reports still need a Store.
  • If the Store has no data and Google is not connected, the run stops and names gscdump init.
  • If some dates are missing, the run stops and prints a gscdump sync command. Use --live only when that Analyzer or Report supports live rows.
  • If a sync for the Site is running and the dates are not covered yet, the run stops with Sync running: 41 of 90 days done. A sync without a heartbeat in the last 2 minutes counts as stopped.

One run never mixes Store rows and live rows. Live results hold the top rows of each request, and synced data keeps more of the long tail. query --sql reads the Store only. With JSON output, every failure prints { "error": { "code", "message", "nextCommand" } } on stdout and exits 1. JSON output means --format json, --json, or the default format of query. A stop has its own code. Examples: USAGE for an invalid option value such as --limit 0, and the Hosted mode codes NO_SITES, SITE_NOT_FOUND, RECORD_NOT_READY, and RANGE_NOT_SYNCED. Any other failure has the code FAILED, such as a network or API error, or UNEXPECTED, a defect in the CLI.

{
  "error": {
    "code": "USAGE",
    "message": "Invalid --limit. Use a positive safe integer, such as --limit 1000.",
    "nextCommand": null
  }
}

The Store’s quota ledger tracks Search Analytics, URL Inspection, and Indexing API publish calls. Each API has separate limits. Other applications can also spend your Google quota. When a limit is reached, the command stops and prints a retry time.