How to run a query engine in LlamaIndex

An index becomes useful to an application when a question can pass through retrieval and return the source context selected for an answer. A LlamaIndex query engine provides that boundary between indexed documents, retrieval settings, and response synthesis.

The high-level index.as_query_engine() API creates a query engine from an existing index. Setting similarity_top_k=1 keeps this smoke test focused on one source node, while response.source_nodes exposes the retrieved content independently of the generated answer.

The credential-free test uses MockLLM and MockEmbedding to exercise the query path without an external service. Replace both mock models with the application's configured models before judging answer quality or retrieval behavior across multiple documents.

1. Create query_engine_check.py with the imports and local mock model settings.

   query_engine_check.py

   from llama_index.core import Document, MockEmbedding, Settings, VectorStoreIndex
   from llama_index.core.llms import MockLLM
    
    
   Settings.llm = MockLLM()
   Settings.embed_model = MockEmbedding(embed_dim=8)

   LlamaIndex must already be installed in the same Python environment.
   Related: How to install LlamaIndex with pip

2. Add the controlled support-policy document below the model settings.

   query_engine_check.py

   documents = [
       Document(
           text=(
               "The Atlas support playbook says refund requests must be "
               "reviewed by the billing team before a credit is issued."
           ),
           metadata={"source": "atlas-support-playbook"},
       )
   ]

3. Add the query-engine construction below the document list.

   query_engine_check.py

   index = VectorStoreIndex.from_documents(documents)
   query_engine = index.as_query_engine(similarity_top_k=1)

   The one-document fixture makes the retrieved source unambiguous. Production retrieval tests need the application's embedding model and a representative document set.

4. Add the query and retrieved-source output below the query engine.

   query_engine_check.py

   response = query_engine.query(
       "Who reviews refund requests before a credit is issued?"
   )
   source_node = response.source_nodes[0].node
    
   print(f"source_count={len(response.source_nodes)}")
   print(f"source={source_node.metadata['source']}")
   print(f"source_text={source_node.get_content()}")

5. Compare the completed query_engine_check.py file with this consolidated version.

   query_engine_check.py

   from llama_index.core import Document, MockEmbedding, Settings, VectorStoreIndex
   from llama_index.core.llms import MockLLM
    
    
   Settings.llm = MockLLM()
   Settings.embed_model = MockEmbedding(embed_dim=8)
    
   documents = [
       Document(
           text=(
               "The Atlas support playbook says refund requests must be "
               "reviewed by the billing team before a credit is issued."
           ),
           metadata={"source": "atlas-support-playbook"},
       )
   ]
    
   index = VectorStoreIndex.from_documents(documents)
   query_engine = index.as_query_engine(similarity_top_k=1)
    
   response = query_engine.query(
       "Who reviews refund requests before a credit is issued?"
   )
   source_node = response.source_nodes[0].node
    
   print(f"source_count={len(response.source_nodes)}")
   print(f"source={source_node.metadata['source']}")
   print(f"source_text={source_node.get_content()}")

6. Run the completed query engine script.

   $ python query_engine_check.py
   source_count=1
   source=atlas-support-playbook
   source_text=The Atlas support playbook says refund requests must be reviewed by the billing team before a credit is issued.

   The source count, metadata value, and retrieved text confirm that the query engine reached the indexed support playbook.