Vector store & RAG

document_parse splits a document, embedding turns the chunks into vectors, and core.vector is where those vectors live and get searched. Nothing here assumes how a vector was produced: your agent parses and embeds with the resources that do those jobs, then hands finished vectors over.

from im_sdk import ImCore, im_agent
 
 
@im_agent("handbuch-rag")
async def main(core: ImCore, data: dict) -> str:
    # 1 — chunk a document the user uploaded
    elements = (
        await core.document_parse.partition(
            "unstructured", file_ref=data["file"], chunking_strategy="by_title"
        )
    ).output.elements
    texts = [e.text for e in elements if e.text]
 
    # 2 — embed the chunks
    vectors = (await core.embedding.embed(texts, alias="text-embed")).output.vectors
 
    # 3 — store them, with the metadata you want to cite later
    await core.vector.upsert(
        "handbuch",
        points=[
            {"id": i, "vector": v, "payload": {"source": "handbuch.pdf", "chunk": i}}
            for i, v in enumerate(vectors)
        ],
    )
 
    # 4 — answer a question out of the store
    query = (await core.embedding.embed(data["question"], alias="text-embed")).output.vectors[0]
    hits = (await core.vector.search("handbuch", vector=query, top_k=5)).output.hits
 
    return "\n".join(f"{h.score:.3f} {h.payload['source']}#{h.payload['chunk']}" for h in hits)

Four things to know first

  • You name a service, not a collection. Each connected vector service owns exactly one collection, created when an administrator saves the service, and the gateway confines every call to it. Two services can share a cluster and be granted to different agents; neither can reach the other's vectors, and no argument you pass changes that.
  • The dimension is the administrator's setting. It is fixed when the service is connected, because a collection cannot be resized. Vectors of another width are refused with both numbers in the message — which almost always means the embedding model you used is not the one the service was created for.
  • upsert overwrites by id. Re-using an id replaces that point. That is what makes re-ingesting a document idempotent instead of duplicating it.
  • Each of the three operations is granted separately. An agent can hold search alone — a retrieval assistant that cannot alter the corpus — or upsert alone, for an ingest job. A missing grant is ImForbiddenError: a policy decision, not a retryable failure.

Storing points — core.vector.upsert

result = await core.vector.upsert("handbuch", points=[
    {"id": 0, "vector": [0.1, 0.2, ...], "payload": {"source": "handbuch.pdf", "page": 3}},
    {"id": "9f1c…", "vector": [...]},                      # payload is optional
])
result.output.upserted        # how many points were sent

A point is {"id": …, "vector": [...], "payload": {...}}. The id is an unsigned integer or a UUID string — Qdrant's own contract, kept as a union so integer ids need no stringifying.

Put in the payload whatever you want to cite or scope by. It comes back with every search hit and it is what filters match on, so a citation's source, page and chunk index belong there.

At most 1000 points per call, and an oversized batch is refused rather than partly written. Chunk your ingest loop accordingly.

Searching — core.vector.search

result = await core.vector.search(
    "handbuch",
    vector=query_vector,
    top_k=5,                                                # default 10, ceiling 250
    filter={"must": [{"key": "source", "match": "handbuch.pdf"}]},
    with_payload=True,                                      # default true
)
for hit in result.output.hits:
    hit.id, hit.score, hit.payload
result.output.count

Hits come back best-first. result.text is empty for every vector call — ids, scores and metadata have no meaningful single-string projection, so read result.output.

Filters are a small, deliberately vendor-neutral dialect

A list of must conditions, each an exact match on one payload key, AND-ed together. The match value is a scalar (string, number, boolean).

filter={"must": [
    {"key": "source", "match": "handbuch.pdf"},
    {"key": "lang", "match": "de"},
]}

Qdrant's own filter language is far richer — should, must_not, ranges, geo, nested keys — and none of it is exposed. vector is the resource type and Qdrant only its first driver: anything accepted here is something every later backend has to reproduce exactly, and field equality is the one construct every vector store has. An agent written against this dialect keeps working when an organization moves to a different backend.

Anything outside the subset is refused, not ignored — locally, before the call leaves your process. A silently-dropped should returns more rows than you asked for on a search, and on a delete removes far more than you named.

Deleting, and re-ingesting a document

delete takes ids or filter — exactly one, never neither and never both:

# by id
await core.vector.delete("handbuch", ids=[0, 1, 2])
 
# by filter — how a re-ingest replaces a document whose chunk ids it forgot
await core.vector.delete("handbuch", filter={
    "must": [{"key": "source", "match": "handbuch.pdf"}],
})
await core.vector.upsert("handbuch", points=new_chunks)

Both refusals raise ImValidationError in your process, exactly as data.delete refuses its own unscoped delete. Qdrant would read an unqualified delete as "no points", but the same request against a future backend could mean "all of them" — and an agent that meant to send a filter and sent an empty one must not silently succeed at nothing either.

output.deleted counts the ids you passed. For a filter-delete it is None: the database does not report how many points matched, and a guessed number would be worse than an honest "not known". The point count in the Portal's Connected Services list answers "how much is in there now" — it is measured, not accumulated from call deltas.

At most 1000 ids per call.

Output variants

Callresult.outputFields
upsertVectorUpsertOutput.upserted, .status
searchVectorSearchOutput.hits (VectorSearchHit: .id, .score, .payload), .count
deleteVectorDeleteOutput.deleted (None for a filter-delete), .status

All of them, plus VectorPoint and PayloadFilter, are importable from the package root: from im_sdk import VectorSearchOutput.

Errors worth handling

ErrorMeans
ImValidationError vector_dimension_mismatchyour vectors are not this service's width. Not retryable — the embedding model is wrong for this service
ImValidationError validation_errorthe SDK refused the call locally: an empty batch, a malformed point, an out-of-dialect filter, an unscoped or doubly-scoped delete
ImValidationError vector_rejectedthe database refused the request, most often for the same reason as a dimension mismatch
ImForbiddenErrorthis action was not granted. Not retryable — ask an administrator
ImResourceError vector_collection_missingthe collection is gone; an administrator needs to re-save the service
ImResourceError vector_auth_failedthe service's key was refused
ImTimeoutErrorthe database did not answer in time

Nothing in any of them names the collection, because a collection's name is a connected service's uuid.

Traces are summarized, always

Query vectors, point payloads, filter values and point ids are kept out of trace exports with no opt-in. What travels is the shape: vector width, point and hit counts, payload key names, filter keys, and the score range. The organization-level log_data_payloads switch — which lets data export rows verbatim — does not extend to vector: consenting to database rows is not consenting to a document corpus.

What is deliberately not here

  • No ingest_file() helper. Parsing, chunking and embedding are separate resources with their own grants and their own costs; folding them in would hide both. Agents orchestrate the pipeline — that is the code at the top of this page.
  • No search_text(). Embedding the query is the embedding resource's job, and which model does it is a decision your agent has to make anyway.
  • No hybrid or sparse search, no named or multi-vectors. One unnamed dense vector per point.
  • No hard point quota, and no collection-management calls: an agent cannot create, rename or drop a collection.

See also

  • Capabilities — the method signatures alongside every other resource
  • Files & storage — where the document being ingested usually comes from, and the durable store for what you produce