BigQuery Client

import { BigqueryWarehouseClient } from '@lightdash/warehouses';
import { type CreateBigqueryCredentials } from '@lightdash/common';

const client = new BigqueryWarehouseClient({
  type: 'bigquery',
  project: 'my-project-id',
  dataset: 'my_dataset',
  location: 'US',
  keyfileContents: {
    type: 'service_account',
    project_id: 'my-project-id',
    private_key: '-----BEGIN PRIVATE KEY-----\n...',
    client_email: 'service@project.iam.gserviceaccount.com',
  },
  timeoutSeconds: 300,
  priority: 'interactive',
  maximumBytesBilled: 1000000000,
  retries: 3,
});

await client.test();

// Note: BigQuery requires the callback parameter (streams results immediately)
// Returns: Promise<WarehouseExecuteAsyncQuery>
const result = await client.executeAsyncQuery(
  {
    sql: 'SELECT * FROM `my-dataset.large-table` WHERE date >= @date',
    tags: { source: 'app' },          // Required
    timezone: 'America/New_York',     // Optional
    queryParams: { date: '2023-01-01' }, // Named parameters
  },
  (rows, fields) => {
    // Callback invoked as results stream from BigQuery job
    console.log(`Received ${rows.length} rows`);
  }
);

// Result contains job metadata
console.log('Job ID:', result.queryId);           // string (BigQuery job ID)
console.log('Total rows:', result.totalRows);     // number
console.log('Duration:', result.durationMs);      // number
console.log('Location:', result.queryMetadata.jobLocation); // 'US', 'EU', etc.

await client.streamQuery(
  'SELECT * FROM `dataset.table` WHERE status = @status',
  (data) => { /* process rows */ },
  { queryParams: { status: 'active' }, tags: {} }
);

const tables = await client.getAllTables();
tables.forEach(t => {
  if (t.partitionColumn) {
    console.log(`${t.table}: partitioned by ${t.partitionColumn.field}`);
  }
});

import { BigquerySqlBuilder } from '@lightdash/warehouses';

const builder = new BigquerySqlBuilder();
builder.getFieldQuoteChar(); // '`'
builder.getFloatingType(); // 'FLOAT64'
builder.escapeString("O'Reilly"); // "O\'Reilly"

import { MetricType } from '@lightdash/common';

// Median (50th percentile)
const medianSql = builder.getMetricSql('revenue', {
  type: MetricType.MEDIAN,
  sql: 'revenue'
});
// Returns: "APPROX_QUANTILES(revenue, 100)[OFFSET(50)]"

// 95th percentile
const p95Sql = builder.getMetricSql('latency', {
  type: MetricType.PERCENTILE,
  sql: 'latency',
  percentile: 95
});
// Returns: "APPROX_QUANTILES(latency, 100)[OFFSET(95)]"

try {
  await client.streamQuery(sql, callback, { tags: {} });
} catch (error) {
  const parsed = client.parseError(error);
  console.error(parsed.message); // Enhanced message with line numbers and guidance
}

/**
 * Sanitize labels to meet BigQuery requirements
 * - Converts to lowercase
 * - Truncates keys/values to 60 characters
 * - Removes invalid characters (only alphanumeric, underscore, hyphen allowed)
 * @param labels - Raw label key-value pairs
 * @returns Sanitized labels or undefined if input is undefined
 */
static sanitizeLabelsWithValues(
  labels?: Record<string, string>
): Record<string, string> | undefined;

// Usage
const labels = BigqueryWarehouseClient.sanitizeLabelsWithValues({
  'User-ID': '123',
  'UPPERCASE': 'value',
  'Very-Long-Label-Name-That-Exceeds-Maximum-Length-Of-60-Characters': 'val'
});
// Result: { 'user-id': '123', 'uppercase': 'value', 'very-long-label-name-that-exceeds-maximum-length-of-60-cha': 'val' }

/**
 * Get available datasets (schemas) using OAuth refresh token
 * Creates temporary BigQuery client using OAuth for authentication
 * Useful for UI dataset selection without service account
 * @param projectId - GCP project ID
 * @param refresh_token - OAuth refresh token from Google OAuth flow
 * @returns Promise resolving to array of dataset metadata
 */
static getDatabases(
  projectId: string,
  refresh_token: string
): Promise<Array<{ projectId: string; datasetId: string; location?: string }>>;

// Usage
const datasets = await BigqueryWarehouseClient.getDatabases(
  'my-project-id',
  'oauth-refresh-token'
);
datasets.forEach(ds => {
  console.log(`${ds.projectId}.${ds.datasetId} (${ds.location})`);
});

/**
 * Extract field type information from BigQuery query response
 * Maps BigQuery types to Lightdash DimensionType
 * @param response - BigQuery QueryRowsResponse[2] with schema metadata
 * @returns Field metadata mapping column names to types
 */
static getFieldsFromResponse(
  response: QueryRowsResponse[2] | undefined
): Record<string, { type: DimensionType }>;

// Usage
const [rows, , metadata] = await dataset.query({ query: sql });
const fields = BigqueryWarehouseClient.getFieldsFromResponse(metadata);
console.log(fields);
// { user_id: { type: 'number' }, created_at: { type: 'timestamp' } }

/**
 * Map BigQuery field type to Lightdash DimensionType
 * @param fieldType - BigQuery field type string (e.g., 'STRING', 'INT64', 'TIMESTAMP')
 * @returns DimensionType enum value
 */
static mapFieldType(fieldType: string): DimensionType;

// Usage
const dimType = BigqueryWarehouseClient.mapFieldType('INT64');
// Returns: DimensionType.NUMBER

/**
 * Type guard to check if error is a BigQuery error with error details
 * @param error - Error object to check
 * @returns True if error contains BigQuery error details (IErrorProto)
 */
static isBigqueryError(error: unknown): error is BigqueryError;

// Usage
try {
  await client.streamQuery(sql, callback, { tags: {} });
} catch (error) {
  if (BigqueryWarehouseClient.isBigqueryError(error)) {
    console.error('BigQuery error code:', error.errors[0].reason);
    console.error('Error message:', error.errors[0].message);
  }
}

interface BigqueryError {
  errors: Array<{
    reason: string;     // Error code (e.g., 'accessDenied', 'invalidQuery')
    message: string;    // Error message with details
    location?: string;  // Query location if syntax error
  }>;
}

keyfileContents: {
  type: 'service_account',
  project_id: 'my-project-id',
  private_key: '-----BEGIN PRIVATE KEY-----\n...',
  client_email: 'service@project.iam.gserviceaccount.com',
  // ... other service account fields
}

import { BigqueryFieldType } from '@lightdash/warehouses';

enum BigqueryFieldType {
  STRING, INTEGER, INT64, BYTES, FLOAT, FLOAT64,
  BOOLEAN, BOOL, TIMESTAMP, DATE, TIME, DATETIME,
  GEOGRAPHY, NUMERIC, BIGNUMERIC, RECORD, STRUCT, ARRAY,
}