> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Text Data

> Upload text documents to a namespace using the Python SDK

## documents.upload

Uploads text documents to a text namespace. Moorcheh will process and embed these asynchronously.

### Parameters

<ParamField query="namespace_name" type="str" required>
  The name of the target text namespace.
</ParamField>

<ParamField query="documents" type="List[Dict]" required>
  A list of dictionaries. Each dict requires an id and text key.
</ParamField>

**Returns:** `Dict[str, Any]` - A dictionary confirming the documents were queued.

**Raises:** `NamespaceNotFound`, `InvalidInputError`.

### Example

```python Upload Documents Example theme={null}
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    documents_to_upload = [
        {
            "id": "faq-1",
            "text": "To reset your password, go to the account settings page.",
            "category": "account"
        },
        {
            "id": "faq-2",
            "text": "Our return policy allows returns within 30 days of purchase.",
            "category": "shipping"
        }
    ]

    status = client.documents.upload(
        namespace_name="my-faq-documents",
        documents=documents_to_upload
    )
    print(status)
```

### Document Structure

Each document in the `documents` array is a flat object with these properties:

* **id** (required): Unique identifier for the document (string or number)
* **text** (required): The main text content of the document
* **Additional fields**: Any other fields are treated as metadata

```python Well-Structured Documents theme={null}
documents = [
    {
        "id": "article-123",
        "text": "Full article content here...",
        # Metadata fields - all other kwargs are considered as metadata
        "title": "Introduction to Machine Learning",
        "author": "Dr. Smith",
        "category": "education",
        "publish_date": "2024-01-15",
        "tags": ["ml", "ai", "tutorial"],
        "difficulty": "beginner"
    }
]
```

### Complete Example

```python Complete Data Management Workflow theme={null}
from moorcheh_sdk import MoorchehClient
import time

with MoorchehClient() as client:
    # 1. Create a namespace
    client.namespaces.create("my-data", type="text")

    # 2. Upload documents
    docs = [
        {
            "id": "doc-1",
            "text": "This is the first document",
            "category": "tutorial",
            "author": "John Doe"
        },
        {
            "id": "doc-2",
            "text": "This is the second document",
            "category": "guide",
            "author": "Jane Smith"
        }
    ]

    upload_result = client.documents.upload(namespace_name="my-data", documents=docs)
    print(f"Upload status: {upload_result}")

    # 3. Wait for processing (text documents need time to be embedded)
    print("Waiting for document processing...")
    time.sleep(5)
```

## Important Notes

<Note>
  **Asynchronous Processing**: Text documents are processed asynchronously. Allow a few seconds after upload before searching.
</Note>

<Warning>
  **ID Uniqueness**: Document IDs must be unique within their namespace. Uploading with an existing ID will overwrite the previous entry.
</Warning>

<Tip>
  **Batch Processing**: For large datasets, upload documents in batches of 100-1000 items for optimal performance.
</Tip>

## Best Practices

* Keep documents focused on a single topic
* Include meaningful titles and metadata
* Use consistent metadata schemas across documents
* Break large documents into logical chunks
* Upload in batches of 25-50 documents for optimal performance
* Use meaningful document IDs for easier management

## Document Limits

* **Text Length**: Min 10 characters, Max 50,000 characters per document
* **Batch Size**: Max 100 documents per request, Recommended 25-50
* **Metadata Size**: Max 2KB per document, Up to 50 metadata keys

## Related Operations

* [Get Documents](/python-sdk/data/get-documents) - Retrieve uploaded documents
* [Delete Data](/python-sdk/data/delete) - Remove specific documents
* [Search](/python-sdk/search/query) - Search uploaded documents