Architecture

The app is the top layer of a four-component stack.

Entities

Document — tracks ingested files. Key attributes: Id, FileName, UploadedAt, Status (Processing, Active, or Failed).

DocumentChunk — stores text chunks, embeddings, and BM25 index state. Attributes: Id, DocumentId, PageNumber (1-based), ChunkIndex (0-based), ChunkText, VectorJson, ChunkHash, TokenCount (Integer, null until IndexChunks runs — new in this release).

BM25Term — one row per unique Porter-stemmed term. Attributes: Id, Term (unique index), DocumentFrequency (populated by RecomputeBM25Stats timer, not at ingestion time).

BM25Posting — one row per (term, chunk) pair. Inverted index for query time. Attributes: Id, BM25TermId, DocumentChunkId, TermFrequency.

BM25Stats — singleton holding TotalChunks and TotalTokenCount for BM25 length normalisation. Refreshed by RecomputeBM25Stats timer. Must contain a row before any hybrid search is valid.

QueryEmbeddingCache — stores cached query vectors and search results. One record per unique query hash and embedding model. Key attributes: QueryHash (lookup key), CachedQueryVector (always stored), CachedResult (stored only when IsCacheResult is True), CacheMaxAgeMinutes (per-record TTL), HitCount (cache hit counter).

Screens

File Upload: upload a PDF, extract and chunk the text, generate embeddings, and build the BM25 index in one workflow. Drag-and-drop file upload included. Default chunk size is 1000 characters with 150-character overlap.

Performance note: ingestion runs synchronously on screen. Very large files can hit ODC's execution time limit. For large documents, run the ingestion logic in a background Timer or ODC Workflow instead.

Semantic Search: type a natural language query and retrieve matching chunks ranked by score with page references. Toggle between semantic and hybrid search from the same screen. Includes a switch to enable or disable result caching at runtime. When caching is on, the query vector and search result are stored for repeat queries. When off, the query vector is still cached but results are always fetched fresh.

Documents: inspect ingested documents and their processing status.

Vectors: inspect stored chunks, hash values, vector entries, and BM25 token detail per chunk. Select the Index Chunk (BM25) tab to view stemmed tokens and their frequencies for any indexed chunk. Useful for verifying what has been ingested and confirming the pipeline ran correctly.

How It Works

Document Ingestion: user uploads a PDF, text is extracted by page, split into overlapping chunks, embedded via the API endpoint, and stored as Document and DocumentChunk records. BM25Engine.IndexChunk is called per chunk: TokenCount is written back to DocumentChunk, and BM25Term and BM25Posting rows are created. Document status is set to Active or Failed.

Semantic Search: query text is hashed and checked against QueryEmbeddingCache. Cache hit with result: cached result returned immediately. Cache hit without result: stored vector used for cosine similarity, no embedding call. Cache miss: query embedded via API, cosine similarity runs against DocumentChunk. Results below the minimum score threshold are excluded. Query vector always stored; result stored only when result caching is enabled.

Hybrid Search: HybridSearchWithBM25 runs the vector leg via SearchVectorWithCache (TopK x 2 candidates), then the BM25 leg via BM25Engine.TokenizeText and BM25Engine.ScoreQuery. Both ranked lists are fused using Reciprocal Rank Fusion (RRF, k=60). A minimum score filter is applied. The top TopK results are returned as a SearchResult list, identical in structure to semantic search output.

Site Properties

Configure these in the ODC Portal under your application's runtime settings before running any operations.

Setup

• Install dependencies. When installing from Forge, ODC will install the required dependencies automatically. Verify they are present in Manage Dependencies in ODC Studio: SemanticEngineV2, Semantic Engine V2 Library, BM25Engine.
• Install the background workflow OML. Ingestion does not run standalone. A separate OML module is required to handle the background ingestion workflow. Download it from the GitHub repository: https://github.com/dbresults/odc-semantic-search. Import the OML into your ODC portal, publish it, and add a reference to its process actions from the main app.
• Configure Site Properties. Open the ODC Portal, navigate to your application's runtime settings, and set EmbeddingAPIKey. Verify the endpoint, model, and Azure flag match your deployment.
• Upload a document. Use the File Upload screen to ingest a PDF. This populates both the vector store and the BM25 index.
• Run RecomputeBM25Stats. Trigger the timer manually from the ODC Portal after the first ingestion. Hybrid search returns an error if this step is skipped.
• Validate. Run a query on the Semantic Search screen with Hybrid Search toggled on. Confirm results return with page references.

Limitations

• Dependencies required. Semantic Engine V2 Library, SemanticEngineV2 External Logic, and BM25Engine External Logic must be installed for ingestion and hybrid search to work. The background ingestion workflow OML from https://github.com/dbresults/odc-semantic-search is also required for ingestion to run.
• Large PDFs may timeout. Ingestion runs synchronously on screen. Very large files can hit ODC's execution time limit. Run ingestion in a background Timer or ODC Workflow for large documents.
• Linear scan does not scale indefinitely. Both vector search and BM25 scoring scan all stored chunks and posting rows at query time. This works well for small to medium knowledge bases. For large document collections, query time will degrade and an external vector database is the right tool.
• BM25Stats must be initialised before hybrid search. RecomputeBM25Stats must run after the first index. If BM25Stats has no row, HybridSearchWithBM25 returns an error.