Skip to main content

​
namespaces.create

Creates a new namespace for storing text documents or precomputed vector embeddings on your on-prem Moorcheh instance. 
client.namespaces.create(
    namespace_name: str,
    *,
    type: Literal["text", "vector"],
    vector_dimension: int | None = None,
) -> dict[str, Any]
The * in the signature means everything after it is keyword-only. You must pass type and vector_dimension by name — for example type="text" — not as extra positional arguments.
API: POST /namespaces — see Create namespace

​
Parameters

​
namespace_name
str
required
A unique name for the namespace. Alphanumeric characters, hyphens, and underscores only.
​
type
str
required
The type of namespace: "text" or "vector".
​
vector_dimension
Optional[int]
The dimension of vectors. Required when type is "vector". Must be greater than 0. Do not pass for text namespaces.
Returns: dict[str, Any] — confirmation with status, message, namespace_name, type, and vector_dimension. Raises: MoorchehApiError — HTTP 400 for invalid input, 409 when the namespace already exists.

​
Examples

Create Text Namespace
from moorcheh import MoorchehClient

with MoorchehClient("http://localhost:8080") as client:
    # Moorcheh embeds documents on upload (Ollama, OpenAI, or Cohere)
    result = client.namespaces.create(
        "my-faq-documents",
        type="text",
    )
    print(f"Created namespace: {result}")
Create Vector Namespace
from moorcheh import MoorchehClient

with MoorchehClient("http://localhost:8080") as client:
    # You supply precomputed vectors; length must match vector_dimension
    result = client.namespaces.create(
        "my-image-embeddings",
        type="vector",
        vector_dimension=768,
    )
    print(f"Created namespace: {result}")

​
Error Handling

On-prem uses a single exception type. Check e.status_code and e.body for details.
Error Handling Example
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    try:
        result = client.namespaces.create("my-documents", type="text")
        print(f"Created namespace: {result}")
    except MoorchehApiError as e:
        if e.status_code == 409:
            print("Namespace already exists")
        elif e.status_code == 400:
            print(f"Invalid input: {e.body}")
        else:
            raise
StatusCause
400Invalid name, missing vector_dimension for vector type, or vector_dimension sent for text type
409Namespace already exists
Example return value (text)
{
  "status": "success",
  "message": "Namespace 'my-documents' created successfully.",
  "namespace_name": "my-documents",
  "type": "text",
  "vector_dimension": None,
}

​
Namespace Types

FeatureText NamespacesVector Namespaces
Primary useStoring and searching text documentsStoring pre-computed vector embeddings
EmbeddingsGenerated on upload by your configured provider (Ollama, OpenAI, or Cohere)Provided by you
RequirementsEmbedding provider configured via moorcheh configureMust specify vector_dimension at creation
SearchText query → embedded → similarity searchVector query → similarity search
Ideal forFAQs, documentation, articlesCustom ML models, image embeddings

​
Best Practices

  • Use descriptive namespace names that indicate their purpose
  • Separate different content types into different namespaces
  • Plan your data layout before creating namespaces — type cannot be changed after creation
  • Prefer text namespaces for most workflows; use vector namespaces only when you supply your own embeddings
  • Match vector_dimension to your embedding model (for example 768 or 1536)