Search Functionality

ORMBridge provides a flexible and extensible search system that allows you to perform full-text searches across your models. The search functionality is designed to be adaptable to different database backends, with built-in support for both simple ILIKE-based searches and advanced PostgreSQL full-text search.

Basic Usage

Client-Side

In your TypeScript code, you can use the search method on a model's objects:

// Search for posts containing "django" or "python" in searchable fields
const searchResults = await Post.objects
  .search("django python")
  .fetch();

// Search with field restriction
const titleSearchResults = await Post.objects
  .search("django python", ["title"])
  .fetch();

// Combine with other filters
const searchWithFilters = await Post.objects
  .filter({ is_published: true })
  .search("django python")
  .orderBy("-created_at")
  .fetch();

Django Configuration

To make fields searchable, specify them when registering your model with ORMBridge:

# blog/crud.py
registry.register(
    model=Post,
    searchable_fields={"title", "content", "tags"},  # Fields to include in search
    # ... other registration options
)

You can use the special ALL_FIELDS constant to make all model fields searchable:

from ormbridge.core.constants import ALL_FIELDS

registry.register(
    model=Post,
    searchable_fields=ALL_FIELDS,  # All fields will be searched
    # ... other registration options
)

Search Providers

ORMBridge's search functionality is implemented through search providers, which are pluggable components that handle the actual search logic. This allows you to switch between different search implementations depending on your database and performance requirements.

Built-In Search Providers

BasicSearchProvider (Default)

The default search provider uses simple ILIKE queries to perform searches. It's compatible with all database backends but generally should not be used in production.

# This is the default - no need to explicitly configure it
from ormbridge.adaptors.django.search_providers.basic_search import BasicSearchProvider
from ormbridge.adaptors.django.config import config

config.search_provider = BasicSearchProvider()

PostgreSQLSearchProvider

For PostgreSQL databases, ORMBridge includes a specialized search provider that leverages PostgreSQL's powerful full-text search capabilities. This provider is recommended for production environments with PostgreSQL.

Important: The PostgreSQL search provider uses PostgreSQL's built-in full-text search capabilities. PostgreSQL's tsvector type (which Django's SearchVectorField uses) is part of the core database functionality - it's not related to the pgvector extension (which is for vector similarity search and embeddings).

For optimal performance with the precomputed search vector approach, simply ensure your database user has permissions to create and update tsvector columns.

Once the required extensions are enabled, you can configure ORMBridge to use the PostgreSQL search provider:

# In your Django settings or app configuration
from ormbridge.adaptors.django.search_providers.postgres_search import PostgreSQLSearchProvider
from ormbridge.adaptors.django.config import config

config.search_provider = PostgreSQLSearchProvider()

Search Performance Optimization

When using PostgreSQL in production, you can dramatically improve search performance by adding a dedicated search vector column to your models.

1. Add a search vector field to your models

from django.contrib.postgres.search import SearchVectorField

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    # ... other fields
    
    # Add a search vector field
    pg_search_vector = SearchVectorField(null=True)

2. Create a migration to add the search vector

from django.contrib.postgres.search import SearchVector
from django.db import migrations

def update_search_vectors(apps, schema_editor):
    Post = apps.get_model('blog', 'Post')
    # Update all existing records
    Post.objects.all().update(
        pg_search_vector=SearchVector('title', 'content')
    )

class Migration(migrations.Migration):
    dependencies = [
        ('blog', 'previous_migration'),
    ]

    operations = [
        migrations.RunPython(update_search_vectors, migrations.RunPython.noop),
    ]

3. Keep the search vector updated

Set up triggers to update the search vector automatically when records change, or update it in your save method:

from django.contrib.postgres.search import SearchVector

class Post(models.Model):
    # ... fields as before
    
    def save(self, *args, **kwargs):
        super().save(*args, **kwargs)
        # Update the search vector after saving
        # Note: This is inefficient for bulk operations
        type(self).objects.filter(pk=self.pk).update(
            pg_search_vector=SearchVector('title', 'content')
        )

For bulk operations, update the search vector after the bulk operation completes:

# After bulk update
Post.objects.filter(updated=True).update(
    pg_search_vector=SearchVector('title', 'content')
)

Creating Custom Search Providers

You can create custom search providers to implement specialized search logic for your specific needs or to integrate with external search engines like Elasticsearch.

Custom Search Provider Example

from typing import Set
from django.db.models import QuerySet
from ormbridge.core.interfaces import AbstractSearchProvider

class ElasticSearchProvider(AbstractSearchProvider):
    """
    Example search provider that uses Elasticsearch.
    """
    
    def __init__(self, elastic_client, index_prefix="django_"):
        self.client = elastic_client
        self.index_prefix = index_prefix
    
    def search(self, queryset: QuerySet, query: str, search_fields: Set[str]) -> QuerySet:
        """
        Apply search using Elasticsearch.
        """
        if not query or not search_fields:
            return queryset
            
        # Get model name for index
        model_name = queryset.model.__name__.lower()
        index_name = f"{self.index_prefix}{model_name}"
        
        # Perform search in Elasticsearch
        search_results = self.client.search(
            index=index_name,
            body={
                "query": {
                    "multi_match": {
                        "query": query,
                        "fields": list(search_fields)
                    }
                }
            }
        )
        
        # Extract IDs from search results
        ids = [hit["_id"] for hit in search_results["hits"]["hits"]]
        
        # Filter queryset by IDs
        return queryset.filter(pk__in=ids)

Registering a Custom Search Provider

# In your Django app configuration or settings
from myapp.search import ElasticSearchProvider
from elasticsearch import Elasticsearch
from ormbridge.adaptors.django.config import config

# Initialize your search provider
elastic_client = Elasticsearch([{'host': 'localhost', 'port': 9200}])
config.search_provider = ElasticSearchProvider(elastic_client)

Advanced Usage

Combining Search with Q Objects

You can use Q objects to create more complex search operations:

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

// Search in specific fields OR apply a filter
const results = await Post.objects.filter({
  Q: [
    Q('OR',
      { title__icontains: 'django' },
      { is_featured: true }
    )
  ],
  is_published: true
}).fetch();

// Combine with search
const advancedResults = await Post.objects
  .search('python')
  .filter({
    Q: [
      Q('OR',
        { author__username: 'admin' },
        { category__name: 'Technology' }
      )
    ]
  })
  .fetch();

Search with Pagination

// Paginated search results
const page1 = await Post.objects
  .search('django python')
  .fetch({
    limit: 10,
    offset: 0
  });
  
const page2 = await Post.objects
  .search('django python')
  .fetch({
    limit: 10,
    offset: 10
  });

Best Practices

1. Limit searchable fields to those that contain meaningful text to improve performance.
2. Use PostgreSQL search provider in production for better performance and relevance ranking.
3. Add a dedicated search vector column when using PostgreSQL to optimize search performance.
4. Consider custom search providers for very large datasets or specialized search requirements.
5. Combine search with filters to reduce the dataset size before applying search operations.