Examples¶

Every example is a complete, runnable project with its own README.md and make test job. Each example is CI-verified on every PR so they do not drift.

Quickstarts (already shipped)¶

Path	What it demonstrates
`bq-cli-quickstart/`	Five-command `bq` CLI tour (mk dataset → mk table → load → query → rm)
`local-file-load/`	`client.load_table_from_file(io.BytesIO(...))` against `/upload/bigquery/v2/...`

Python integrations¶

Path	What it demonstrates	Known caveats
`python/pytest-integration/`	Flask app + pytest fixture (`bqemu_client`)	—
`python/dbt-local/`	`dbt build` against emulator (seed + model + tests)	—
`python/airflow-dag-test/`	`BigQueryInsertJobOperator` DAG via `dag.test()`	Monkey-patches `google.auth.default` to return `AnonymousCredentials` so the BQ hook skips JWT grant
`python/pyspark-bigquery/`	PySpark `DataFrame` from Storage Read (Arrow)	— (v1.0.0's IPC-format workaround was removed in v1.0.1 — #15 / ADR 0033)

Node.js / TypeScript integrations¶

Path	What it demonstrates
`nodejs/nestjs-app/`	NestJS app + Jest + supertest e2e
`nodejs/cloud-run-local/`	Express service running in a Cloud Run-shaped image

Go integrations¶

Path	What it demonstrates
`go/beam-pipeline/`	Apache Beam Go SDK DirectRunner
`go/dataflow-local/`	Stand-alone Go ETL binary writing to BigQuery

Java / Scala integrations¶

Path	What it demonstrates	Known caveats
`java/spring-boot/`	Spring Boot repository + Testcontainers integration test	—
`java/scio/`	Spotify Scio (Scala-on-Beam) pipeline + ScalaTest. End-to-end `CustomersPipeline.run` writes 3 rows via Beam's BATCH_LOADS and the emulator returns them on read — closed in v1.0.2 via a per-example `EmulatorBigQueryServices` injected through `BigQueryIO.Write.withTestServices(...)` and a `fsouza/fake-gcs-server` sidecar for the GCS staging step (#17, ADR 0034).	—

Compose stacks¶

Path	What it demonstrates
`docker-compose/full-stack/`	App + emulator + Prometheus + Grafana, one `docker compose up`

CI/CD recipes¶

Path	What it demonstrates
`ci-recipes/github-actions/`	`services:` container pattern + Testcontainers pattern
`ci-recipes/gitlab-ci/`	`services:` with the `bqemulator` alias on the CI network
`ci-recipes/circleci/`	Docker secondary executor + machine executor patterns

Structure conventions¶

Each example provides:

README.md — what it demonstrates, how to run, what to look for.
Makefile with a test target run in CI.
Pinned dependency versions (where applicable).
A link from the relevant guide in docs/guides/ (where applicable).

Running an example locally¶

Most examples assume:

bqemulator is on $PATH (pip install bqemulator), or
docker can pull ghcr.io/jjviscomi/bqemulator:dev.

The README in each subdirectory documents toolchain-specific prerequisites (Node + npm, Go 1.22+, JDK 17 + Maven, Spark, dbt, etc.).

CI¶

Each example has its own job in .github/workflows/examples.yml. The job builds (or pulls) the dev image and runs the example's make test. The examples workflow is not a required check on the main pipeline — a flaky upstream dependency (dbt-core release, Spark upgrade, etc.) should not block emulator PRs.