Skip to main content

​
documents.get

Fetch stored items by id within a namespace. Item ids are unique per namespace, not globally. Missing ids are omitted from items without failing the request. 
client.documents.get(
    namespace_name: str,
    *,
    ids: list[str],
) -> dict[str, Any]
  • Text namespaces return id, text, and metadata
  • Vector namespaces return id and metadata only (vectors are not returned)
API: POST /namespaces/{namespace_name}/items/get — see Get items

​
Parameters

​
namespace_name
string
required
Namespace to read from.
​
ids
array
required
Non-empty array of item id strings. Maximum 100 ids per request.

​
Examples

from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    # Text namespace
    result = client.documents.get(
        "my-documents",
        ids=["doc-1", "doc-2"],
    )

    for item in result["items"]:
        print(item["id"], item.get("text"), item["metadata"])

    # Vector namespace (no text or vector in response)
    result = client.documents.get(
        "my-embeddings",
        ids=["vec-1"],
    )

    for item in result["items"]:
        print(item["id"], item["metadata"])

​
Returns

​
status
string
"success" when the lookup completed.
​
message
string
Human-readable result description.
​
requested_ids
number
Number of ids sent in the request.
​
found_items
number
Number of items returned in items. May be less than requested_ids if some ids were not found.
​
items
array
Array of found items. Empty when none of the requested ids exist.
​
items[].id
string
Item id.
​
items[].text
string
Stored document text. Present for text namespace items only.
​
items[].metadata
object
Metadata stored with the item (custom fields from upload).
Example return value (text namespace)
{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'my-documents'.",
  "requested_ids": 2,
  "found_items": 1,
  "items": [
    {
      "id": "doc-1",
      "metadata": {"team": "ai"},
      "text": "Moorcheh on-prem retrieval test",
    },
  ],
}
Example return value (vector namespace)
{
  "status": "success",
  "message": "Successfully retrieved 1 items from namespace 'my-embeddings'.",
  "requested_ids": 1,
  "found_items": 1,
  "items": [
    {
      "id": "vec-1",
      "metadata": {"source": "demo"},
    },
  ],
}

​
Error Handling

Non-2xx responses raise MoorchehApiError. A successful lookup with missing ids does not raise — check found_items vs requested_ids. 
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        result = client.documents.get("my-documents", ids=["doc-1"])
except MoorchehApiError as e:
    print(e.status_code, e.body)
StatusCause
400Empty ids, more than 100 ids, or empty id string
404Namespace not found
  • Maximum 100 ids per request — use multiple requests for larger batches
  • Missing ids are skipped; check found_items vs requested_ids
  • Vector embeddings are not included in the response