# BigQuery emulator

> Run BigQuery locally: GoogleSQL datasets, tables, queries, scripting, external tables, and the Storage API on ports 5388 and 5389.
>
> Source: https://local.cloud/services/bigquery/

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.

## 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

Connection

Environment variable

`BIGQUERY_EMULATOR_HOST=http://localhost:5388`

Runtime details

- **Endpoints:** HTTP/REST :5388 · gRPC :5389
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Custom Emulator

## 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](https://local.cloud/docs/)

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

Python:

### 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

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

#### Save as hello.py

```python
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

```bash
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](https://local.cloud/docs/sdk-examples/#bigquery-deterministic-query)

Java:

### 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

```bash
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

```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

```bash
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:

### 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

```bash
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

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [BigQuery emulator feature comparison](https://local.cloud/compare/emulators/?service=bigquery): Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.
- [Official SDK code samples](https://docs.cloud.google.com/bigquery/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

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](https://local.cloud/ai/) 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](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [BigQuery feature reference](https://local.cloud/docs/bigquery-emulator-features/): detailed operation and recovery notes.
- [Official BigQuery documentation](https://docs.cloud.google.com/bigquery/docs/introduction): service concepts and cloud usage.