Skip to main content

​
Overview

Vector stores are collections of processed files that can be used with the file_search tool for retrieval-augmented generation. They automatically chunk, embed, and index your documents for semantic search.
Vector stores require the OpenAI-Beta: assistants=v2 header, which is automatically added by the SDK.

​
Create vector store

Creates a new vector store. 
vector_store = client.vector_stores.create(
  name: "Product Documentation",
  file_ids: ["file-abc123", "file-def456"]
)

​
Parameters

​
name
string
Name of the vector store
​
file_ids
array
List of file IDs to add to the vector store
​
description
string
Description of the vector store’s purpose
​
chunking_strategy
object
How to chunk files. Options:
​
expires_after
object
Expiration policy
​
metadata
hash
Optional metadata (up to 16 key-value pairs)

​
Response

​
id
string
Unique vector store identifier
​
name
string
Name of the vector store
​
status
string
Processing status: expired, in_progress, or completed
​
file_counts
object
File processing counts:
​
usage_bytes
integer
Total bytes used by files
​
created_at
integer
Unix timestamp of creation

​
Retrieve vector store

Retrieves a vector store by ID. 
vector_store = client.vector_stores.retrieve("vs_abc123")
puts vector_store.status

​
Parameters

​
vector_store_id
string
required
ID of the vector store

​
Update vector store

Modifies a vector store. 
vector_store = client.vector_stores.update(
  "vs_abc123",
  name: "Updated Product Docs",
  metadata: { version: "2.0" }
)

​
Parameters

​
vector_store_id
string
required
ID of the vector store to modify
​
name
string
New name
​
expires_after
object
Updated expiration policy
​
metadata
hash
Updated metadata

​
List vector stores

Returns a list of vector stores. 
vector_stores = client.vector_stores.list(
  limit: 20,
  order: :desc
)

vector_stores.data.each do |vs|
  puts "#{vs.name} (#{vs.file_counts.completed} files)"
end

​
Parameters

​
limit
integer
Number to return (1-100, default: 20)
​
order
string
Sort order: asc or desc (default)
​
after
string
Cursor for pagination
​
before
string
Cursor for reverse pagination

​
Delete vector store

Deletes a vector store. 
client.vector_stores.delete("vs_abc123")

​
Parameters

​
vector_store_id
string
required
ID of the vector store to delete

​
Search vector store

Searches a vector store for relevant chunks based on a query. 
results = client.vector_stores.search(
  "vs_abc123",
  query: "How do I configure authentication?",
  max_num_results: 10
)

results.data.each do |result|
  puts "Score: #{result.score}"
  puts "Content: #{result.content}"
end

​
Parameters

​
vector_store_id
string
required
ID of the vector store to search
​
query
string | array
required
Search query (string or array of strings)
​
max_num_results
integer
Maximum results to return (1-50, default: 20)
​
filters
object
File attribute filters for narrowing search results
​
ranking_options
object
Ranking configuration options
​
rewrite_query
boolean
Whether to rewrite the query for better vector search

​
File management

Vector stores provide nested resources for managing files:

​
Add files to vector store

file = client.vector_stores.files.create(
  "vs_abc123",
  file_id: "file-xyz789"
)

​
List files in vector store

files = client.vector_stores.files.list("vs_abc123")

​
Create file batch

batch = client.vector_stores.file_batches.create(
  "vs_abc123",
  file_ids: ["file-1", "file-2", "file-3"]
)

​
Examples

​
RAG with vector stores

# Upload documents
file1 = client.files.create(
  file: "docs/guide.pdf",
  purpose: "assistants"
)

file2 = client.files.create(
  file: "docs/api.pdf",
  purpose: "assistants"
)

# Create vector store
vector_store = client.vector_stores.create(
  name: "Documentation",
  file_ids: [file1.id, file2.id],
  chunking_strategy: { type: "auto" }
)

# Wait for processing
loop do
  vs = client.vector_stores.retrieve(vector_store.id)
  break if vs.status == "completed"
  sleep 2
end

Build docs developers (and LLMs) love

Get started for freeTalk to us