SEARCHPIPELINE

Use the standard table function DBMS_HYBRID_VECTOR.SEARCHPIPELINE to return a pipeline of row records.

This pipeline function accepts valid JSON query input and returns a pipeline of row records. The syntax is as shown below:

FUNCTION SEARCHPIPELINE(qparams JSON)
RETURN results PIPELINED;

The results is of type RECORD. The results contains the following fields:

Field	Type
doc_rowid	varchar2(18)
score	number
vector_score	number
text_score	number
vector_rank	number
text_rank	number
chunk_text	varchar2(32767)
chunk_id	varchar2(4000)
paths	varchar2(4000)

The record members are the column names in the SELECT statement. These names are the same as the JSON field names that are returned in DBMS_HYBRID_VECTOR_SEARCH(), except that paths is a list of field IDs in the record, where as the JSON result maps the ids to their actual paths (in an array). Also note that the result record could not have a member named rowid nor a member with a rowid type.

Example 12-1

SELECT
   chartorowid(doc_rowid) as doc_rowid,
   score,
   vector_score,
   text_score,
   vector_rank,
   text_rank,
   chunk_text,
   chunk_id,
   paths
FROM dbms_hybrid_vector.searchpipeline(JSON('{"hybrid_index_name" : "idx",
                                              "search_text" : "teamwork" }'));

If you do not wish to use the table function DBMS_HYBRID_VECTOR.SEARCHPIPELINE(), the original SEARCH API can be wrapped in a JSON_TABLE specification. This is shown in the example below:

SELECT jt.*
FROM
   JSON_TABLE(
        dbms_hybrid_vector.search(
                      json_object('hybrid_index_name' value 'idx',
                      'search_text' value 'teamwork'
                      RETURNING JSON)
                   ),
                   '$[*]' COLUMNS idx for ORDINALITY,
                                  doc_rowid PATH '$.rowid',
                                  score NUMBER PATH '$.score',
                                  vector_score NUMBER PATH '$.vector_score',
                                  text_score NUMBER PATH '$.text_score',
                                  vector_rank NUMBER PATH '$.vector_rank',
                                  text_rank NUMBER PATH '$.text_rank',
                                  chunk_text PATH '$.chunk_text',
                                  chunk_id PATH '$.chunk_id',
                                  paths PATH '$.paths'
                    ) jt
ORDER by idx ASC

Usage Notes

When using DBMS_HYBRID_VECTOR.SEARCHPIPELINE with search_fusion set to RERANK and search_scorer set to RRF (Reciprocal Rank Fusion) or WRRF (Weighted Reciprocal Rank Fusion), the results may not reflect the intended semantic ordering. Instead, the final ranking may prioritize rows based on their text rank rather than the semantic rerank score derived from vector distances. This behavior can lead to misleading results where rows with lower vector scores are ranked higher due to their higher text ranks.

RERANK mode is not a fusion search mode, despite being specified via the search_fusion parameter. Instead, RERANK performs a text keyword search and then uses vector scores to rerank the results. When RRF or WRRF is used with RERANK mode these scorers do not properly aggregate vector distances or semantic scores. Instead, it relies solely on the reciprocal text ranks and does not incorporate the semantic scores, even though they are computed. This behavior can lead to misleading results where rows with lower semantic scores (vector distances) are ranked higher due to their higher text ranks. Additionally, RERANK only considers documents retrieved by the initial text search (limited by text.result_max), meaning better semantically scoring documents may exist but are not evaluated. As a result, the final output may prioritize rows with higher text ranks, even if their vector scores are lower.

Applications relying on DBMS_HYBRID_VECTOR.SEARCHPIPELINE with RERANK and RRF or WRRF may receive results that appear valid but do not reflect the intended semantic ordering. This can lead to:

• Inaccurate rankings: Rows with higher semantic relevance (higher vector scores) may be ranked lower than less relevant rows with higher text ranks.
• Suboptimal search performance: Users may experience misleading or incorrect results, impacting data correctness and application reliability.

To achieve proper semantic reranking, avoid using RRF or WRRF scorers with search_fusion=RERANK. It is recommended to use search_scorer=RSF (Relative Score Fusion) for reranking, as it correctly prioritizes rows based on their vector scores.