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 [email protected].

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 [email protected] or visit our GitHub repository.