Upload Vectors

vectors.upload

Uploads one or more precomputed vectors to a vector namespace. Each vector length must match the namespace vector_dimension set at creation. Poll Upload Job Status with the returned job_id.

client.vectors.upload(
    namespace_name: str,
    *,
    vectors: list[dict],
) -> dict[str, Any]

The * means vectors is keyword-only. Extra fields on each vector (for example source) are stored as metadata for search filters.

API: POST /namespaces/{namespace_name}/vectors — see Upload vectors

Parameters

string

required

Target vector namespace.

array

required

Non-empty array of vector objects.

string

required

Item id, unique within this namespace.

array

required

Array of finite numbers. Length must equal the namespace vector_dimension.

any

Optional additional keys on each vector are saved as metadata (for example "source": "demo").

Examples

from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    try:
        resp = client.vectors.upload(
            "my-embeddings",
            vectors=[
                {
                    "id": "vec-1",
                    "vector": [0.1] * 768,
                    "source": "demo",
                },
            ],
        )
        job_id = resp["job_id"]
    except MoorchehApiError as e:
        if e.is_item_limit_exceeded:
            print(e.body)
        else:
            raise

Poll with vectors.upload_job_status.

Returns

string

"success" when the upload job was started.

string

Human-readable result description.

string

Id of the async upload job. Poll vectors.upload_job_status with this value.

string

Namespace the vectors are being uploaded to.

number

Number of vectors accepted into the upload job.

number

Current total item count on the instance. Present on 409 item limit errors in MoorchehApiError.body.

number

Global item cap for this instance. Present on 409 item limit errors.

number

Number of new item ids in the request that would exceed the cap. Present on 409 item limit errors.

Example return value

{
  "status": "success",
  "message": "Vectors upload started. Poll job status for progress.",
  "job_id": "job-d044a3bf6c0e4380bf6ad7e9df7999d0",
  "namespace_name": "my-embeddings",
  "total": 1,
}

Error Handling

Non-2xx responses raise MoorchehApiError. Use e.is_item_limit_exceeded for 409 quota errors.

from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        client.vectors.upload("my-embeddings", vectors=[...])
except MoorchehApiError as e:
    print(e.status_code, e.body)

Status	Cause
400	Empty `vectors`, missing `id`/`vector`, non-finite values, dimension mismatch, or wrong namespace type
404	Namespace not found
409	Global item limit would be exceeded (job not started)

At most 100,000 items total across all namespaces
409 is returned before the job starts if new ids would exceed the cap
Re-uploading an existing id in the same namespace updates the item and does not consume extra quota
Vector values must be finite (no NaN or Infinity)

Getting Started

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

vectors.upload

Parameters

Examples

Returns

Error Handling

​vectors.upload

​Parameters

​Examples

​Returns

​Error Handling

​Related Operations

vectors.upload

Parameters

Examples

Returns

Error Handling

Related Operations