TGM Manager provides powerful search capabilities including full-text search with PostgreSQL and semantic search using AI-powered vector embeddings.

Overview¶

The search system supports:

• Full-Text Search - Traditional keyword-based search using PostgreSQL
• Semantic Search - AI-powered concept matching using vector embeddings
• Hybrid Search - Combines both approaches for best results
• Autocomplete - Search suggestions for better UX
• Multi-Entity Search - Search across different entity types

REST API¶

Full-Text Search¶

Search Specific Entity Type¶

GET /search?q=pump+failure&type=WorkOrder&limit=20&offset=0

Parameters:

Searchable Entity Types: - WorkOrder - Inspection - Intervention - Failure - Component - Unit - Location - User - Article - Faq

Response:

{
  "data": {
    "hits": [
      {
        "id": 123,
        "title": "Pump P-101 Emergency Repair",
        "description": "Failure due to bearing damage",
        "status": "COMPLETED",
        "createdAt": "2024-01-15T10:30:00",
        "score": 0.85
      },
      {
        "id": 456,
        "title": "Pump Preventive Maintenance",
        "description": "Scheduled pump inspection",
        "status": "OPEN",
        "createdAt": "2024-01-20T08:00:00",
        "score": 0.72
      }
    ],
    "total": 15,
    "limit": 20,
    "offset": 0,
    "query": "pump failure",
    "type": "WorkOrder"
  }
}

Search All Entity Types¶

GET /search/all?q=maintenance&limitPerEntity=5

Parameters:

Response:

{
  "data": {
    "hits": [
      {
        "entityType": "WorkOrder",
        "id": 123,
        "title": "Scheduled Maintenance",
        "score": 0.92
      },
      {
        "entityType": "Article",
        "id": 45,
        "title": "Maintenance Best Practices",
        "score": 0.88
      },
      {
        "entityType": "Inspection",
        "id": 789,
        "title": "Monthly Maintenance Check",
        "score": 0.75
      }
    ],
    "total": 3,
    "query": "maintenance"
  }
}

Autocomplete Suggestions¶

GET /search/suggest?q=pum&type=Component&limit=10

Response:

{
  "data": {
    "suggestions": [
      { "text": "Pump P-101", "id": 1, "type": "Component" },
      { "text": "Pump P-102", "id": 2, "type": "Component" },
      { "text": "Pump Station A", "id": 3, "type": "Component" }
    ],
    "query": "pum",
    "type": "Component"
  }
}

Count Search Results¶

GET /search/count?q=failure&type=Failure

Response:

{
  "data": {
    "count": 42,
    "query": "failure",
    "type": "Failure"
  }
}

Semantic Search¶

Semantic search uses AI to understand the meaning and context of queries, finding conceptually similar results even if exact keywords don't match.

Semantic Search¶

GET /search/semantic?q=equipment+not+working&type=Failure&limit=20&minSimilarity=0.5

Parameters:

Response:

{
  "data": {
    "hits": [
      {
        "id": 101,
        "entityType": "Failure",
        "title": "Motor stopped unexpectedly",
        "description": "Equipment malfunction caused production halt",
        "similarity": 0.89
      },
      {
        "id": 102,
        "entityType": "Failure",
        "title": "Machine breakdown",
        "description": "Conveyor belt failure",
        "similarity": 0.78
      }
    ],
    "total": 2,
    "query": "equipment not working",
    "type": "Failure",
    "semanticSearchAvailable": true
  }
}

Hybrid Search¶

Combines semantic understanding with keyword matching for comprehensive results.

GET /search/hybrid?q=pump+bearing+overheating&type=Failure&limit=20

Response:

{
  "data": {
    "hits": [
      {
        "id": 201,
        "entityType": "Failure",
        "title": "Bearing failure on pump P-101",
        "description": "High temperature caused bearing damage",
        "combinedScore": 0.95,
        "semanticScore": 0.92,
        "textScore": 0.88
      }
    ],
    "total": 1,
    "query": "pump bearing overheating",
    "type": "Failure",
    "semanticSearchAvailable": true
  }
}

Semantic Search Management¶

Reindex All Entities¶

Trigger reindexing of all entities for semantic search.

POST /search/semantic/reindex

Response:

{
  "data": "Reindex started in background"
}

Note: This is a background operation that may take time depending on data volume.

Get Index Statistics¶

GET /search/semantic/stats

Response:

{
  "data": {
    "available": true,
    "indexStats": {
      "totalDocuments": 15420,
      "byEntityType": {
        "WorkOrder": 5200,
        "Failure": 3100,
        "Inspection": 4500,
        "Component": 2620
      },
      "lastIndexed": "2024-01-31T10:00:00",
      "indexSizeBytes": 125000000,
      "embeddingModel": "text-embedding-ada-002"
    }
  }
}

Search Tips¶

Full-Text Search Syntax¶

Semantic Search Tips¶

1. Use natural language - "equipment that stopped working" vs "failure"
2. Be descriptive - More context yields better results
3. Ask questions - "Why did the pump fail?" finds related content
4. Describe symptoms - "loud noise from motor" finds similar issues

Usage Examples¶

Finding Related Work Orders¶

# Full-text search for pump issues
curl -X GET "http://localhost:1337/search?q=pump+vibration&type=WorkOrder&limit=10" \
  -H "Authorization: Bearer $JWT"

Semantic Search for Similar Problems¶

# Find failures similar to "equipment making strange noises"
curl -X GET "http://localhost:1337/search/semantic?q=equipment+making+strange+noises&type=Failure&minSimilarity=0.6" \
  -H "Authorization: Bearer $JWT"

Global Search Across All Types¶

# Search everything for "maintenance schedule"
curl -X GET "http://localhost:1337/search/all?q=maintenance+schedule&limitPerEntity=5" \
  -H "Authorization: Bearer $JWT"

Autocomplete for Forms¶

# Get component suggestions as user types
curl -X GET "http://localhost:1337/search/suggest?q=conv&type=Component&limit=5" \
  -H "Authorization: Bearer $JWT"

Hybrid Search for Best Results¶

# Combine semantic and keyword search
curl -X GET "http://localhost:1337/search/hybrid?q=recurring+bearing+problems+on+pumps&limit=20" \
  -H "Authorization: Bearer $JWT"

Configuration¶

Full-Text Search¶

Full-text search uses PostgreSQL's built-in capabilities. No additional configuration required.

Semantic Search¶

Semantic search requires an AI embedding provider. Configure in application.yml:

search:
  semantic:
    enabled: true
    provider: openai  # or azure, local
    model: text-embedding-ada-002
    batch-size: 100

  openai:
    api-key: ${OPENAI_API_KEY}

Best Practices¶

1. Start with full-text search for exact keyword matches
2. Use semantic search when keywords don't capture intent
3. Use hybrid search for comprehensive results
4. Set appropriate similarity thresholds to filter noise
5. Reindex periodically to keep semantic search current
6. Monitor index stats to ensure coverage

Comparison¶