Collections & Namespaces

Last updated: Jun 21, 2026 Author: Aspirant Edu Team

As your data grows, you need to organise it. Vector databases use collections (top-level containers) and namespaces (partitions within them) to keep vectors separated, searchable, and multi-tenant. Getting this hierarchy right is key to structuring a production vector store — it affects isolation, performance, and how you manage data over time.

💡 In one line: Collections are top-level containers for vectors; namespaces partition a collection to isolate subsets (like per-customer data).

The Hierarchy

Vector stores are organised in layers:

Database → Collections → Namespaces → Records.

Remove

Collections (a.k.a. Indexes)

A collection is the top-level container for a set of vectors — think of it as a "table" for embeddings. A collection fixes:

• a dimension (all vectors must match), and
• a distance metric (e.g. cosine).

You create separate collections for different embedding models or use cases (for example, docs vs images). Every query runs inside one collection.

Namespaces (a.k.a. Partitions / Tenants)

A namespace is a subdivision within a collection that isolates a subset of vectors. Queries are scoped to a namespace, which makes them a natural fit for:

• Multi-tenancy — a namespace per customer or user.
• Environments — dev vs prod.
• Logical separation — different projects in one collection.

Because a namespace is a hard partition, scoped searches are also faster (less data to scan).

Terminology Varies by Database

So loosely: collection ≈ index, and namespace ≈ partition / tenant.

Namespaces vs. Metadata Filtering

Both narrow a search, but differently:

• Namespace — a hard partition: clean isolation, faster, but data is physically separated.
• Metadata filter — a soft filter within a collection: flexible, but it searches the whole set and then filters.

Use namespaces for tenant isolation, and metadata filters for attribute filtering. This decision guide helps — 

Whiteboard

Why Organise This Way

• Separation & security — isolate tenants.
• Performance — scope searches to the relevant subset.
• Different models — separate collections for different dimensions.
• Lifecycle — drop a namespace or collection cleanly.

Code Example

Best Practices

• One collection per embedding model / dimension.
• Namespaces for tenants, users, or environments.
• Don't over-partition — too many namespaces adds overhead.
• Combine namespaces (isolation) with metadata filters (attributes).

Summary

• Vector stores are organised as Database → Collections → Namespaces → Records.
• A collection fixes a dimension and metric; use one per model/use case.
• A namespace partitions a collection for isolation (e.g. per customer) and faster scoped search.
• Namespaces are hard partitions; metadata filters are soft — use each for its purpose.
• Terminology varies (index/partition), but the concepts are the same. EOF echo created