BigQuery ORM

A Mongoose-like ORM for Google BigQuery, providing a familiar interface for Node.js developers to interact with BigQuery.

Features

• Schema Definition: Define your data structure with a familiar Mongoose-like schema syntax
• Model Operations: Create, read, update, and delete operations on BigQuery tables
• Query Builder: Intuitive query building with chainable methods
• Schema Versioning: Support for schema evolution and migrations
• Discriminators: Inheritance and polymorphic queries
• Middleware: Pre and post hooks for model operations
• Plugins: Extend functionality with plugins

Installation

npm install bigquery-orm

Quick Start

import { Schema, model, connect } from 'bigquery-orm';

// Connect to BigQuery
const connection = await connect({
  projectId: 'your-project-id',
  keyFilename: 'path/to/keyfile.json'
});

// Define a schema
interface IUser {
  name: string;
  email: string;
  age?: number;
  isActive: boolean;
  createdAt: Date;
}

const userSchema = new Schema<IUser>({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  age: { type: Number },
  isActive: { type: Boolean, default: true },
  createdAt: { type: Date, default: Date.now }
});

// Create a model
const User = model<IUser>('User', userSchema);

// Create a document
const user = await User.create({
  name: 'John Doe',
  email: '[email protected]',
  age: 30
});

// Query documents
const users = await User.find({ isActive: true })
  .sort({ createdAt: -1 })
  .limit(10);

// Update documents
await User.updateMany(
  { age: { $lt: 18 } },
  { isActive: false }
);

// Delete documents
await User.deleteOne({ email: '[email protected]' });

Schema Versioning

The ORM supports schema versioning to handle schema evolution:

import { Schema, model, SchemaVersioning, SchemaVersion } from 'bigquery-orm';

// Define the current schema
const userSchema = new Schema({
  name: { type: String, required: true },
  email: { type: String, required: true },
  age: { type: Number },
  isActive: { type: Boolean, default: true }
});

// Create versioning
const versioning = new SchemaVersioning(userSchema);

// Define previous schema versions
const v1Schema = new Schema({
  name: { type: String, required: true },
  email: { type: String, required: true }
});

// Add version with migration function
versioning.addVersion({
  version: 1,
  schema: v1Schema,
  migrate: (doc) => {
    // Add missing fields for v1 documents
    return {
      ...doc,
      age: null,
      isActive: true
    };
  }
});

// Documents will be automatically migrated when retrieved

Discriminators

The ORM supports discriminators for schema inheritance:

import { Schema, model } from 'bigquery-orm';

// Base schema
const eventSchema = new Schema({
  name: { type: String, required: true },
  date: { type: Date, default: Date.now }
});

// Create base model
const Event = model('Event', eventSchema);

// Create discriminator for ClickEvent
const clickSchema = new Schema({
  element: { type: String, required: true },
  position: {
    x: { type: Number, required: true },
    y: { type: Number, required: true }
  }
});

const ClickEvent = Event.discriminator('ClickEvent', clickSchema);

// Create discriminator for PageViewEvent
const pageViewSchema = new Schema({
  url: { type: String, required: true },
  referrer: { type: String }
});

const PageViewEvent = Event.discriminator('PageViewEvent', pageViewSchema);

// You can query all events or specific types
const allEvents = await Event.find();
const clickEvents = await ClickEvent.find();

License

This project is licensed under the MIT License - see the LICENSE file for details.