How to Run Your First BigQuery Query (Console + bq CLI)

Simple explanation

BigQuery is a serverless data warehouse. You do not manage servers, install software, or create indexes. You write a SQL query, BigQuery fans the work across thousands of machines, and results come back in seconds.

”Running a query” means: you send SQL to BigQuery, it reads only the columns your query references from its columnar storage, processes the data, and returns the result. You pay based on how many bytes it read, not how long it took or how many rows came back.

What you will do

• Run a SQL query against a public dataset in the BigQuery console
• Read the bytes-scanned counter and understand what it means
• Run the same query from the bq CLI
• Run a dry run to estimate cost before executing
• See why SELECT * costs more than selecting specific columns
• Learn why LIMIT does not reduce bytes scanned

Before you start

Open the BigQuery console. Go to console.cloud.google.com/bigquery. Make sure the correct project is selected in the project dropdown at the top of the page. If you are not sure how the Cloud Console works, read that page first.

Billing is optional for this walkthrough. BigQuery has a sandbox mode that works without a billing account. You get 1 TB of free query processing per month and can query any public dataset. The sandbox restricts some features (no streaming inserts, tables expire after 60 days), but everything on this page works in the sandbox. See the GCP Free Tier page for the full breakdown.

Public datasets. BigQuery hosts hundreds of datasets under the bigquery-public-data project. To browse them, click + Add in the Explorer panel, then select Public datasets. The queries on this page use the bigquery-public-data.usa_names.usa_1910_2013 table, a small dataset of baby names by year and state.

For CLI steps: Cloud Shell vs local install. The bq tool comes pre-installed in Cloud Shell, which you can open from any browser with no setup.

Run your first query in the BigQuery console

Step 1. Open the BigQuery console and click + Compose a new query (or use the SQL editor that is already open).

Step 2. Paste this query into the editor:

SELECT
  name,
  SUM(number) AS total
FROM `bigquery-public-data.usa_names.usa_1910_2013`
WHERE state = 'TX'
GROUP BY name
ORDER BY total DESC
LIMIT 10;

This finds the 10 most popular baby names in Texas across all years in the dataset. The table is small (about 6 MB), so this query is well within free-tier limits.

Step 3. Before clicking Run, look at the bottom-right corner of the editor. The query validator shows a green checkmark and an estimate like “This query will process 51.3 MB when run.” That estimate is your built-in cost preview.

Step 4. Click Run. Results appear in the panel below within a few seconds.

Step 5. Click the Job information tab above the results. This shows bytes processed, bytes billed, slot time used, and whether the result came from cache. Check this after every query. It is the fastest way to build cost intuition.

Run the same idea with the bq CLI

Open Cloud Shell from the console (the terminal icon in the top-right toolbar), or use a local terminal where you have the gcloud CLI installed and authenticated.

Run the query:

bq query \
  --use_legacy_sql=false \
  'SELECT name, SUM(number) AS total
   FROM `bigquery-public-data.usa_names.usa_1910_2013`
   WHERE state = "TX"
   GROUP BY name
   ORDER BY total DESC
   LIMIT 10'

The —use_legacy_sql=false flag tells bq to use GoogleSQL (standard SQL). Without it, bq defaults to legacy SQL, which is an older dialect that does not support modern features like WITH clauses, STRUCT, or ARRAY. Always include this flag.

Run a dry run first:

bq query \
  --use_legacy_sql=false \
  --dry_run \
  'SELECT name, SUM(number) AS total
   FROM `bigquery-public-data.usa_names.usa_1910_2013`
   WHERE state = "TX"
   GROUP BY name
   ORDER BY total DESC
   LIMIT 10'

A dry run validates the SQL and prints the estimated bytes that would be scanned. It does not execute the query or use any quota. The output looks like:

Query successfully validated. Assuming the tables are not modified,
running this query will process 51361861 bytes of data.

Run a dry run before executing any query on a table whose size you do not know. It is free and takes less than a second.

--use_legacy_sql=false

How BigQuery decides cost and performance

Bytes scanned is the core cost metric. On on-demand pricing, you pay per byte scanned. The current rate is $6.25 per TB after the first free 1 TB each month. The query itself can take 2 seconds or 20 seconds. The cost is the same if both queries scan the same bytes.

Why SELECT * is expensive. BigQuery uses columnar storage. It only reads the columns your query actually references. SELECT * forces it to read every column in the table. On a 50-column table where you only need 3 columns, SELECT * scans roughly 17 times more data. Always name the columns you need.

Dry runs show cost before you spend anything. In the console, the validator shows estimated bytes as you type. In the CLI, the —dry_run flag does the same thing. Use both. There is no reason to guess what a query will cost.

Cached results are free. BigQuery caches query results for 24 hours. If you run the exact same query on unchanged data, the second run is free and returns instantly. The cache is per-user. Changing even a single space in the SQL invalidates the cache.

Console vs bq CLI

Cloud Shell is the easiest bridge between the two. It gives you a terminal with bq pre-installed and pre-authenticated, directly inside the console. No local install, no authentication steps. Start there if you want to try the CLI without any setup.

When to use this

• You are new to BigQuery and want to see how it works before reading about architecture or pricing theory.
• You want to explore a public dataset before deciding whether to load your own data.
• You need to run a quick ad-hoc query on data that already exists in BigQuery: checking row counts, sampling values, or verifying a load.
• You are evaluating BigQuery vs another tool like Cloud SQL and want to feel the difference between an analytical warehouse and a transactional database.
• You are building a script or pipeline and need to validate that your SQL works before automating it with the bq CLI.

Common errors and quick fixes