Package Exports

rabbit-bq-job-optimizer
rabbit-bq-job-optimizer/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rabbit-bq-job-optimizer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Rabbit BigQuery Job Optimizer TypeScript Client

This is the official TypeScript client library for the Rabbit BigQuery Job Optimizer API. It helps optimize BigQuery job configurations to reduce costs and improve performance.

Installation

npm install @followrabbit/bq-job-optimizer

Usage

Basic Usage

import { RabbitBQJobOptimizer, OptimizationConfig } from '@followrabbit/bq-job-optimizer';

// Initialize the client
const client = new RabbitBQJobOptimizer({
  apiKey: 'your-api-key'
  // baseUrl is optional - will use production endpoint by default
});

// Optimize a BigQuery job configuration
const jobConfig = {
  configuration: {
    query: {
      query: 'SELECT * FROM my_table',
      useLegacySql: false,
      priority: 'INTERACTIVE'
    }
  }
};

const optimizationConfig: OptimizationConfig = {
  type: 'reservation_assignment',
  config: {
    defaultPricingMode: 'on_demand',
    reservationIds: [
      'my-project:US.my-reservation-us',
      'my-project:EU.my-reservation-eu'
    ]
  }
};

// Optimize the job
const result = await client.optimizeJob(jobConfig, [optimizationConfig]);

// Access the optimized configuration
const optimizedConfig = result.optimizedJob;

// Access optimization results
for (const optimization of result.optimizationResults) {
  console.log(`Type: ${optimization.type}`);
  console.log(`Applied: ${optimization.performed}`);
  console.log(`Estimated Savings: ${optimization.estimatedSavings}`);
}

Error Handling

The client provides specific error types for different failure scenarios:

import { 
  RabbitBQJobOptimizerError,
  MissingApiKeyError,
  ApiRequestError
} from '@followrabbit/bq-job-optimizer';

try {
  const result = await client.optimizeJob(jobConfig, [optimizationConfig]);
} catch (error) {
  if (error instanceof MissingApiKeyError) {
    console.error('API key is missing');
  } else if (error instanceof ApiRequestError) {
    console.error(`API request failed: ${error.message}`);
    console.error(`Status code: ${error.statusCode}`);
  } else if (error instanceof RabbitBQJobOptimizerError) {
    console.error(`Optimizer error: ${error.message}`);
  }
}

Authentication

The API key is required to use the client. It can be obtained from the Rabbit team by contacting success@followrabbit.ai.

There are three ways to configure authentication:

1. Pass API key directly to the constructor

import { RabbitBQJobOptimizer } from '@followrabbit/bq-job-optimizer';

const client = new RabbitBQJobOptimizer({
  apiKey: 'your-api-key'
});

2. Pass both API key and custom base URL

const client = new RabbitBQJobOptimizer({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-custom-endpoint.com'
});

3. Use environment variables

Set the environment variables:

export RABBIT_API_KEY="your-api-key"
export RABBIT_API_BASE_URL="your-base-url"  # Optional - will use default if not set

Then initialize the client without parameters:

const client = new RabbitBQJobOptimizer(); // Will automatically use environment variables

API Reference

Classes

`RabbitBQJobOptimizer`

Main client class for interacting with the Rabbit BigQuery Job Optimizer API.

Constructor:

constructor(config?: RabbitBQJobOptimizerConfig)

Methods:

optimizeJob(configuration, enabledOptimizations): Promise<OptimizationResponse>
getApiKey(): string - Returns masked API key for debugging
getBaseUrl(): string - Returns the current base URL

Types

`OptimizationConfig`

Configuration for BigQuery job optimization.

interface OptimizationConfig {
  type: string;
  defaultPricingMode?: string;
  config?: Record<string, unknown>;
}

`OptimizationResult`

Result of a specific optimization.

interface OptimizationResult {
  type: string;
  performed: boolean;
  estimatedSavings: number;
  context: Record<string, unknown>;
}

`OptimizationResponse`

Response from the optimization API.

interface OptimizationResponse {
  optimizedJob: Record<string, unknown>;
  optimizationResults: OptimizationResult[];
  estimatedSavings: number;
  optimizationPerformed: boolean;
}

Error Classes

RabbitBQJobOptimizerError - Base error class
MissingApiKeyError - Thrown when API key is not provided
ApiRequestError - Thrown when API request fails
ResponseParseError - Thrown when response parsing fails

Examples

See the examples/ directory for complete usage examples:

basic-usage.ts - Basic optimization example
error-handling.ts - Error handling patterns
environment-variables.ts - Using environment variables

Development

To build the library:

npm run build

To run tests:

npm test

To run linting:

npm run lint

License

Apache License 2.0

Support

For support, please contact success@followrabbit.ai or visit our GitHub repository.