VectorStoreIndex: searching documents by meaning

VectorStoreIndex is an index that embeds every chunk of your documents once and stores the vectors, so a question only has to be embedded and compared with them.

Last updated: 28 Sep, 2026 · LlamaIndex 0.14

The last lesson compared one question to three sentences by hand. VectorStoreIndex does that comparison for a whole document set, and its retriever is the first tool for seeing what a question pulls back.

Wrapping text as Documents

A Document is text plus metadata, a dictionary of facts about it such as the file it came from:

from llama_index.core import Document, VectorStoreIndex

documents = [
    Document(text="You can get a full refund within 30 days of delivery.", metadata={"file_name": "refunds.md"}),
    Document(text="Standard delivery takes 3 to 5 working days.", metadata={"file_name": "delivery.md"}),
    Document(text="The LMP-204 desk lamp has a known cable fault.", metadata={"file_name": "lamps.md"}),
]

Building the index

from_documents splits each document into chunks, embeds them with Settings.embed_model, and keeps the vectors in memory:

index = VectorStoreIndex.from_documents(documents)

Building the index end to end

from llama_index.core import Document, VectorStoreIndex

documents = [
    Document(text="You can get a full refund within 30 days of delivery.", metadata={"file_name": "refunds.md"}),
    Document(text="Standard delivery takes 3 to 5 working days.", metadata={"file_name": "delivery.md"}),
    Document(text="The LMP-204 desk lamp has a known cable fault.", metadata={"file_name": "lamps.md"}),
]
index = VectorStoreIndex.from_documents(documents)
print(type(index).__name__, len(index.docstore.docs))

VectorStoreIndex 3

Reading what was built

• VectorStoreIndex is the object returned, ready to answer questions.
• Three documents are in the docstore, one per text, each split and embedded during the build.
• The embedding happened once, at build time, so questions later only embed themselves.

Asking the retriever directly

as_retriever(similarity_top_k=2) returns the two closest chunks for a question, each with its score, the cosine similarity from the last lesson:

retriever = index.as_retriever(similarity_top_k=2)
for question in ["How do I get my money back?", "My parcel is late"]:
    results = retriever.retrieve(question)
    print(question, [(r.metadata["file_name"], round(r.score, 3)) for r in results])

Retrieving the closest chunks with scores

retriever = index.as_retriever(similarity_top_k=2)
for question in ["How do I get my money back?", "My parcel is late"]:
    results = retriever.retrieve(question)
    print(question, [(r.metadata["file_name"], round(r.score, 3)) for r in results])

How do I get my money back? [('refunds.md', 0.507), ('lamps.md', 0.099)]
My parcel is late [('delivery.md', 0.416), ('refunds.md', 0.289)]

Reading the retrieved chunks

• Both questions that defeated keyword search in the previous lesson now find the right document first.
• Each result carries a score, the cosine similarity, so you can see how close the match was.
• Top-k always returns k results: the second chunk for each question is the next closest, relevant or not.

By-hand similarity vs VectorStoreIndex

When to reach for a vector index

• Any search over more than a handful of passages, where sorting by hand is impractical.
• As the store behind a query engine and an agent, both later in the course.
• Whenever you want the retriever's scores to debug why an answer was wrong.

Related

• Previous: Embeddings: text as numbers that carry meaning
• Next: SimpleDirectoryReader: loading a folder of documents
• Reference: Indexing your data