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.
upsertoverwrites 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
searchalone — a retrieval assistant that cannot alter the corpus — orupsertalone, for an ingest job. A missing grant isImForbiddenError: 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 sentA 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.countHits 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
| Call | result.output | Fields |
|---|---|---|
upsert | VectorUpsertOutput | .upserted, .status |
search | VectorSearchOutput | .hits (VectorSearchHit: .id, .score, .payload), .count |
delete | VectorDeleteOutput | .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
| Error | Means |
|---|---|
ImValidationError vector_dimension_mismatch | your vectors are not this service's width. Not retryable — the embedding model is wrong for this service |
ImValidationError validation_error | the SDK refused the call locally: an empty batch, a malformed point, an out-of-dialect filter, an unscoped or doubly-scoped delete |
ImValidationError vector_rejected | the database refused the request, most often for the same reason as a dimension mismatch |
ImForbiddenError | this action was not granted. Not retryable — ask an administrator |
ImResourceError vector_collection_missing | the collection is gone; an administrator needs to re-save the service |
ImResourceError vector_auth_failed | the service's key was refused |
ImTimeoutError | the 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 theembeddingresource'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