BigQuery

Lightweight, dependency-free fake of Google Cloud BigQuery that speaks the real BigQuery v2 REST API (https://bigquery.googleapis.com/bigquery/v2), so application code using @google-cloud/bigquery can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { BigqueryServer } from "./services/bigquery/src/server.js";

const server = new BigqueryServer(4583);
await server.start();
// ... use it ...
await server.stop();

Connect with the real BigQuery client. Two things route it to the parlel fake:

1. Set BIGQUERY_EMULATOR_HOST before constructing the client — its value becomes the client's baseUrl.
2. Inject an offline auth client so the common layer does not attempt a real OAuth token exchange against Google. The fake never validates tokens.

process.env.BIGQUERY_EMULATOR_HOST = "http://127.0.0.1:4583";

import { BigQuery } from "@google-cloud/bigquery";
import { GoogleAuth } from "google-auth-library";

// A no-network auth client: authorizeRequest is a no-op that injects a fake
// bearer token. The fake never checks it.
const auth = new GoogleAuth({ projectId: "parlel" });
auth.authorizeRequest = async (opts = {}) => {
  opts.headers = opts.headers || {};
  opts.headers.Authorization = "Bearer parlel-fake-token";
  return opts;
};
auth.getProjectId = async () => "parlel";

const bq = new BigQuery({ projectId: "parlel", authClient: auth });

// Create a dataset + table
const [dataset] = await bq.createDataset("analytics");
const [table] = await dataset.createTable("events", {
  schema: [
    { name: "id", type: "INTEGER" },
    { name: "name", type: "STRING" },
    { name: "ts", type: "TIMESTAMP" },
  ],
});

// Stream rows in
await table.insert([
  { id: 1, name: "signup", ts: "2024-01-01T00:00:00Z" },
  { id: 2, name: "purchase", ts: "2024-01-02T00:00:00Z" },
]);

// Query
const [rows] = await bq.query("SELECT name FROM analytics.events WHERE id = @id", {
  params: { id: 1 },
});
console.log(rows); // [{ name: "signup" }]

// Parameterised / job-based query
const [job] = await bq.createQueryJob({ query: "SELECT COUNT(*) AS c FROM analytics.events" });
const [results] = await job.getQueryResults();
console.log(results); // [{ c: 2 }]

The endpoint URL the client composes is {BIGQUERY_EMULATOR_HOST}/projects/{projectId}/{uri} — this server implements the full BigQuery v2 resource tree under /projects/{projectId}/….

Implemented operations

Datasets

Tables

Jobs & Queries

Routines

Models

Internal parlel endpoints (not part of BigQuery)

SQL engine

Queries (jobs.query and query jobs) run through a small, pragmatic SQL subset sufficient for testing application logic:

• SELECT <literals> with no FROM (e.g. SELECT 1 AS one, 'hi' AS greeting)
• SELECT * | col, col AS alias FROM [project.]dataset.table
• WHERE with =, !=, <>, >, <, >=, <=, IS [NOT] NULL, and AND-joined predicates
• ORDER BY col [ASC|DESC] (multiple keys)
• LIMIT n
• SELECT COUNT(*) [AS alias] FROM …
• Named (@name) and positional (?) query parameters
• DDL/DML statements (CREATE/INSERT/UPDATE/DELETE/MERGE/DROP) are accepted and reported with the correct statementType but produce no rows.

Rows are returned in BigQuery's wire shape — { f: [{ v }, …] } paired with a schema.fields array — and the client merges them back into plain objects.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors follow the Google-API JSON envelope the client expects:

{
  "error": {
    "code": 404,
    "message": "Not found: Dataset parlel:missing",
    "status": "NOT_FOUND",
    "errors": [
      { "message": "Not found: Dataset parlel:missing", "domain": "global", "reason": "notFound" }
    ]
  }
}

The HTTP status equals error.code. Common codes:

Streaming insert validation errors are returned inside a 200 response as insertErrors: [{ index, errors: [{ reason, message }] }], matching tabledata.insertAll; the client raises a PartialFailureError from them.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

BIGQUERY_EMULATOR_HOST=http://parlel-bridge:4583
GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel