Keep Your Knowledge Base Current

Source content changes: docs get revised, pages get deleted, products get discontinued. If your vector index does not keep up, retrieval and chat can answer from stale chunks. Ragrails maintenance is chunk-level today. You update stored chunks with edit() and remove exact chunk IDs with delete(). Use the interface-specific docs when you need exact parameters, flags, request fields, or response shapes.

Task	Operation	What it does
Source text changed	`edit()`	Embeds replacement text and upserts it at the same ID.
Source was removed	`delete()`	Deletes exact stored IDs from the vector database.
Whole source refreshed	Re-ingest plus diff	Upsert new chunks, then delete old IDs that disappeared.

Maintenance depends on stable chunk IDs. Derive IDs from source identity and section location, then keep a manifest that maps each source to the chunk IDs currently stored for it.

Stable IDs

A stable ID lets a later run replace or delete the same stored vector.

{
  "source": "docs/refunds.md",
  "version": "2026-06-23",
  "chunk_ids": [
    "docs/refunds.md#refund-window",
    "docs/refunds.md#annual-plans"
  ]
}

Use IDs that survive normal edits. A file path plus heading slug is usually better than a random UUID. If a heading moves but still means the same thing, keep the ID.

Update changed chunks

edit() accepts unembedded replacement chunks. Ragrails embeds each replacement with input_type="document" and upserts it into the configured vector store.

from ragrails import RagRails

rag = RagRails(
    collection="docs",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
)

result = rag.edit(
    chunks=[
        {
            "id": "docs/refunds.md#refund-window",
            "text": "Refunds now take 3 to 5 business days.",
            "source": "docs/refunds.md",
            "metadata": {"title": "Refund window"},
        }
    ]
)

ragrails edit   --input-dir files/updated/   --vector-db qdrant   --collection docs   --url http://localhost:6333   --provider voyage   --model voyage-3

curl -X POST http://127.0.0.1:8000/v1/edit   -H "Content-Type: application/json"   -d '{
    "chunks": [
      {
        "id": "docs/refunds.md#refund-window",
        "text": "Refunds now take 3 to 5 business days.",
        "source": "docs/refunds.md",
        "metadata": {"title": "Refund window"}
      }
    ],
    "provider": "voyage",
    "model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "docs",
    "url": "http://localhost:6333"
  }'

Result:

{
  "requested": 1,
  "edited": 1,
  "items": [{"id": "docs/refunds.md#refund-window"}],
  "failed": 0,
  "provider": "qdrant",
  "collection": "docs",
  "errors": []
}

Key	Meaning
`requested`	Number of replacement chunks submitted.
`edited`	Number of chunks embedded and upserted successfully.
`items`	IDs that were replaced.
`failed`	Number of chunks that failed validation, embedding, or storage.
`provider`	Vector database provider used for the operation.
`collection`	Collection, index, or class that was updated.
`errors`	Structured validation, embedding, or vector-store errors.

Delete stale chunks

delete() removes exact IDs. It does not delete by metadata filter or by source path.

result = rag.delete(
    ids=[
        "docs/refunds.md#legacy-pricing",
        "docs/refunds.md#old-plan",
    ]
)

ragrails delete   --id docs/refunds.md#legacy-pricing   --id docs/refunds.md#old-plan   --vector-db qdrant   --collection docs   --url http://localhost:6333

curl -X POST http://127.0.0.1:8000/v1/delete   -H "Content-Type: application/json"   -d '{
    "ids": ["docs/refunds.md#legacy-pricing", "docs/refunds.md#old-plan"],
    "vector_db": "qdrant",
    "collection": "docs",
    "url": "http://localhost:6333"
  }'

Result:

{
  "requested": 2,
  "deleted": 2,
  "items": [
    {"id": "docs/refunds.md#legacy-pricing"},
    {"id": "docs/refunds.md#old-plan"}
  ],
  "failed": 0,
  "provider": "qdrant",
  "collection": "docs",
  "errors": []
}

Refresh one source

A full source refresh is a small reconciliation loop:

Load the old manifest entry for the source.
Parse, chunk, embed, and store the current source content.
Collect the new chunk IDs from the store result.
Delete old_ids - new_ids.
Save the new manifest entry.

old_ids = set(manifest["docs/refunds.md"]["chunk_ids"])

result = rag.ingest(
    docs="docs/refunds.md",
    chunking={"chunk_size": 800, "chunk_overlap": 120},
    storage={"collection": "docs"},
)

new_ids = {item["id"] for item in result.store_result.items}
stale_ids = sorted(old_ids - new_ids)

if stale_ids:
    rag.delete(ids=stale_ids)

manifest["docs/refunds.md"] = {
    "chunk_ids": sorted(new_ids),
    "version": "2026-06-23",
}

store() and edit() upsert by ID. If a refreshed source produces the same IDs, the new vectors replace the previous vectors.

Operational checklist

Check	Why it matters
Keep a source-to-IDs manifest	Ragrails deletes exact IDs, so your app needs to know which IDs belonged to a removed source.
Use one embedding model per collection	Edited chunks must stay in the same vector space as existing chunks.
Use one ID scheme across ingest and refresh	Random IDs create duplicates instead of replacements.
Delete stale IDs after refresh	Upserts do not remove chunks that disappeared from the source.
Test retrieval after maintenance	Verify changed content is retrieved and deleted content no longer appears.

Current boundaries

Boundary	Practical workaround
No document-level delete API	Track chunk IDs per document and call `delete(ids=...)`.
No metadata-filter delete API	Query your own manifest or source inventory, then delete exact IDs.
No automatic source diffing	Re-ingest the source and compare old/new chunk IDs in your application.
No automatic scheduling	Run refresh jobs from your own worker, cron, or CI system.

Possible errors

Most stage-level failures are returned in the result errors list instead of raising immediately. REST validation and setup failures may return an exception envelope instead. See Errors for the shared shapes.

{
  "requested": 1,
  "edited": 0,
  "items": [],
  "failed": 1,
  "provider": "qdrant",
  "collection": "docs",
  "errors": [
    {
      "source": "docs/refunds.md#refund-window",
      "source_kind": "stored_chunk",
      "stage": "validate",
      "error": "chunk text must be a non-empty string",
      "isRetryable": false,
      "attempts": 1
    }
  ]
}

{
  "requested": 1,
  "edited": 0,
  "items": [],
  "failed": 1,
  "provider": "qdrant",
  "collection": "docs",
  "errors": [
    {
      "source": "",
      "source_kind": "stored_chunk",
      "stage": "embed",
      "error": "embedding model returned a different number of vectors than input chunks",
      "isRetryable": true,
      "attempts": 1
    }
  ]
}

{
  "requested": 2,
  "deleted": 0,
  "items": [],
  "failed": 1,
  "provider": "qdrant",
  "collection": "docs",
  "errors": [
    {
      "source": "",
      "source_kind": "stored_chunk",
      "stage": "validate",
      "error": "ids[1] must be a non-empty string",
      "isRetryable": false,
      "attempts": 1
    }
  ]
}

Next steps

Use Storing for the initial store operation.
Use Pipeline Overview to place maintenance after ingestion and query workflows.
Use Retrieval to verify maintained content is searchable.

Get Started

Features

Capabilities

Use Cases

Walkthroughs

Keep Your Knowledge Base Current

Stable IDs

Update changed chunks

Delete stale chunks

Refresh one source

Operational checklist

Current boundaries

Possible errors

Next steps

​Stable IDs

​Update changed chunks

​Delete stale chunks

​Refresh one source

​Operational checklist

​Current boundaries

​Possible errors

​Next steps

Stable IDs

Update changed chunks

Delete stale chunks

Refresh one source

Operational checklist

Current boundaries

Possible errors

Next steps