Skip to main content
How-to

BigQuery SDK Quickstart

Install the package, authenticate, and stream your first hydrated Order objects out of the data warehouse.

Before you start​

  • Node.js 22 or newer. The package follows @google-cloud/bigquery v9, which sets the same floor. If you are still on Node 18 or 20, both of which are past end of life, pin @ultracart/bigquery-sdk@0.1.x, which tracks @google-cloud/bigquery v8.
  • Data warehouse access. Your Google account or service account has to be registered as an UltraCart user with data warehouse permissions before any query will run. The account owner grants that under Configuration → Account & Users → Users, and provisioning takes about five minutes. See Data Warehouse (BigQuery) for the grant and the four access levels.
  • Your merchant ID. The warehouse project is derived from it as ultracart-dw-{merchantid}, lowercased.

Install​

npm install @ultracart/bigquery-sdk ultra_cart_rest_api_v2 @google-cloud/bigquery

ultra_cart_rest_api_v2 is an optional peer dependency. Install it when you want hydrated model instances; without it the package still returns plain SDK-shaped objects.

Authenticate​

Authentication uses Google Application Default Credentials, so nothing goes in code:

# Developer machine
gcloud auth application-default login

# Server or CI
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json   # <- your key file

For a server, create a service account in your own Google project, then add its email as an UltraCart user with the data warehouse permissions that job needs. UltraCart provisions read access at the taxonomy level you grant.

Run a query​

query() returns an async iterator. Rows are fetched a page at a time, so a small incremental sync and a full-history backfill run through the same constant-memory path.

const { UltraCartBigQuery } = require('@ultracart/bigquery-sdk');
const UltraCartApi = require('ultra_cart_rest_api_v2');

// Project is derived as ultracart-dw-demo
const ucbq = new UltraCartBigQuery({ merchantId: 'DEMO' });   // <- your merchant ID

const sql = `SELECT * FROM ultracart_dw.uc_orders
             WHERE creation_dts >= @since
             ORDER BY creation_dts`;

for await (const order of ucbq.query(sql, {
  params: { since: '2025-01-01' },
  model: UltraCartApi.Order,
})) {
  // order is a real UltraCartApi.Order instance:
  //   order.creation_dts      -> "2025-01-15T10:30:00Z"
  //   order.items[0]          -> OrderItem instance
  console.log(order.order_id, order.summary.total.value);
}

Omit model to stream plain SDK-shaped objects instead of hydrated instances.

Two things decide which dataset name belongs in that FROM clause: whether the account is a parent of linked accounts, and whether you need customer names and emails. Extracting order history covers both.

Estimate the cost first​

BigQuery bills by bytes scanned, and LIMIT does not reduce that number. Check any query you have not run before:

const est = await ucbq.dryRun(sql, { params: { since: '2025-01-01' } });
console.log(`${est.gigabytesProcessed.toFixed(2)} GB (~$${est.estimatedCostUsd.toFixed(2)})`);

Every query() is capped at 10 GB billed by default, so a runaway SELECT * aborts rather than running up a bill. Override the ceiling per client or per call with maxBytesBilled, or pass 0 to remove it. The API reference lists the defaults and the full option set.

warning

Query cost is billed to your UltraCart data warehouse project and appears on your UltraCart bill. Raising or disabling maxBytesBilled removes the only guard against a single expensive query. See pricing.

Next​

Was this page helpful?