txtai

Common errors

Warnings

Install

Install compatibility stale last tested: 2026-05-12

Imports

• Embeddings (basic semantic search)
  wrong

  from txtai import Embeddings
  
  embeddings = Embeddings()
  embeddings.index(['doc 1', 'doc 2'])
  
  # Wrong: index() again REPLACES the entire index
  embeddings.index(['doc 3'])  # doc 1 and doc 2 are now gone
  
  # Wrong: expecting text back from search without content storage
  text = embeddings.search('query', 1)[0][0]  # returns id (int), not text

  correct

  from txtai import Embeddings
  
  # Default model (all-MiniLM-L6-v2)
  embeddings = Embeddings()
  
  # Or specify model explicitly
  embeddings = Embeddings(path='sentence-transformers/all-MiniLM-L6-v2')
  
  # index() — builds NEW index, overwrites existing
  embeddings.index(['Correct answer', 'Wrong answer', 'Maybe'])
  
  # search returns list of (id, score) tuples
  results = embeddings.search('positive', 1)
  print(results)  # [(0, 0.298)] — id=0 is 'Correct answer'

  index() rebuilds the entire index from scratch — calling it again wipes previous data. Use upsert() to add/update without full rebuild. search() returns (id, score) tuples by default, not text.

• Embeddings with content storage
  wrong

  # Without content=True, search only returns (id, score)
  embeddings = Embeddings()
  embeddings.index(['text 1', 'text 2'])
  results = embeddings.search('query', 1)
  print(results[0]['text'])  # KeyError — no text in result

  correct

  from txtai import Embeddings
  
  # Enable content storage to retrieve text from search results
  embeddings = Embeddings(content=True)
  
  # Index with dict documents
  embeddings.index([
      {'id': 0, 'text': 'Python is a programming language'},
      {'id': 1, 'text': 'JavaScript runs in browsers'},
      {'id': 2, 'text': 'Rust is fast and safe'},
  ])
  
  # Now search returns dicts with text
  results = embeddings.search('compiled language', 1)
  print(results[0]['text'])  # 'Rust is fast and safe'
  
  # Can also use SQL
  results = embeddings.search(
      "SELECT text, score FROM txtai WHERE similar('web language') LIMIT 1"
  )

  Without content=True, search returns (id, score) tuples only. Enable content=True to store and retrieve document text. SQL queries also require content=True.

Quickstart stale last tested: 2026-04-23

txtai Embeddings with content storage, search, upsert, save/load.

# pip install txtai
from txtai import Embeddings

# Create embeddings with content storage
embeddings = Embeddings(
    path='sentence-transformers/all-MiniLM-L6-v2',
    content=True
)

# Index documents
embeddings.index([
    {'id': 0, 'text': 'Python is a programming language created by Guido'},
    {'id': 1, 'text': 'JavaScript is used for web development'},
    {'id': 2, 'text': 'Rust provides memory safety without garbage collection'},
    {'id': 3, 'text': 'Go is designed for cloud infrastructure'},
])

# Semantic search — returns dicts with text
results = embeddings.search('systems programming language', 2)
for r in results:
    print(r['text'], r['score'])

# Upsert — add without rebuilding
embeddings.upsert([{'id': 4, 'text': 'TypeScript adds types to JavaScript'}])

# Save and load
embeddings.save('/tmp/myindex')
embeddings.load('/tmp/myindex')