BigQuery SDK Reference

The complete surface of @ultracart/bigquery-sdk. For the concepts behind it, see BigQuery Data Warehouse SDK; for a first working query, see the quickstart.

Exports

const {
  UltraCartBigQuery,
  DEFAULT_MAX_BYTES_BILLED,   // 10737418240 (10 GB)
  DEFAULT_PAGE_SIZE,          // 50000
  resolveDataset,
  projectIdForMerchant,
  DATASET_STANDARD,           // 'ultracart_dw'
  DATASET_MEDIUM,             // 'ultracart_dw_medium'
  DATASET_HIGH,               // 'ultracart_dw_high'
  DATASET_STREAMING,          // 'ultracart_dw_streaming'
  transformRows,
  toBigQueryDatetime,
} = require('@ultracart/bigquery-sdk');

The linked dataset names have no exported constants at the package root. resolveDataset() produces them.

new UltraCartBigQuery(options)

Either merchantId or projectId is required. Passing neither throws Provide either a merchantId or an explicit projectId.

Option	Type	Default	Description
merchantId	string	none	Merchant ID. The project is derived as ultracart-dw-{merchantid}, lowercased.
projectId	string	derived	Explicit project ID. Overrides the merchantId derivation.
bigquery	BigQuery	ADC client	An injected @google-cloud/bigquery client, for testing or custom auth. A client using Application Default Credentials is created when this is omitted.
maxBytesBilled	number	10737418240	Default per-query ceiling on bytes billed. 0 or null disables the cap.
pageSize	number	50000	Rows fetched per page while streaming. Bounds memory, since one page is held at a time.

The page size default balances throughput against per-page memory for wide rows. Streaming is round-trip bound, so larger pages mean fewer HTTP fetches.

query(sql, opts)

Runs a SQL query and returns an AsyncGenerator that yields one object per result row. Iterated with for await. Rows are fetched a page at a time, so memory stays bounded no matter how large the result set is.

Option	Type	Default	Description
params	object	none	Named query parameters, referenced as @name in the SQL.
model	class	none	An UltraCart SDK model class, such as UltraCartApi.Order. Each row is hydrated through its static constructFromObject. Omitted, rows are yielded as plain SDK-shaped objects.
maxBytesBilled	number	client value	Per-query override of the byte ceiling. 0 or null disables it for this call.
pageSize	number	client value	Per-query override of the page size.

A query that would exceed maxBytesBilled fails rather than running, and the error comes from BigQuery rather than from this package.

dryRun(sql, opts)

Estimates what a query would scan without running it, using a BigQuery dry run. Accepts params, and resolves to:

Field	Type	Description
totalBytesProcessed	number	Bytes BigQuery reports it would scan.
gigabytesProcessed	number	The same figure in GiB.
estimatedCostUsd	number	An estimate, computed at a fixed on-demand rate of 6.25 USD per TiB scanned.

estimatedCostUsd is an approximation for guarding a large extract, not a quote. Actual billing follows Google's current pricing and your project's terms. See pricing.

Because LIMIT does not reduce bytes scanned, a dry run is the only reliable way to size a query before running it.

hydrate(rows, schemaFields, model) and hydrateRow(row, schemaFields, model)

Transform rows already in hand, for callers running their own BigQuery job. hydrateRow handles one row and hydrate maps an array. Both take the result schema's fields array and an optional model class, and both return the same objects query() would yield. query() remains the streaming path.

Helpers

Function	Returns	Description
projectIdForMerchant(merchantId)	string	'DEMO' resolves to 'ultracart-dw-demo'. Throws when the merchant ID is missing or not a string.
resolveDataset({ linked, taxonomy })	string	Dataset name for a combination of linked and PII tier. { linked: true, taxonomy: 'high' } resolves to 'ultracart_dw_linked_high'.
toBigQueryDatetime(value)	string	Strips the trailing Z from an ISO string so it can be compared against a DATETIME column, normalizing a non-UTC offset to UTC first. The inverse of what the transform emits on read.
transformRows(rows, schemaFields)	array	The low-level schema-driven transform, without model hydration.

Dataset selection

Goal	Dataset	Filter
A single standard account	ultracart_dw	merchant_id = 'ACME'
A parent account, all children	ultracart_dw_linked	merchant_id optional
One child of a parent	ultracart_dw_linked	merchant_id = 'ACME'
Customer names and emails	ultracart_dw_medium or _high, ultracart_dw_linked_medium or _linked_high	as above
Change data capture	ultracart_dw_streaming.uc_*_streaming	RecordTime > @since

Which tiers you can reach depends on the data warehouse permissions granted to your user. The access levels and what each one exposes are documented under Data Warehouse (BigQuery).

The _linked tables are views, so their numRows and partitioning metadata read as empty. The data is still there.

Type mapping

BigQuery	SDK model property	Note
DATETIME	ISO 8601 string with Z	Stored as UTC wall-clock with no zone.
TIMESTAMP	ISO 8601 string with Z	Normalized to a canonical Z form.
DATE, TIME	string, unchanged	YYYY-MM-DD and HH:MM:SS.
INTEGER, NUMERIC	Number	Wrapper objects and strings are normalized.
REPEATED RECORD with a single value sub-field	primitive array	How the warehouse stores string[] and number[].
REPEATED RECORD with several sub-fields	array of objects	Left as is. Nested models hydrate normally.
*_hash columns	dropped	No matching SDK property, so hydration discards them.

The transform reads the BigQuery result schema rather than checking runtime types, so it behaves the same for every table.

Requirements

Node.js 22 or newer, matching the floor set by @google-cloud/bigquery v9. @ultracart/bigquery-sdk@0.1.x tracks @google-cloud/bigquery v8 for older runtimes. ultra_cart_rest_api_v2 is an optional peer dependency, needed only for model hydration.