BigQuery emulator

BigQuery is a SQL analytics warehouse for exploring and transforming datasets. It is designed for reporting, aggregations, and analytical pipelines rather than individual application record updates.

When to use BigQuery

Typical uses

Use when you need to scan datasets, join analytical tables, and calculate aggregates with SQL. Validate reporting queries and transformation outputs against small local fixtures.

Examples

Analytics and business reporting
SQL transformations and model experiments

Example usage

Service ID: bigquery. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and BIGQUERY_EMULATOR_HOST
eval "$(localcloud env)"

Python

Run a deterministic GoogleSQL query

Run a deterministic SQL query; BigQuery provides tabular results for analytical application workflows.

Configure the REST endpoint and anonymous credentials, then query a hello-world message.

SDK dependencies

Run in a new example directory

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigquery

Save as hello.py

import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

client = bigquery.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
)
rows = list(client.query("SELECT 'Hello from LocalCloud!' AS message").result(timeout=30))
assert rows[0].message == 'Hello from LocalCloud!'
print(rows[0].message)
client.close()

Run the example

python hello.py

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

Full example guide

Java

Run a GoogleSQL query

Run a SQL query and read its result; BigQuery lets analytical code transform and summarize datasets.

BigQuery needs an explicit HTTP endpoint and local anonymous credentials. Requires JDK 17+ and Maven.

SDK dependencies

Run in a new example directory

cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-bigquery</artifactId><version>2.73.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt

Save as Hello.java

import com.google.cloud.NoCredentials;
import com.google.cloud.bigquery.*;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var client = BigQueryOptions.newBuilder()
        .setProjectId(Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT")))
        .setHost(Objects.requireNonNull(System.getenv("BIGQUERY_EMULATOR_HOST")))
        .setCredentials(NoCredentials.getInstance()).build().getService();
    var query = QueryJobConfiguration.newBuilder("SELECT 'Hello from LocalCloud!' AS message")
        .setUseLegacySql(false).build();
    var job = client.create(JobInfo.of(query)).waitFor();
    for (var row : job.getQueryResults().iterateAll()) {
      System.out.println(row.get("message").getStringValue());
    }
  }
}

Run the example

java --class-path "$(cat classpath.txt)" Hello.java

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

HTTP

Run a GoogleSQL query over HTTP

Submit a SQL query over HTTP; BigQuery returns tabular results for analytics and data transformations.

Send a query directly to the BigQuery REST API with curl.

Run in your terminal

curl --fail-with-body "${BIGQUERY_EMULATOR_HOST%/}/bigquery/v2/projects/${GOOGLE_CLOUD_PROJECT}/queries" \
  -H 'Content-Type: application/json' \
  -d '{"query":"SELECT 1 AS value","useLegacySql":false}'

Verify the result

The query response contains a row whose value is 1. A successful HTTP status alone does not verify the query result.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

Datasets, tables, clones, and time travel

Create a dataset and table, load deterministic rows, and test clone or time-travel reads used by your application. Compare row values and schema, then remove the owned dataset.
Row access policies, top-level policy tags, and masking

Apply a row access policy or top-level policy tag and query as the relevant local principal. Assert both visible rows and masked values through the client path you deploy.
Joins, window functions, CTEs, PIVOT/UNPIVOT, and MERGE

Load a small input dataset and run joins, window functions, CTEs, PIVOT, or MERGE. Compare exact rows and expected errors before using the query in a larger pipeline.
Procedural scripts, stored procedures, and dynamic SQL

Run a multi-statement script or stored procedure against fixtures, including dynamic SQL if needed. Check variable handling, statement results, and failure behavior.
Jobs, dry runs, scheduled queries, and selected ML models

Submit a job, inspect its result and dry-run response, and test scheduled-query configuration. For a supported ML model, train on a small fixture and assert prediction output.
Materialized views and INFORMATION_SCHEMA

Create a materialized view and query it after changing source data. Use INFORMATION_SCHEMA to assert the metadata your migration or discovery tool relies on.
Emulated GCS: CSV, JSONL, Parquet, Avro, ORC; EXTERNAL_QUERY

Upload a supported CSV, JSONL, Parquet, Avro, or ORC fixture to local Storage, then query its external table. Exercise EXTERNAL_QUERY with the specific supported connection your application uses.
gRPC Storage Read/Write with Avro and Arrow

Configure the separate gRPC Storage endpoint and CA trust, then read or write Avro or Arrow records. Compare schema and row contents independently of the REST query client.

Service boundaries

SQL, ML, and geography have input-specific limits; ingestion-time pseudocolumn reads and nested policy tags are unavailable
External tables use local GCS; native Bigtable, Sheets, HTTP, and local-file sources are unavailable
Managed reservations, production IAM, and fleet scale require Google Cloud

Code examples and integrations

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Comparison

BigQuery emulator feature comparison

Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.

Open guide

Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples

Agent testing

Use BigQuery with an AI agent

Before the agent changes application logic, have it create local BigQuery state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

BigQuery local test

Use LocalCloud to test BigQuery code locally. Read https://local.cloud/ai/agents.md and the BigQuery docs, set BIGQUERY_EMULATOR_HOST for localhost, create a local dataset/table, insert sample rows, run a representative query, and call out any unsupported SQL features instead of using real BigQuery.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

BigQuery emulator FAQ

How do I run BigQuery locally?

Start LocalCloud using the setup guide, then export its environment in the same terminal as your application.

Which environment variable points the SDK at the local BigQuery?

LocalCloud exports BIGQUERY_EMULATOR_HOST=http://localhost:5388. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

Does the local BigQuery behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real BigQuery before production deployment.

Related guides

Compatibility: compare all 27 service guides.
Configuration: service selection and runtime settings.
BigQuery feature reference: detailed operation and recovery notes.
Official BigQuery documentation : service concepts and cloud usage.

BigQuery emulator

Typical uses

Explore another service

Example usage

Python

Run a deterministic GoogleSQL query

Save as hello.py

Run the example

Verify the result

Expected output

Java

Run a GoogleSQL query

Save as Hello.java

Run the example

Verify the result

Expected output

HTTP

Run a GoogleSQL query over HTTP

Run in your terminal

Verify the result

Documented workflows

Datasets, tables, clones, and time travel

Row access policies, top-level policy tags, and masking

Joins, window functions, CTEs, PIVOT/UNPIVOT, and MERGE

Procedural scripts, stored procedures, and dynamic SQL

Jobs, dry runs, scheduled queries, and selected ML models

Materialized views and INFORMATION_SCHEMA

Emulated GCS: CSV, JSONL, Parquet, Avro, ORC; EXTERNAL_QUERY

gRPC Storage Read/Write with Avro and Arrow

Service boundaries

Code examples and integrations

Build an integration test loop

BigQuery emulator feature comparison

Official SDK code samples

Use BigQuery with an AI agent

BigQuery local test

BigQuery emulator FAQ

How do I run BigQuery locally?

Which environment variable points the SDK at the local BigQuery?

Does the local BigQuery behave exactly like Google Cloud?

Related guides