Skip to main content
Explanation

BigQuery Data Warehouse SDK

@ultracart/bigquery-sdk is a Node.js companion to the JavaScript REST API SDK. It runs SQL against your UltraCart data warehouse in BigQuery and streams each row back as a native SDK model instance: Order, Customer, AutoOrder, and the rest of the same classes the REST API returns.

Source and issues: UltraCart/rest_api_v2_sdk_javascript_bigquery.

note

This package is an early release (0.2.0). The authentication, transform, and hydration paths are working and unit tested, and the API surface may still change before 1.0.

When to use it instead of the REST API​

Use it for bulk reads over history: seeding a loyalty portal, a nightly customer export, a reporting pipeline, or any job that would otherwise page through tens of thousands of REST responses. The warehouse answers those in one query, and the REST API rate limits do not apply.

Keep using the REST API for everything else. The warehouse is read-only and lags live data by one to two minutes, so it is the wrong source for writes, for checkout-time lookups, and for anything that must reflect the current state of a single record right now.

JobSource
Full order history for a new systemBigQuery SDK
Nightly sync of what changedBigQuery SDK
Aggregate reporting across linked accountsBigQuery SDK
Creating or updating any objectREST API
Reading one order during checkoutREST API

Why the objects line up​

The warehouse tables are generated from the same domain model that powers the REST API, so column names and nesting already match the SDK model properties one to one. Only three differences exist, and the package normalizes all three before hydration:

  • Dates. BigQuery DATETIME columns hold UTC wall-clock values with no zone. The package emits ISO 8601 strings with an explicit Z, which is what the SDK models expect.
  • Primitive arrays. A string[] or number[] is stored as a REPEATED RECORD with a single value sub-field. The package flattens those back to a primitive array. Object arrays are left as arrays of objects.
  • Numbers. INTEGER and NUMERIC values can arrive as wrapper objects or strings, and are normalized to JavaScript Number.

The transform is driven by the BigQuery result schema rather than by runtime type checks, so the same code path handles every table.

What it does not do​

The package exposes raw SQL only. You write the SELECT, pass a model class, and iterate the results. There are no getOrders()-style helpers, no query builder, and no write path.

Because the SDK models and the warehouse schema are generated separately, a schema drift guard ships with the repository and fails when an SDK field no longer has a matching warehouse column. That check runs against a live dataset, so it belongs in the package's own CI rather than in your application.

How access works​

Authentication uses Google Application Default Credentials, so no keys appear in code. The Google account or service account you authenticate as must be registered as an UltraCart user with data warehouse permissions, which is what provisions read access to your warehouse project and sets the taxonomy level you can reach. The account owner grants that access, and the merchant documentation covers the grant, the pricing, and the four data access levels: Data Warehouse (BigQuery).

Customer names, emails, and addresses live only in the taxonomy-gated _medium and _high datasets. Elsewhere those fields are present only as *_hash columns, which have no matching SDK model property and therefore drop during hydration.

The uc-bq Claude Code CLI also reads the same warehouse, but it solves a different problem. It builds and replays reports, charts, and scheduled deliveries for a merchant analyst. This package is a library for pulling records into your own application.

Next​

Was this page helpful?