Storage

Feather stores all your vectors in a single, portable `.feather` file. This guide explains how storage works, the file format, and best practices.

How Storage Works

Feather uses a simple, efficient file format that stores vectors and metadata in a single file:

┌────────────────────────────────────┐
│ 4 bytes: "FEAT" (magic)            │
│ 4 bytes: version = 1               │
│ 4 bytes: dimension (e.g. 128)      │
├────────────────────────────────────┤
│ 8 bytes: id (uint64)               │
│ dim*4 bytes: vector (float32)      │
│ ... repeat for each vector ...     │
└────────────────────────────────────┘

The file format is designed to be simple, portable, and crash-safe.

Saving and Loading

Save your database explicitly or let it auto-save:

Python
from feather import DB

# Explicit save
db = DB.open("data.feather", dim=128)
db.add(1, vector)
db.save()  # Writes to disk

# Auto-save on close (context manager)
with DB.open("data.feather", dim=128) as db:
    db.add(1, vector)
    # Automatically saved on exit
Loading
# Load existing database
db = DB.open("data.feather", dim=128)

# Vectors are automatically loaded
# Index is rebuilt on first search

File Size Considerations

Feather files are compact. Here's the size calculation:

File Size = Header (12 bytes) + 
           (Vector Count × (8 bytes ID + dim × 4 bytes))

Example: 1M vectors, 384 dimensions
= 12 + (1,000,000 × (8 + 384 × 4))
= 12 + (1,000,000 × 1544)
≈ 1.5 GB

For smaller file sizes, consider:

  • Quantization (int8/f16) - 4× size reduction
  • Compression - additional 2-3× reduction
  • Filtering - only store relevant vectors

Backup and Sync

Since Feather uses a single file, backing up is simple:

Backup
# Simple file copy
import shutil
shutil.copy("data.feather", "data.backup.feather")

# Or use version control
# git add data.feather

For multi-device sync, Feather supports delta sync via CRDTs. See the sync documentation for details.

Best Practices

Regular Saves

Save frequently during development. Use context managers for automatic saving.

Version Control

For small databases, you can commit `.feather` files to git. For large databases, use git LFS or external storage.

Backup Strategy

Keep regular backups, especially before major updates. The single-file format makes backups trivial.