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.

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.

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.

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:
# 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:
- Turns the input query into an embedding vector.
code_to_embeddingis a transform flow shared by the query and indexing paths; see the next section. - Searches a database of code embeddings using cosine similarity.
- 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():
@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:
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:
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.


