Working with records

Insert
  ↓
Search
  ↓
Get
  ↓
Update metadata
  ↓
Soft-delete (or hard-delete)

Insert

Insert a record writes one vector. Batch insert writes many in one request — reach for it once you're writing more than a handful of vectors at a time, since it's one round trip instead of many.

Both accept a request_id (single insert) or per-item request_ids (batch) for idempotent writes: replaying the same id within the dedup window returns the record the first request created instead of inserting a duplicate. Pass one on every write your application might retry — network timeouts and retries are the normal case this protects, not an edge case.

Search

Vector search finds the nearest records to a query vector. It's read-only and doesn't touch anything you insert.

Get

Get a record fetches one record by id — useful for confirming what a search hit actually contains, or for reading current metadata before an update (see below).

Update metadata

Update metadata replaces metadata wholesale — not a merge. If you only want to change one field, fetch the current metadata with Get first, merge client-side, then send the full object.

Delete

Two different operations, not one:

• Soft-delete a record — the record stops appearing in search, but its slot and audit history are kept. Reach for this by default.
• Delete a record — frees the slot immediately. A genuine hard delete.

Encrypted records

Insert an encrypted record is a separate, special-purpose operation — not a normal searchable vector. Use it only when you need a payload that can be made permanently unreadable on demand (crypto-shredding).