Searching Documents with Full-Text and Metadata Search

QualityDocD provides two search interfaces backed by two search engines. The .NET application’s Reports/Search page and the PHP portal’s Documents page both query the Search Service first, falling back to SQL Server (or PostgreSQL token index) when the service is unavailable. The Node.js API exposes a lower-level search endpoint with granular control over search mode and field targeting. This guide explains how each interface works and when to use each one.

For the fastest search response, use mode=metadata in the Node.js API. This queries the MongoDB $text index, which is optimized with per-field weights (title: 10, tags: 5, standard: 3, description: 1). Use mode=all when you need the most complete results, combining metadata and full-text content matching.

Search interfaces

.NET App — Reports/Search
Node.js API — GET /search
PHP Portal — documents.php

The .NET application exposes a search report at GET /Reports/Search. This interface accepts the parameters q, category, and status, and internally calls the Search Service. If the Search Service is unavailable, it falls back to a SQL Server query against titles, descriptions, codes, and tags.Endpoint:

GET /Reports/Search?q={query}&category={category}&status={status}

Parameter	Description
`q`	Free-text search term matched against title, description, code, and tags.
`category`	Filter by document category (e.g., `Manual`, `Procedure`, `Record`, `Audit`).
`status`	Filter by document status (e.g., `Approved`, `Draft`).

Results are returned as cards showing the document code, status badge, title, category, standard, and up to five tags. Each card links to the document detail page in the .NET app.

Access to /Reports/Search requires the Admin, Manager, or Reviewer role. Unauthenticated or Viewer-only users are redirected to login.

Fallback behavior: When the Search Service HTTP call fails or returns a non-success status code, the .NET app automatically falls back to a SQL Server query. The fallback returns up to 50 results ordered by creation date descending.Example curl:

curl "https://your-app/Reports/Search?q=quality+manual&category=Manual&status=Approved"

The Node.js API provides a more powerful search endpoint with explicit control over the search engine and field scope. It requires authentication (requireAuth) and at minimum MODULE_2 access (standard users).Endpoint:

GET /search?q={query}&mode={mode}&field={field}

Parameter	Values	Description
`q`	Any string	The search query. An empty `q` with `mode=metadata` returns all indexed documents.
`mode`	`all` (default), `metadata`, `content`	Controls which search engine(s) are used. See Search modes below.
`field`	`all` (default), `title`, `body`	Restricts PostgreSQL token matching to a specific field (only applies in `metadata` mode when MongoDB is unavailable).

Example curl:

curl -H "Authorization: Bearer <token>" \
  "https://your-api/search?q=ISO+9001&mode=metadata&field=title"

Response shape:

{
  "query": "ISO 9001",
  "mode": "metadata",
  "total": 3,
  "results": [
    {
      "source": "mongodb-metadata",
      "documentId": 42,
      "versionId": 17,
      "title": "Quality Manual ISO 9001",
      "versionNumber": "1.0",
      "contentUrl": null,
      "matchedIn": "metadata",
      "snippet": "…relevant excerpt from contentText…"
    }
  ]
}

The PHP portal’s Documents page (documents.php) displays only Approved documents. It queries the Search Service’s /api/search endpoint directly, passing status=Approved on every request.

GET /api/search?q={query}&category={category}&status=Approved

The portal shows document cards with the code, title, category, standard, file size, and tags. There are no direct links to download files from the portal — authenticated users must use the .NET app’s download endpoint.If the Search Service is unreachable, the portal displays a warning message: “El servicio de búsqueda no está disponible.” with a prompt to verify that the Docker containers are running.Example curl against the Search Service:

curl "http://search-service:3100/api/search?q=procedure&category=Procedure&status=Approved"

Search modes

The Node.js API GET /search supports three modes that control which engines are queried:

Mode	Primary engine	Fallback	`matchedIn` value
`metadata`	MongoDB `$text` index on `title`, `description`, `tags`, `standard`	PostgreSQL token index	`metadata` or `title`/`body`/`both`
`content`	MongoDB regex search on `contentText`	None	`content`
`all`	Both `metadata` and `content`	PostgreSQL token index for metadata half	`metadata`, `content`, or `metadata+content`

MongoDB metadata search

When mode=metadata (or mode=all) and a non-empty q is provided, the search queries the MongoDB document_metadata collection using a $text index with the following field weights:

Field	Weight
`title`	10
`tags`	5
`standard`	3
`description`	1

Results are sorted by text score (highest relevance first), limited to 30 documents per query.

PostgreSQL token fallback

If the MongoDB query fails (e.g., MongoDB is offline), the metadata search falls back to the PostgreSQL search_index table. The fallback tokenizes the query and matches against pre-built titleTokens and bodyTokens arrays stored per document version. The field parameter controls whether only title tokens, only body tokens, or both are checked.

Content search

When mode=content (or mode=all) and q is non-empty, a MongoDB regex search ($regex, case-insensitive) is performed against the contentText field. If a document was already found in the metadata pass, its matchedIn field is updated to metadata+content rather than adding a duplicate result.

Autocomplete suggestions

GET /search/suggest?q={prefix}

Returns up to 10 autocomplete suggestions based on a prefix match against document titles in MongoDB. Requires at least 2 characters in q. Access requirement: MODULE_3 (OPERATOR role or higher). Response:

{
  "suggestions": [
    { "id": 42, "title": "Quality Manual ISO 9001" },
    { "id": 57, "title": "Quality Procedure QP-001" }
  ]
}

Manually re-indexing a document version

POST /search/index
Body: { "versionId": 17 }

Forces a specific document version to be re-indexed in the PostgreSQL token index. This is useful if a document’s content was updated outside the normal approval flow or if the index entry became stale.

Manual re-indexing via POST /search/index requires MODULE_1 access (OPERATOR role or higher). Documents are automatically indexed when a version is approved via POST /documents/:id/versions/:versionId/approve — manual re-indexing is only needed for exceptional cases.

Automatic indexing

Documents are automatically synced to the Search Service whenever they are created, updated, submitted for review, approved, rejected, or marked obsolete in the .NET application. The sync call posts document metadata (id, code, title, description, category, standard, tags, fileExtension, status, isPublic) to POST /api/documents on the Search Service, which upserts the record in the MongoDB document_metadata collection. If the Search Service is unavailable during a sync, the error is logged as a warning and the primary operation (create/update/approve) continues without being blocked.

Getting Started

Core Concepts

User Guide

Deployment

Searching Documents with Full-Text and Metadata Search

Search interfaces

Search modes

MongoDB metadata search

PostgreSQL token fallback

Content search

Autocomplete suggestions

Manually re-indexing a document version

Automatic indexing

Build docs developers (and LLMs) love

Getting Started

Core Concepts

User Guide

Deployment

Documentation Index

​Search interfaces

​Search modes

​MongoDB metadata search

​PostgreSQL token fallback

​Content search

​Autocomplete suggestions

​Manually re-indexing a document version

​Automatic indexing

Build docs developers (and LLMs) love

Search interfaces

Search modes

MongoDB metadata search

PostgreSQL token fallback

Content search

Autocomplete suggestions

Manually re-indexing a document version

Automatic indexing