Skip to main content

Namespace

Multi-Tenant Isolation

A Namespace represents an isolated boundary within MatsuDB, creating complete data separation between different tenants, organizations, or projects. Every piece of information in the system belongs to exactly one namespace.

Definition​

A namespace represents an isolated boundary within MatsuDB, creating complete data separation between different tenants, organizations, or projects. Every piece of information in the system belongs to exactly one namespace, ensuring that data from one namespace remains invisible and inaccessible to operations within another namespace. This isolation operates at the foundational level of the system, providing security guarantees that extend across all operations, queries, and processing workflows.

The namespace concept enables multi-tenant architectures where a single MatsuDB instance serves multiple independent organizations. Each organization operates within its own namespace, maintaining separate document collections, configurations, and search spaces. Namespaces serve as organizational units that enable secure sharing of infrastructure while maintaining complete data separation.

Core Philosophy: Complete Isolation​

Namespaces create hermetic boundaries where data, operations, and configurations remain completely separate. When a query executes within a namespace context, it sees only information belonging to that namespace. When documents are uploaded, they enter the namespace's isolated space. When configurations are established, they apply exclusively within their namespace. This isolation represents a fundamental architectural principle where namespace membership determines visibility, access, and behavior.

Isolation is Fundamental

This approach enables secure multi-tenancy without requiring separate infrastructure per tenant. Organizations can share the same MatsuDB instance while maintaining complete data privacy. The system enforces isolation automatically, ensuring that operations within one namespace cannot access or influence data in another namespace.

Identity and Scope​

Each namespace is identified by a unique namespace identifier, a string that serves as the primary key for all namespace-scoped operations. This identifier appears in every API request, establishing the context for all subsequent operations. The namespace identifier determines which data is visible and which configurations apply.

All entities within MatsuDB belong to a namespace. Nodes, positions, metadata, and configurations all carry namespace membership as part of their identity. This membership is immutable—once an entity belongs to a namespace, it cannot be moved to another. This immutability ensures that isolation boundaries remain stable and predictable, preventing accidental data migration that could compromise security.

Namespace Context in API Operations​

All API operations require a namespace context, which is provided through your authentication token. The security token encapsulates the namespace identifier, establishing the isolation boundary for all operations. This context determines which data is visible, which rules apply, and which processing workflows execute.

All other API operations require a namespace context, typically provided through request headers or context parameters. This context determines the namespace boundary for the operation, ensuring that queries, document uploads, configurations, and search operations execute within the correct isolated space.

Authentication

Namespace context is typically provided through the security header in API requests. This header establishes the namespace boundary for all subsequent operations in that request.

Isolation Guarantees​

Namespace isolation operates at multiple levels:

Query operations automatically filter results to include only entities belonging to the current namespace context. Whether querying nodes, positions, or metadata, results are automatically scoped to the namespace.

This multi-level enforcement ensures that isolation cannot be bypassed through any operation path. Whether accessing data through direct queries, search interfaces, or processing workflows, the namespace boundary remains intact. The system treats namespace membership as a fundamental property that influences every operation, ensuring complete separation between namespaces.

Processing and Configuration​

Each namespace can establish its own processing configurations. Settings configured within a namespace apply only to nodes and operations within that namespace. This enables organizations to customize their document processing pipelines according to their specific needs while maintaining complete independence from other namespaces.

When documents are uploaded to a namespace, workflows execute within that namespace's context. The resulting nodes, embeddings, and enriched content all belong to the namespace, ensuring that processing outputs remain isolated. This namespace-scoped processing enables different organizations to apply different enrichment strategies or processing workflows without interference.

Customization Per Namespace

Different namespaces can apply different rules and triggers, different workflow configurations, and different processing strategies. This enables organizational independence within a shared infrastructure.

Relationship to Other Concepts​

Namespaces provide the isolation boundary within which all other MatsuDB concepts operate:

  • Nodes: Belong to namespaces, determining their visibility and accessibility
  • Positions: Are namespace-scoped, ensuring that spatial queries operate within namespace boundaries
  • Metadata: Operates within namespace boundaries, ensuring that extended attributes remain isolated per organization
  • Embeddings: Are namespace-scoped, creating separate semantic search spaces for each organization
  • Rules & Triggers: Operate within namespace boundaries, ensuring that automation configurations are isolated per organization
  • Workflows: Operate within namespace boundaries, ensuring that processing configurations and statuses are isolated per organization
  • Status Tracking: Operates within namespace boundaries, ensuring that status information remains isolated per organization

This comprehensive namespace scoping ensures that multi-tenant isolation extends across all system capabilities, providing complete data separation while enabling shared infrastructure.