Query Syntax

ORMBridge's querying interface is a subset of Django's ORM, adapted for JavaScript. This guide covers the query patterns available in ORMBridge, from basic filters to complex logical expressions.

Django ORM in JavaScript: Key Differences

If you're already familiar with Django's ORM, ORMBridge will feel comfortable with a few adaptations for JavaScript:

1. Object-based Parameters: In Django, you pass field conditions as keyword arguments. In ORMBridge, conditions are properties in a single object argument.

   # Django
   User.objects.filter(is_active=True)

   // ORMBridge
   User.objects.filter({ is_active: true })

2. Async/Await for Materialized Results: Methods that materialize results, like fetch(), get(), first(), last(), count(), return Promises and require await. Query-building methods like all(), filter() and exclude() are synchronous. They don't return any data.

   // Building a query (synchronous)
   const query = User.objects.filter({ is_active: true });
   
   // Materializing results (async)
   const users = await query.fetch();

3. Field Names vs Method Names: Method names use JavaScript's camelCase convention (like getOrCreate), but field names retain their original snake_case format from Django.

   // Method name in camelCase, field names in snake_case
   await User.objects.getOrCreate(
     { email: 'user@example.com', is_active: true }
   );

4. Multiple Fetching Patterns: ORMBridge supports explicit fetch() calls and array expansion to gather query results:

   // Explicit fetch (recommended)
   const users = await User.objects.filter({ is_active: true }).fetch();
   
   // Array expansion
   const users = [...await User.objects.filter({ is_active: true })];

5. Pagination Implementation: Since data travels over HTTP, ORMBridge uses limit and offset parameters or the slice() method for pagination.

   // Using fetch options
   const page1 = await User.objects.fetch({ limit: 10, offset: 0 });
   
   // Using slice (alternative syntax)
   const page1 = await User.objects.slice(0, 10).fetch();

Basic Filtering Techniques

Simple Filtering with filter()

The filter() method returns records matching specified conditions:

// Get active users
const activeUsers = await User.objects.filter({ is_active: true }).fetch();

// Get users who joined after a specific date
const newUsers = await User.objects.filter({
  created_at__gte: new Date('2023-01-01')
}).fetch();

Exclusion with exclude()

The exclude() method returns records that don't match the conditions:

// All users except admins
const nonAdminUsers = await User.objects.exclude({ role: 'admin' }).fetch();

// All products that aren't out of stock
const availableProducts = await Product.objects.exclude({ stock: 0 }).fetch();

Chaining Filters

Filter methods can be chained to build complex queries incrementally:

// Get active users who aren't admins and joined recently
const recentActiveNonAdmins = await User.objects
  .filter({ is_active: true })
  .exclude({ role: 'admin' })
  .filter({ created_at__gte: new Date('2023-01-01') })
  .fetch();

Multiple Conditions in a Single Filter

Multiple conditions in a single filter() call are combined with AND logic:

// Users who are both active AND have manager role
const activeManagers = await User.objects.filter({
  is_active: true,
  role: 'manager'
}).fetch();

// Equivalent to:
const sameActiveManagers = await User.objects
  .filter({ is_active: true })
  .filter({ role: 'manager' })
  .fetch();

Field Lookup Operations

ORMBridge supports Django-style field lookups with double underscore syntax:

Lookup	Description	Example
__gt	Greater than	price__gt: 100
__gte	Greater than or equal	age__gte: 18
__lt	Less than	stock__lt: 10
__lte	Less than or equal	price__lte: 99.99
__contains	Contains (case-sensitive)	name__contains: 'Smith'
__icontains	Contains (case-insensitive)	name__icontains: 'smith'
__startswith	Starts with (case-sensitive)	code__startswith: 'PRD'
__istartswith	Starts with (case-insensitive)	email__istartswith: 'admin'
__endswith	Ends with (case-sensitive)	email__endswith: '.org'
__iendswith	Ends with (case-insensitive)	email__iendswith: '.com'
__in	In a list of values	status__in: ['pending', 'processing']
__isnull	Is null (or not null)	phone__isnull: true
__exact	Exact match (default)	username__exact: 'john'
__iexact	Exact match (case-insensitive)	username__iexact: 'john'
__regex	Matches regex (case-sensitive)	code__regex: '^PRD\\d{4}$'
__iregex	Matches regex (case-insensitive)	code__iregex: '^prd\\d{4}$'

Examples of Field Lookups

// Products with price between $10 and $50
const affordableProducts = await Product.objects.filter({
  price__gte: 10,
  price__lte: 50
}).fetch();

// Users with email from certain domains
const corporateUsers = await User.objects.filter({
  email__endswith: '.corp.com'
}).fetch();

// Products with certain tags
const featuredProducts = await Product.objects.filter({
  tag__in: ['featured', 'sale', 'new']
}).fetch();

// Users without a profile picture
const incompleteProfiles = await User.objects.filter({
  profile_picture__isnull: true
}).fetch();

Complex Queries with Q Objects

For queries requiring OR logic or nested conditions, ORMBridge provides Q objects:

import { Q } from '@ormbridge/core';

// Users who are either admins OR have high permission levels
const powerUsers = await User.objects.filter({
  Q: [
    Q('OR',
      { role: 'admin' },
      { permission_level__gte: 8 }
    )
  ]
}).fetch();

Note: Like in Django, Q objects default to AND logic. Specify 'OR' explicitly for OR logic.

Complex Q Object Examples

// Users who are EITHER:
// 1. Both active AND have manager role, OR
// 2. Have admin permissions
const specialUsers = await User.objects.filter({
  Q: [
    Q('OR',
      Q('AND',
        { is_active: true },
        { role: 'manager' }
      ),
      { role: 'admin' }
    )
  ]
}).fetch();

// Complex nested logic
const complexQuery = await User.objects.filter({
  Q: [
    Q('OR',
      Q('AND',
        { is_active: true },
        Q('OR',
          { role: 'manager' },
          { permission_level__gte: 7 }
        )
      ),
      Q('AND',
        { is_verified: true },
        { created_at__gte: new Date('2023-01-01') }
      )
    )
  ]
}).fetch();

This translates to:

(is_active AND (role='manager' OR permission_level >= 7))
OR
(is_verified AND created_at >= '2023-01-01')

Combining Q Objects with Regular Filters

Regular field conditions can be combined with Q objects:

// Users who:
// - Are active (regular filter, combined with AND)
// - AND match either of these conditions:
//   - Role is 'admin'
//   - Department is 'Engineering' AND permission_level >= 5
const targetedUsers = await User.objects.filter({
  is_active: true,  // AND condition with everything else
  Q: [
    Q('OR',
      { role: 'admin' },
      Q('AND',
        { department: 'Engineering' },
        { permission_level__gte: 5 }
      )
    )
  ]
}).fetch();

Filtering Across Relationships

ORMBridge allows traversing relationships with double underscore notation:

Single-level Relationships

// Orders placed by users in the USA
const domesticOrders = await Order.objects.filter({
  'user__country': 'USA'
}).fetch();

// Users who have placed orders with a specific status
const usersWithPendingOrders = await User.objects.filter({
  'orders__status': 'pending'
}).fetch();

Multi-level Relationships

You can traverse multiple relationships:

// Orders where the user belongs to the Sales department
const departmentOrders = await Order.objects.filter({
  'user__department__name': 'Sales'
}).fetch();

// Products ordered by users in New York
const locallyPopularProducts = await Product.objects.filter({
  'order_items__order__user__address__city': 'New York'
}).distinct().fetch();

Performance Considerations

When traversing relationships, keep in mind:

1. Each relationship level generates additional database queries
2. Be mindful of the number of relationships you traverse
3. Since data travels over HTTP, keep queries focused and paginated

Model Summary Representation

When fetching related models without a depth parameter, ORMBridge returns a summary representation:

// Fetching a user without depth parameter
const post = await Post.objects.get({ id: 123 });

// The author field is a summary
console.log(post.author); // { id: 456, repr: "John Smith", img: "/media/profile/john.jpg" }

// Get the full author model when needed
const fullAuthor = await post.author.toFullModel();

Customizing Summary Representation

You can customize how models appear in summaries by implementing special methods in your Django models:

# In your Django model
class User(models.Model):
    name = models.CharField(max_length=100)
    profile_pic = models.ImageField(upload_to='profiles/', null=True)
    
    def __repr__(self):
        """Customize the string representation for ORMBridge summaries"""
        return f"{self.name}"
    
    def __img__(self):
        """Customize the image URL for ORMBridge summaries"""
        return self.profile_pic.url if self.profile_pic else None

Serializer Options and Pagination

ORMBridge offers options to control what data is returned:

export interface SerializerOptions<T> {
  // Control related model expansion (default: 0)
  depth?: number;
  
  // Select specific fields to include
  fields?: Array<keyof T | string>;
  
  // Pagination
  limit?: number;
  offset?: number;
}

Pagination

Since ORMBridge operates over HTTP, pagination is crucial:

// Get first page of 10 users
const firstPage = await User.objects.orderBy('name').fetch({
  limit: 10,
  offset: 0
});

// Get second page of 10 users
const secondPage = await User.objects.orderBy('name').fetch({
  limit: 10,
  offset: 10
});

// Alternative slice syntax
const firstTenUsers = await User.objects.orderBy('name').slice(0, 10).fetch();

Common Pagination Implementation

async function getPage(pageNumber, pageSize = 10) {
  const offset = (pageNumber - 1) * pageSize;
  
  // Fetch the current page of data
  const data = await User.objects
    .orderBy('created_at')
    .fetch({
      limit: pageSize,
      offset: offset
    });
  
  // Get total count for page controls
  const totalCount = await User.objects.count();
  const totalPages = Math.ceil(totalCount / pageSize);
  
  return {
    data,
    pagination: {
      currentPage: pageNumber,
      totalPages,
      totalCount,
      pageSize
    }
  };
}

Controlling Depth

The depth parameter controls how deeply related models are expanded:

// Depth 0: Related models are returned as summaries (default)
const orderBasic = await Order.objects.get({ id: 123 });
// order.user is a ModelSummary

// Depth 1: Direct relations are expanded
const orderWithRelations = await Order.objects.get(
  { id: 123 },
  { depth: 1 }
);
// order.user is fully expanded, but order.user.department is a summary

// Depth 2: Relations of relations are expanded
const orderFullyExpanded = await Order.objects.get(
  { id: 123 },
  { depth: 2 }
);
// Both order.user and order.user.department are fully expanded

Field Selection

The fields parameter allows selecting specific fields:

// Only get name and email fields
const userContacts = await User.objects.fetch({
  fields: ['id', 'name', 'email']
});

// Fields can include related models with depth
const detailedProfiles = await User.objects.fetch({
  fields: ['id', 'name', 'profile'],
  depth: 1
});

getOrCreate and updateOrCreate

ORMBridge provides methods to atomically create or retrieve objects:

Using getOrCreate

// Try to get a user with this email, or create one if it doesn't exist
const [user, created] = await User.objects.getOrCreate(
  { email: 'user@example.com' },
  { defaults: { name: 'New User', is_active: true } }
);

if (created) {
  console.log('Created a new user');
} else {
  console.log('Found existing user');
}

Using updateOrCreate

// Find or create a product, updating stock if it exists
const [product, created] = await Product.objects.updateOrCreate(
  { sku: 'ABC123' },
  { defaults: { name: 'Widget', price: 19.99, stock: 100 } }
);

Destructuring Options

ORMBridge supports both array destructuring (Django-style) and object destructuring (JavaScript-style):

// Array destructuring (Django-style)
const [user, created] = await User.objects.getOrCreate(
  { email: 'user@example.com' }
);

// Object destructuring (JavaScript-style)
const { instance, created } = await User.objects.getOrCreate(
  { email: 'user@example.com' }
);

Advanced Pattern: Building Dynamic Queries

For real-world applications, you often need to build queries dynamically:

function buildProductQuery(filters) {
  let query = Product.objects;
  
  // Add conditions based on provided filters
  if (filters.category) {
    query = query.filter({ category: filters.category });
  }
  
  if (filters.minPrice !== undefined) {
    query = query.filter({ price__gte: filters.minPrice });
  }
  
  if (filters.maxPrice !== undefined) {
    query = query.filter({ price__lte: filters.maxPrice });
  }
  
  if (filters.inStock) {
    query = query.filter({ stock__gt: 0 });
  }
  
  // Add search term if provided
  if (filters.search) {
    query = query.filter({
      Q: [
        Q('OR',
          { name__icontains: filters.search },
          { description__icontains: filters.search },
          { sku: filters.search }
        )
      ]
    });
  }
  
  // Add sorting
  if (filters.sortBy) {
    const direction = filters.sortDesc ? '-' : '';
    query = query.orderBy(`${direction}${filters.sortBy}`);
  }
  
  return query;
}

// Usage with pagination
async function searchProducts(userFilters) {
  const query = buildProductQuery(userFilters);
  
  // Apply pagination
  return await query.fetch({
    limit: userFilters.pageSize || 10,
    offset: ((userFilters.page || 1) - 1) * (userFilters.pageSize || 10)
  });
}

Performance Best Practices

Keep these performance considerations in mind:

1. Be specific with filters: More specific queries return smaller result sets
2. Use field selection: Only request needed fields with fields: [...]
3. Consider depth carefully: Higher depth values cause more database queries
4. Always paginate results: Pagination is essential for network performance
5. Use summaries effectively: Use model summaries for lists and only fetch full models when necessary
6. Watch query complexity: Deep relationship traversal affects performance
7. Watch query count: Multiple chained queries execute separately on the server

Common Query Examples

Date Range Filtering

const startDate = new Date('2023-01-01');
const endDate = new Date('2023-01-31');

const januaryOrders = await Order.objects.filter({
  created_at__gte: startDate,
  created_at__lte: endDate
}).fetch();

Text Search Across Multiple Fields

const searchTerm = 'wireless headphones';

const searchResults = await Product.objects.filter({
  Q: [
    Q('OR',
      { name__icontains: searchTerm },
      { description__icontains: searchTerm },
      { sku: searchTerm }
    )
  ]
}).fetch();

Finding Records with Specific Related Records

// Find users who have placed at least one order over $100
const bigSpenders = await User.objects.filter({
  'orders__total__gt': 100
}).distinct().fetch();

Filtering with Negated Conditions

// Find posts that don't have any comments
const uncommentedPosts = await Post.objects.filter({
  'comments__isnull': true
}).fetch();

Conclusion

ORMBridge's query system provides a powerful way to interact with your Django backend from JavaScript. It closely mirrors Django's ORM while adapting to JavaScript conventions, offering a familiar experience for Django developers while providing clean TypeScript interfaces for frontend developers.

Remember that these operations map to database queries that are transmitted over HTTP, so proper pagination and judicious use of fields and depth parameters is essential for performance.