Skip to main content

​
documents.delete / vectors.delete

Deletes specific documents or vectors from a namespace by their IDs. Use documents.delete for text data and vectors.delete for vector data.
This operation permanently deletes data and cannot be undone. Deleted items will decrement your total item count.

​
Parameters

​
namespace_name
str
required
The name of the target namespace.
​
ids
List[Union[str, int]]
required
A list of document/vector IDs to delete (max 1000 items per request).
Returns: Dict[str, Any] - A dictionary confirming the deletion status. Raises: NamespaceNotFound, InvalidInputError.

​
Examples

Delete Documents Example
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    # Delete specific documents by ID
    result = client.documents.delete(
        namespace_name="my-faq-documents",
        ids=["faq-1", "faq-3", "faq-5"]
    )
    print(f"Deletion result: {result}")
Delete Vectors Example
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    # Delete specific vectors by ID
    result = client.vectors.delete(
        namespace_name="my-image-embeddings",
        ids=["image_001.jpg", "image_002.jpg"]
    )
    print(f"Deletion result: {result}")

​
Response Structure

The response contains:
  • status (str): “success” or “partial”
  • message (str): Human-readable confirmation message
  • requested_deletions (int): Number of items requested to be deleted
  • actual_deletions (int): Number of items actually deleted
  • remaining_items (int): Total number of items remaining in namespace
  • unprocessed_ids (list, optional): IDs that failed to be deleted (for partial success)

​
Complete Example

Complete Deletion Example
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    namespace = "my-documents"
    
    # Delete multiple documents
    ids_to_delete = ["doc-1", "doc-2", "doc-3", "doc-4", "doc-5"]
    
    result = client.documents.delete(
        namespace_name=namespace,
        ids=ids_to_delete
    )
    
    print(f"Requested deletions: {result.get('requested_deletions', 0)}")
    print(f"Actual deletions: {result.get('actual_deletions', 0)}")
    print(f"Remaining items: {result.get('remaining_items', 0)}")
    
    # Handle partial success
    if result.get('status') == 'partial':
        unprocessed = result.get('unprocessed_ids', [])
        if unprocessed:
            print(f"Failed to delete: {unprocessed}")

​
Important Notes

  • Maximum of 1,000 IDs can be deleted in a single request
  • IDs can be strings or numbers - they’ll be converted to strings internally
  • This operation permanently deletes data and cannot be undone
  • Successfully deleted items will decrement your total item count
  • Use documents.delete for text data, vectors.delete for vector data
  • Namespace must exist and belong to your account

​
Understanding Responses

  • 200 Response: No items failed to process (no unprocessed items)
  • 207 Response: Some items were successfully deleted while others failed
  • Check actual_deletions vs requested_deletions to see if items were found
  • If actual_deletions is 0, the requested IDs may not exist in the namespace
  • The remaining_items count reflects the current namespace size

​
Best Practices

  • Verify document IDs before deletion
  • Delete in batches for large operations
  • Check the response to confirm successful deletions
  • Implement proper error handling for partial failures
  • Consider backing up important data before deletion

​
Use Cases

  • Data Cleanup: Remove outdated or temporary documents/vectors
  • Content Management: Delete specific items by ID
  • Privacy Compliance: Remove specific user data
  • Storage Management: Free up space by removing unused content
  • Testing: Clean specific test data between runs