Create Namespace

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

str

required

A unique name for the namespace. Alphanumeric characters, hyphens, and underscores only.

str

required

The type of namespace: "text" or "vector".

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

Status	Cause
400	Invalid name, missing `vector_dimension` for vector type, or `vector_dimension` sent for text type
409	Namespace 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

Feature	Text Namespaces	Vector Namespaces
Primary use	Storing and searching text documents	Storing pre-computed vector embeddings
Embeddings	Generated on upload by your configured provider (Ollama, OpenAI, or Cohere)	Provided by you
Requirements	Embedding provider configured via `moorcheh configure`	Must specify `vector_dimension` at creation
Search	Text query → embedded → similarity search	Vector query → similarity search
Ideal for	FAQs, documentation, articles	Custom 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)

Getting Started

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

namespaces.create

Parameters

Examples

Error Handling

Namespace Types

Best Practices

​namespaces.create

​Parameters

​Examples

​Error Handling

​Namespace Types

​Best Practices

​Related Operations

namespaces.create

Parameters

Examples

Error Handling

Namespace Types

Best Practices

Related Operations