Skip to main content

Search API Endpoints

Performs an advanced search across specified model collections using MongoDB aggregation.

Request​

  • Method: GET
  • Endpoint: /api/search
  • Query Parameters:
    • type (required): The model/collection name to search in
    • search (required): Search term or query string
    • index (optional): Specific index to use for search
    • paths (optional): Specific fields to search within
    • parentCompany (optional): Filter results by parent company
    • page (optional): Page number for pagination
    • limit (optional): Number of items per page

Response​

{
  "data": {
    "docs": [...],
    "totalDocs": number,
    "limit": number,
    "page": number,
    "totalPages": number,
    "hasNextPage": boolean,
    "nextPage": number,
    "hasPrevPage": boolean,
    "prevPage": number,
    "pagingCounter": number
  },
  "code": 200
}

Error Responses​

  • 400 Bad Request
    • When type is missing: "Search failed: Model type is required"
    • When search is missing: "Search failed: Search term is required"
    • When model type is invalid: "Search failed: Invalid model type: {modelName}"
  • 500 Internal Server Error
    • When search operation fails: "Search failed: {error message}"

MongoDB Text Search​

Performs a text search using MongoDB's built-in text search capabilities.

Request​

  • Method: GET
  • Endpoint: /api/mongo-search
  • Query Parameters:
    • type (required): The model/collection name to search in
    • search (optional): Text to search for
    • parentCompany (optional): Filter results by parent company
    • page (optional): Page number for pagination
    • limit (optional): Number of items per page

Response​

{
  "docs": [...],
  "totalDocs": number,
  "limit": number,
  "page": number,
  "totalPages": number,
  "hasNextPage": boolean,
  "nextPage": number,
  "hasPrevPage": boolean,
  "prevPage": number,
  "pagingCounter": number
}

Error Response​

  • 500 Internal Server Error 
    {
      "error": "Search operation failed",
      "details": "error message"
    }

Notes​

  • The general search endpoint uses MongoDB aggregation pipeline for more complex search operations
  • The MongoDB text search endpoint uses built-in text search functionality and includes relevance scoring
  • Both endpoints support pagination
  • Results are sorted by creation date (descending) by default
  • Text search results include a relevance score when search term is provided

Search Query Renderer

The renderSearchQuery utility function is responsible for constructing MongoDB aggregation pipelines for advanced search operations across different models.

Function Signature​

renderSearchQuery(modelName: string, searchTerm: string, options: {
  parentCompany?: string,
  index?: string,
  paths?: string[]
}): Object[]

Parameters​

  • modelName (string, required)

    • The name of the model/collection to search in
    • Used to determine specific search configurations for different models

  • searchTerm (string, required)

    • The search term or query string to search for
    • Can be partial words or complete phrases

  • options (object)

    • parentCompany (string, optional)

      • Company identifier to filter results by company
      • Used for multi-tenant data separation

    • index (string, optional)

      • Specific MongoDB index to use for the search
      • Can optimize search performance for specific use cases

    • paths (string[], optional)

      • Array of field paths to search within
      • Limits the search to specific fields in the document

Return Value​

Returns an array of MongoDB aggregation pipeline stages that can be used with Model.aggregate().

Usage Example​

const searchQuery = renderSearchQuery("Customer", "John Doe", {
  parentCompany: "company123",
  paths: ["firstName", "lastName", "email"],
});

const aggregate = Customer.aggregate(searchQuery);
const results = await Customer.aggregatePaginate(aggregate, options);

Industry-Specific Examples​

Trucking Industry​

// Search for trucks by make, model, or VIN
const truckSearch = renderSearchQuery("Vehicle", "Peterbilt 579", {
  paths: ["make", "model", "vin"],
});

Service Industry (HVAC, Plumbing, Electrical)​

// Search for service tickets by description or customer info
const serviceSearch = renderSearchQuery("ServiceTicket", "AC repair", {
  paths: ["description", "serviceType", "customerName"],
});

Search Behavior​

  1. The function constructs a search pipeline that:

    • Filters by parent company if specified
    • Performs text matching based on the provided search term
    • Applies any model-specific search configurations
    • Orders results by relevance

  2. Search capabilities include:

    • Partial word matching
    • Case-insensitive search
    • Multi-field search when paths are specified
    • Company-specific data isolation

Performance Considerations​

  • Using the index parameter can significantly improve search performance
  • Limiting paths to only necessary fields can optimize query execution
  • The function supports MongoDB's aggregation pipeline optimizations
  • Consider adding specific indexes for frequently searched fields

Security Notes​

  • The function automatically handles company isolation through the parentCompany parameter
  • Input sanitization should be performed before passing search terms
  • Access control should be implemented at the API route level
  • Used by the main search controller (/controllers/search/index.js)
  • Works with MongoDB aggregation framework
  • Integrates with the pagination system