AI & ML · Const

Semantic Search

Semantic search uses embeddings to find semantically relevant chunks in indexed data, including matches with few or no shared keywords. OpenAI's Retrieval API performs this search over vector stores.

How it works

Semantic search represents a natural-language query and stored content as embeddings, then ranks stored chunks by semantic similarity. OpenAI's Retrieval API performs this search over vector stores and returns matching chunks, similarity scores, and their source files; query rewriting can optionally improve search queries.

Syntax

client.vector_stores.search(vector_store_id, query, rewrite_query=false)

Parameters

Name	Type	Description
`vector_store_id`	`string`	Identifier of the vector store containing the indexed data.
`query`	`string`	Natural-language text to search for.
`rewrite_query`	`boolean`	Optional setting that rewrites the query for improved performance.

Returns

A list of results containing relevant chunks, similarity scores, and the file of origin.

Key points

The Retrieval API searches your own data by semantic meaning rather than requiring exact keyword matches.
Vector stores index the data used for semantic retrieval.
A natural-language query is passed to the vector store's search operation.
When query rewriting is enabled, the rewritten form is exposed as search_query in the result.

Common mistakes

Search results contain chunks and scores, so applications should inspect the returned content and relevance rather than treating a result as a complete document.
Query rewriting is optional; enable it explicitly when query phrasing needs optimization.

Example: Search a vector store

from openai import OpenAI

client = OpenAI()

results = client.vector_stores.search(
    vector_store_id="vs_123",
    query="How do I reset my password?",
)

for result in results.data:
    print(result.filename, result.score)
    for content in result.content:
        print(content.text)

Searches a vector store with a natural-language query and prints matching files, similarity scores, and content chunks.

When to use it

Knowledge-base retrieval

Retrieve relevant passages from an internal knowledge base before generating an answer.

Natural-language document search

Find documents matching a user's intent when exact keywords differ.

Similarity-based discovery

Locate semantically related code or text across an indexed corpus.

vector stores
embeddings
Retrieval API
query rewriting
file search

Source: Retrieval | OpenAI API. Checked 2026-10-15.