> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/avnlp/vectordb/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

> Logical data partitioning within a single index

Namespaces partition data within a single collection or index, enabling logical separation without managing multiple collections. Use namespaces to separate development from production data, version document sets, or organize by content type.

## Overview

Namespaces provide isolated logical partitions within a vector database. Each namespace contains its own subset of vectors and can be queried independently or in combination with other namespaces.

<Info>
  Namespaces are ideal when you need data isolation but want to avoid the overhead of managing separate collections or indexes.
</Info>

## Use cases

<CardGroup cols={2}>
  <Card title="Environment separation" icon="layer-group">
    Separate dev, staging, and production data in the same index
  </Card>

  <Card title="Dataset versioning" icon="code-branch">
    Maintain multiple versions of embeddings or content
  </Card>

  <Card title="Content organization" icon="folder-tree">
    Partition by document type, source, or category
  </Card>

  <Card title="A/B testing" icon="flask">
    Compare retrieval quality across different embedding models
  </Card>
</CardGroup>

## Database strategies

Each vector database implements namespaces differently:

| Database     | Isolation Strategy        | Implementation                                 |
| ------------ | ------------------------- | ---------------------------------------------- |
| **Pinecone** | Native namespace support  | Index-level namespaces with automatic routing  |
| **Milvus**   | Partition-based isolation | Partition key field with filter expressions    |
| **Weaviate** | Tenant mechanism          | Native multi-tenancy with per-tenant shards    |
| **Qdrant**   | Collection-based          | Separate collections with shared configuration |
| **Chroma**   | Collection-based          | Individual collections per namespace           |

## Configuration

Namespace configuration varies by database:

<CodeGroup>
  ```yaml Pinecone theme={null}
  pinecone:
    api_key: "your-api-key"
    index_name: "main-index"
    namespace: "production"  # Native namespace support

  embedder:
    model: "sentence-transformers/all-MiniLM-L6-v2"
  ```

  ```yaml Milvus theme={null}
  milvus:
    uri: "http://localhost:19530"
    collection_name: "documents"
    partition_field: "namespace"  # Partition key approach

  embedder:
    model: "sentence-transformers/all-MiniLM-L6-v2"
  ```

  ```yaml Weaviate theme={null}
  weaviate:
    cluster_url: "https://your-cluster.weaviate.network"
    api_key: "your-api-key"
    collection_name: "Documents"
    tenant_field: "namespace"  # Tenant mechanism

  embedder:
    model: "sentence-transformers/all-MiniLM-L6-v2"
  ```
</CodeGroup>

## Usage example

<CodeGroup>
  ```python Create namespace theme={null}
  from vectordb.langchain.namespaces.pinecone import (
      PineconeNamespacePipeline,
  )

  pipeline = PineconeNamespacePipeline(config)

  # Create namespace
  result = pipeline.create_namespace("production")
  print(f"Created namespace: {result.namespace}")

  # Check existence
  if pipeline.namespace_exists("production"):
      print("Namespace exists")

  # List all namespaces
  namespaces = pipeline.list_namespaces()
  print(f"Available namespaces: {namespaces}")
  ```

  ```python Index to namespace theme={null}
  from langchain_core.documents import Document

  pipeline = PineconeNamespacePipeline(config)

  # Prepare documents
  documents = [
      Document(
          page_content="Vector databases enable semantic search",
          metadata={"source": "docs", "version": "v1"}
      ),
      Document(
          page_content="Embeddings capture semantic meaning",
          metadata={"source": "blog", "version": "v1"}
      )
  ]

  # Generate embeddings
  from vectordb.langchain.utils import EmbedderHelper

  embedder = EmbedderHelper.create_embedder(config)
  embeddings = EmbedderHelper.embed_documents(embedder, 
      [doc.page_content for doc in documents]
  )

  # Index to specific namespace
  result = pipeline.index_documents(
      documents=documents,
      embeddings=embeddings,
      namespace="production"
  )
  print(f"Indexed {result.count} documents")
  ```

  ```python Query namespace theme={null}
  # Query single namespace
  results = pipeline.query_namespace(
      query="What are vector databases?",
      namespace="production",
      top_k=5
  )

  for result in results:
      print(f"Score: {result.score:.3f}")
      print(f"Content: {result.content[:100]}")
      print(f"Metadata: {result.metadata}")
  ```

  ```python Cross-namespace query theme={null}
  # Query multiple namespaces
  cross_results = pipeline.query_cross_namespace(
      query="What are embeddings?",
      namespaces=["production", "staging"],
      top_k=5
  )

  # Access results by namespace
  for ns, results in cross_results.namespace_results.items():
      print(f"\nNamespace: {ns}")
      for result in results:
          print(f"  - {result.content[:80]}")

  # Compare timing across namespaces
  for comparison in cross_results.timing_comparisons:
      print(f"{comparison.namespace}: {comparison.query_time_ms}ms")
  ```
</CodeGroup>

## Management operations

### Get namespace statistics

```python theme={null}
stats = pipeline.get_namespace_stats("production")

print(f"Document count: {stats.document_count}")
print(f"Vector count: {stats.vector_count}")
print(f"Size (bytes): {stats.size_bytes}")
print(f"Created: {stats.created_at}")
print(f"Updated: {stats.updated_at}")
```

### Delete namespace

```python theme={null}
# Delete namespace and all its data
result = pipeline.delete_namespace("staging")

if result.success:
    print(f"Deleted namespace: {result.namespace}")
else:
    print(f"Error: {result.error}")
```

## Cross-namespace search

Query multiple namespaces simultaneously with performance comparison:

```python theme={null}
from vectordb.langchain.namespaces import PineconeNamespacePipeline

pipeline = PineconeNamespacePipeline(config)

# Query all namespaces
results = pipeline.query_cross_namespace(
    query="machine learning fundamentals",
    namespaces=None,  # None = all namespaces
    top_k=10
)

# Results include timing metrics per namespace
for comparison in results.timing_comparisons:
    print(f"Namespace: {comparison.namespace}")
    print(f"  Query time: {comparison.query_time_ms}ms")
    print(f"  Results: {comparison.result_count}")
    print(f"  Avg score: {comparison.avg_score:.3f}")
```

## Namespace isolation pipeline

Use dedicated search and indexing pipelines for namespace-scoped operations:

<CodeGroup>
  ```python Search pipeline theme={null}
  from vectordb.langchain.namespaces.search.pinecone import (
      PineconeNamespaceSearchPipeline,
  )

  # Create namespace-scoped search pipeline
  search_pipeline = PineconeNamespaceSearchPipeline(
      config=config,
      namespace="production"
  )

  # All searches automatically scoped to namespace
  results = search_pipeline.search(
      query="vector similarity",
      top_k=10
  )

  print(f"Namespace: {results['namespace']}")
  for doc in results["documents"]:
      print(f"- {doc.page_content[:100]}")
  ```

  ```python Indexing pipeline theme={null}
  from vectordb.langchain.namespaces.indexing.pinecone import (
      PineconeNamespaceIndexingPipeline,
  )

  # Create namespace-scoped indexing pipeline
  index_pipeline = PineconeNamespaceIndexingPipeline(
      config=config,
      namespace="production"
  )

  # Index documents to namespace
  result = index_pipeline.index(documents)
  print(f"Indexed {result['count']} documents to {result['namespace']}")
  ```
</CodeGroup>

## Performance considerations

<AccordionGroup>
  <Accordion title="Pinecone namespaces">
    Pinecone provides native namespace support with minimal overhead. Namespaces share the same index resources and scale automatically. Best for 100,000+ namespaces.
  </Accordion>

  <Accordion title="Milvus partitions">
    Milvus uses partition keys for isolation, supporting millions of tenants. Partition-based queries are optimized and only scan relevant data. Enable partition key field during collection creation.
  </Accordion>

  <Accordion title="Weaviate tenants">
    Weaviate's tenant mechanism provides strong isolation with per-tenant shards. Enterprise-grade performance with automatic tenant management. Ideal for strict data separation requirements.
  </Accordion>

  <Accordion title="Collection-based (Qdrant, Chroma)">
    Collection-based strategies create separate collections per namespace. More overhead but strongest isolation. Best for under 1000 namespaces.
  </Accordion>
</AccordionGroup>

## Best practices

<Steps>
  <Step title="Choose the right strategy">
    Use Pinecone or Milvus for high namespace counts (10,000+), collection-based approaches for strong isolation needs.
  </Step>

  <Step title="Consistent naming">
    Use clear namespace naming conventions: `{environment}_{version}` or `{team}_{dataset}`.
  </Step>

  <Step title="Clean up regularly">
    Delete unused namespaces to reduce storage costs and maintain index performance.
  </Step>

  <Step title="Monitor per-namespace metrics">
    Track document counts and query latency per namespace to identify performance issues.
  </Step>
</Steps>

## Related features

<CardGroup cols={2}>
  <Card title="Multi-tenancy" icon="users" href="/data/multi-tenancy">
    Tenant-isolated indexing and retrieval
  </Card>

  <Card title="Metadata filtering" icon="filter" href="/data/metadata-filtering">
    Structured constraints on retrieval
  </Card>

  <Card title="Hybrid search" icon="shuffle" href="/features/hybrid-search">
    Dense and sparse retrieval
  </Card>

  <Card title="Cost-optimized RAG" icon="dollar-sign" href="/advanced/cost-optimization">
    Efficient production pipelines
  </Card>
</CardGroup>