Trace search results back to source data

Define query handlers in CocoIndex and trace search results back to source data in CocoInsight to close the loop on indexing strategy.

TutorialUpdated 2 min read
Trace search results back to source data in CocoInsight
Enlarge cover

Trace search results back to source data

Zoom in to see details.

Trace search results back to source data in CocoInsight

Query handlers connect CocoIndex flows to CocoInsight, where you can run queries, inspect the results and trace each result back to its source data.

CocoInsight

Does my data transformation create a meaningful index for retrieval?

CocoInsight has a Query mode. To enable it, add a query handler to your flow. You can then query the index and view the collected information for any entity.

CocoInsight Query Mode
CocoInsight Query ModeEnlarge

CocoInsight Query Mode

Zoom in to see details.

CocoInsight Query Mode

Each result links back, step by step, to how the indexing path produced it.

Where are the results coming from?

For example, this chunk comes from the file docs/docs/core/flow_def.mdx. The file was split into 30 chunks.

trace back data
trace back dataEnlarge

trace back data

Zoom in to see details.

trace back data

Why is my chunk not showing in the search result?

A query ranks chunks by a score. In CocoInsight, you can open any file and see the score of each of its chunks for the same query.

missing chunks
missing chunksEnlarge

missing chunks

Zoom in to see details.

missing chunks

CocoInsight lets you inspect transformations and test indexing strategies without building a separate interface.

Integrate query logic with CocoIndex

Query handler

A query handler is a function that takes a query string and returns structured results. Tools like CocoInsight discover it, so you can query your index without building your own UI. To run queries in CocoInsight, define one; the handler can use any library to run the query.

The V0 documentation covers query handlers.

For example:

python
# Declaring it as a query handler, so that you can easily run queries in CocoInsight.
@code_embedding_flow.query_handler(
    result_fields=cocoindex.QueryHandlerResultFields(
        embedding=["embedding"], score="score"
    )
)
def search(query: str) -> cocoindex.QueryOutput:
    # Get the table name, for the export target in the code_embedding_flow above.
    table_name = cocoindex.utils.get_target_default_name(
        code_embedding_flow, "code_embeddings"
    )
    # Evaluate the transform flow defined below with the input query, to get the embedding.
    query_vector = code_to_embedding.eval(query)
    # Run the query and get the results.
    with connection_pool().connection() as conn:
        register_vector(conn)
        with conn.cursor() as cur:
            cur.execute(
                f"""
                SELECT filename, code, embedding, embedding <=> %s AS distance, start, "end"
                FROM {table_name} ORDER BY distance LIMIT %s
            """,
                (query_vector, TOP_K),
            )
            return cocoindex.QueryOutput(
                query_info=cocoindex.QueryInfo(
                    embedding=query_vector,
                    similarity_metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY,
                ),
                results=[
                    {
                        "filename": row[0],
                        "code": row[1],
                        "embedding": row[2],
                        "score": 1.0 - row[3],
                        "start": row[4],
                        "end": row[5],
                    }
                    for row in cur.fetchall()
                ],
            )

This code defines a query handler that:

  1. Turns the input query into an embedding vector. code_to_embedding is a transform flow shared by the query and indexing paths; see the next section.
  2. Searches a database of code embeddings using cosine similarity.
  3. Returns the top matching chunks with their filename, code, embedding, score, and positions.

Sharing logic between indexing and query

When you build a vector index and query it, the query must be embedded the same way as the indexed chunks. Define that logic once as a transform flow with @cocoindex.transform_flow():

python
@cocoindex.transform_flow()
def code_to_embedding(text: cocoindex.DataSlice[str]) -> cocoindex.DataSlice[NDArray[np.float32]]:
    return text.transform(
        cocoindex.functions.SentenceTransformerEmbed(
            model="sentence-transformers/all-MiniLM-L6-v2"))

In the indexing flow, call it on each chunk:

python
with file["chunks"].row() as chunk:
    chunk["embedding"] = chunk["text"].call(code_to_embedding)

In the query handler, call its eval() method on the query string:

python
def search(query: str) -> cocoindex.QueryOutput:
    # Evaluate the transform flow defined above with the input query, to get the embedding.
    query_vector = code_to_embedding.eval(query)

Examples

These V0 examples define query handlers:

Beyond vector index

This post uses a vector index from the code embedding example. CocoIndex also supports knowledge graphs, structured extraction, and custom transformations.

Source

Browse the CocoIndex source on GitHub.

Frequently asked questions

What is a query handler in CocoIndex?

A query handler is a function that takes a query string and returns structured results. Declaring it with @flow.query_handler(...) makes it discoverable by tools like CocoInsight, so you can query your indexes without building your own UI. See Query handler.

How do I run queries against my index inside CocoInsight?

Enable Query mode by adding a query handler. You can then run queries and view the collected information for any entity directly in CocoInsight, with each result linked back to how the data was generated on the indexing path. See CocoInsight.

How do I keep embedding logic consistent between indexing and querying?

Define the shared logic once with @cocoindex.transform_flow(). In the indexing flow you call it directly on a data slice; in the query path you call its eval() method with the query string. Both paths then compute the embedding the same way. See Sharing logic between indexing and query.

How do I trace a search result back to its source data?

In CocoInsight, each query result links back, step by step, to how the indexing path produced it. For example, a chunk traces to its source file and to the chunks that file was split into. See Where are the results coming from?.

Why is my chunk not showing up in the search results?

A query ranks chunks by a score. In CocoInsight you can open any file and see the score of each of its chunks for the same query, which shows why a chunk ranked where it did. See Why is my chunk not showing in the search result?.

Does query support only work with vector indexes?

No. This walkthrough uses a vector index; CocoIndex also supports knowledge graphs, structured extraction and custom transformations. See Beyond vector index.

Build fresh context for your agents.

CocoIndex keeps derived data in sync with its sources. Only what changed re-runs.