Documents and Ingestion
Examples by language for document registration, the ingestion pipeline, image understanding, Yuque data source synchronization, and full rebuild; for concepts, parameters, and boundary rules see knowledge base.
Examples by language
Ingest a document (register → ingest → poll)
createDocument registers the source file, createIngestion asynchronously enqueues it and returns HTTP 202 (meaning the task was accepted, not that it is immediately retrievable). Poll getIngestion until ready, and after confirming that the Document's status=ready, activeGeneration, and this ingestion's generation are consistent, retrieve by the new generation; ingestion 409 means a task for the same document is already in progress. The Web surface has no ingestion capability.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
const doc = await kb.createDocument({ knowledgeBaseId: base.$id, fileId: '<storageFileId>' });
// Batch registration: kb.createDocumentsBatch (up to 50 files per batch)
await kb.createIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id }); // Asynchronously enqueued, may carry an idempotency key
// Polling: state machine queued → running → ready | failed | cancelled
const ing = await kb.getIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id, ingestionId: '<ingestionId>' });var doc = kb.createDocument(base.getId(), "<storageFileId>",
null, null, null, null, null, null, null, null); // bucketId / name / documentTag / source / externalItemId / parserId / parserConfig / metadata
kb.createIngestion(base.getId(), doc.getId(), null, null, null, null); // Asynchronous enqueue (idempotency key / retryOf / overrides optional)
// Poll: kb.getIngestion(base.getId(), doc.getId(), "<ingestionId>"), state machine queued → running → ready | failed | cancelleddoc = kb.create_document(knowledge_base_id=base['$id'], file_id='<storageFileId>')
# Batch registration: kb.create_documents_batch (up to 50 files per batch)
kb.create_ingestion(knowledge_base_id=base['$id'], document_id=doc['$id']) # Asynchronously enqueued, may carry an idempotency key
# Polling: state machine queued → running → ready | failed | cancelled
kb.get_ingestion(knowledge_base_id=base['$id'], document_id=doc['$id'], ingestion_id='<ingestionId>')doc, err := kb.CreateDocument(base.Id, "<storageFileId>") // fileId is a positional parameter; the rest use WithCreateDocument* options
_, err = kb.CreateIngestion(base.Id, doc.Id,
kb.WithCreateIngestionIdempotencyKey("<idem-key>")) // Asynchronous enqueue
// Polling: state machine queued → running → ready | failed | cancelled
_, err = kb.GetIngestion(base.Id, doc.Id, "<ingestionId>")curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<storageFileId>"}'
# Ingestion: POST /knowledgebases/{kbId}/documents/{documentId}/ingestions (optional idempotency key idempotencyKey)
# Polling: GET .../ingestions/{ingestionId}; Reprocess: POST .../documents/{documentId}/process
# Batch registration (up to 50 files per batch): POST /knowledgebases/{kbId}/documents/batchImage understanding (optional)
Configured in parserConfig.imageUnderstanding, this is an independent step after parsing: it generates descriptions for informative images and adds them to the retrieval text, without modifying the original chunk's content / span / locator; when enabled=true, model and providerRef are required. Passing null or omitting maxImagesPerDocument means no limit on the number of image-understanding runs. The Web surface has no such capability.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
await kb.createDocument({
knowledgeBaseId: base.$id,
fileId: '<storageFileId>',
parserConfig: {
imageUnderstanding: {
enabled: true,
model: '<visionModelId>', // Project vision model ID
providerRef: 'project:<providerId>', // Project Provider reference
prompt: '用中文概括图片中的关键信息', // ≤4000 characters; use the built-in prompt when empty
maxImagesPerDocument: 20, // 1–20, default 20
maxDescriptionChars: 800, // 1–800, default 800
maxConcurrency: 4 // 1–8, default 4
}
}
});import io.agentbase.models.KnowledgeBaseImageUnderstandingConfig;
import io.agentbase.models.KnowledgeBaseParserConfig;
// parserConfig is a strongly typed model (no Map form exposed on the Java side):
var config = new KnowledgeBaseParserConfig()
.setImageUnderstanding(new KnowledgeBaseImageUnderstandingConfig()
.setEnabled(true)
.setModel("<visionModelId>") // Project vision model ID (when enabled=true, model and providerRef are required)
.setProviderRef("project:<providerId>") // Project Provider reference
.setPrompt("用中文概括图片中的关键信息") // ≤4000 characters; use the built-in prompt when empty
.setMaxImagesPerDocument(20L) // 1–20, default 20
.setMaxDescriptionChars(800L) // 1–800, default 800
.setMaxConcurrency(4L)); // 1–8, default 4
kb.createDocument(base.getId(), "<storageFileId>",
null, null, null, null, null, null, config, null); // bucketId / name / documentTag / source / externalItemId / parserId are nullkb.create_document(
knowledge_base_id=base['$id'],
file_id='<storageFileId>',
parser_config={
'imageUnderstanding': {
'enabled': True,
'model': '<visionModelId>', # Project vision model ID (when enabled=true, model and providerRef are required)
'providerRef': 'project:<providerId>', # Project Provider reference
'prompt': '用中文概括图片中的关键信息', # ≤4000 characters; use the built-in prompt when empty
'maxImagesPerDocument': 20, # 1–20, default 20
'maxDescriptionChars': 800, # 1–800, default 800
'maxConcurrency': 4 # 1–8, default 4
}
}) # keys match the REST request body (camelCase passed through)import "agentbase-go-sdk/models"
_, err := kb.CreateDocument(base.Id, "<storageFileId>",
kb.WithCreateDocumentParserConfig(models.KnowledgeBaseParserConfig{
ImageUnderstanding: models.KnowledgeBaseImageUnderstandingConfig{
Enabled: true,
Model: "<visionModelId>", // Project vision model ID (when enabled=true, model and providerRef are required)
ProviderRef: "project:<providerId>", // Project Provider reference
Prompt: "用中文概括图片中的关键信息", // ≤4000 characters; use the built-in prompt when empty
MaxImagesPerDocument: 20, // 1–20, default 20; omit to disable the limit
MaxDescriptionChars: 800, // 1–800, default 800
MaxConcurrency: 4, // 1–8, default 4
}}))curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<storageFileId>","parserConfig":{"imageUnderstanding":{"enabled":true,"model":"<visionModelId>","providerRef":"project:<providerId>","prompt":"用中文概括图片中的关键信息"}}}'
# Description generation runs with the ingestion pipeline and completes along with the document's ingestion statusExcel worksheet parsing (2.7.0)
parserId adds sheet: applies only to Excel .xls / .xlsx, generates one complete chunk for each non-empty worksheet, and saves sheetName / sheetIndex / sheetPages. Excel documents directly support faq or sheet, and smart is automatically parsed as sheet at ingestion; general / title / regex return 400 for Excel ingestion. documentParser can still be stacked: text preserves cell structured text, while vlm / mineru render each target sheet separately into a temporary PDF (suited to charts and images). Empty-output sheets are not ingested; there are hard limits on sheet count per workbook, decompression volume, compression ratio, cell rectangles, and rendering input. The Web surface has no such capability, and this card has no Web tab.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
import { ParserId, KnowledgeBaseDocumentParser } from 'agentbase-node-sdk';
// Both database-level defaults and document-level overrides can use sheet; when the document-level parserConfig is non-empty it fully replaces the knowledge base default
await kb.createDocument({
knowledgeBaseId: base.$id,
fileId: '<xlsxFileId>',
parserId: ParserId.Sheet,
parserConfig: { documentParser: KnowledgeBaseDocumentParser.Text }, // Extract structured text sheet by sheet
});
// Chart-heavy workbooks: use Vlm / Mineru for documentParser (each target Sheet is rendered as a temporary PDF)import io.agentbase.enums.ParserId;
import io.agentbase.models.KnowledgeBaseParserConfig;
import io.agentbase.enums.KnowledgeBaseDocumentParser;
kb.createDocument(base.getId(), "<xlsxFileId>",
null, null, null, null, null, // bucketId / name / documentTag / source / externalItemId
ParserId.SHEET,
new KnowledgeBaseParserConfig().setDocumentParser(KnowledgeBaseDocumentParser.TEXT),
null); // metadatafrom agentbase.enums.parser_id import ParserId
kb.create_document(
knowledge_base_id=base['$id'],
file_id='<xlsxFileId>',
parser_id=ParserId.SHEET,
parser_config={'documentParser': 'text'}) # Extract structured text per Sheet; for chart-heavy sheets use vlm / mineruimport "agentbase-go-sdk/models"
_, err := kb.CreateDocument(base.Id, "<xlsxFileId>",
kb.WithCreateDocumentParserId("sheet"),
kb.WithCreateDocumentParserConfig(models.KnowledgeBaseParserConfig{DocumentParser: "text"}))
// Chart-heavy workbooks: use "vlm" / "mineru" for DocumentParser (each target Sheet is rendered as a temporary PDF)curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<xlsxFileId>","parserId":"sheet","parserConfig":{"documentParser":"text"}}'
# Excel inherits/specifies general, title, regex, which return 400 at ingestion; smart is automatically resolved to a sheetBatch delete documents (2.8.0)
knowledgeBases.deleteDocuments({ knowledgeBaseId, documentIds, versionId }) (versionId optional) deletes multiple documents in a single request, at most 50 per batch; success returns 204. The request first runs a precheck: all IDs must belong to the library (when versionId is passed, they must belong to that writable DRAFT version); if the precheck fails, nothing is deleted. Deletion executes in request order; if an external storage or concurrency failure occurs mid-way, re-fetch the list and retry only the IDs that still exist. Requires the knowledgebases.write scope. After versioned activation, the write path must carry versionId.
- Node.js (Server)
- REST (curl)
await kb.deleteDocuments({
knowledgeBaseId: base.$id,
documentIds: ['doc_001', 'doc_002'] // At most 50 per batch
});curl -sS -X DELETE "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"documentIds":["doc_001","doc_002"]}' # Array holds at most 50 items; may include versionId
# 204 No Content; if the precheck fails, no documents are deletedIndex output language and embedding input limit (2.7.0)
Output language: when creating or updating a library, use
indexingDefaultsto save the Chat LLM configuration shared by GraphRAG / RAPTOR / Wiki; in each capability'supdateIndexCapabilityconfiguration,config.languagecontrols the generation output language —auto(default, detected from source content) /zh/en/ja; an explicit value overrides detection. For call examples see wiki.md "Capability configuration and build".Embedding input limit: the LLM Gateway Provider's
maxInputTokensbecomes the effective embedding input limit for Wiki projection — the indexer only truncates the embedding projection and packs batches according to the limit, without modifying canonical Wiki content;nullmeans no limit.
Personal Yuque authorization and team synchronization
Personal Yuque authorization and import require the current Console user identity; a project API key or an ordinary application user session cannot substitute for it. The environment must have Yuque authorization configured. Only specific enterprise Yuque domains are supported; ask the environment administrator which are available.
This example uses the Console Python SDK. Use a short-lived JWT issued by a still-valid Console session for a user with knowledge base write permission on the target project. Set the target project, admin mode, and that JWT on the client without attaching another active Cookie. Complete first-time authorization in the browser when prompted; the session, project, knowledge base, and user must remain the same. Set the actual draft ID when versioning is enabled, or an empty string otherwise.
- Python
from getpass import getpass
from agentbase_console.client import Client
from agentbase_console.services.knowledge_bases import KnowledgeBases
client = (Client().set_endpoint('<ENDPOINT>/v1').set_project('<PROJECT_ID>')
.set_mode('admin').set_jwt(getpass('Console user JWT: ')))
kb = KnowledgeBases(client)
knowledge_base_id = '<KNOWLEDGE_BASE_ID>'
draft_version_id = '<DRAFT_VERSION_ID>'
authorization = kb.create_yuque_o_auth_session(knowledge_base_id=knowledge_base_id)
if not authorization['authorized']:
print(authorization['authorizeUrl'])
input('Complete authorization in your browser, then press Enter: ')
session = kb.get_yuque_o_auth_session(
knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'])
if not session['authorized']:
raise RuntimeError('Yuque authorization is not complete')
result = kb.create_yuque_documents(
knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'],
urls=['<SUPPORTED_YUQUE_DOCUMENT_URL>'], version_id=draft_version_id or None)
for item in result.results:
print(item.url, item.status, item.error or '')
if result.failed:
raise RuntimeError(f'{int(result.failed)} document(s) failed to import')Team data source synchronization
The following uses an existing team source and server-side client kb with knowledgebases.write. Replace the knowledge base, data source, and draft IDs with actual values. When versioning is disabled, set draftVersionId to an empty string or omit versionId from the REST request.
- Node.js (Server)
- REST (curl)
const knowledgeBaseId = '<knowledgeBaseId>';
const dataSourceId = '<dataSourceId>';
const draftVersionId = '<DRAFT_VERSION_ID>';
const sync = await kb.createDataSourceSync({
knowledgeBaseId,
dataSourceId,
...(draftVersionId ? { versionId: draftVersionId } : {})
});printf 'header = "X-Appwrite-Key: %s"\n' "$APPBASE_API_KEY" | \
curl --config - -X POST "$APPBASE_ENDPOINT/knowledgebases/<knowledgeBaseId>/datasources/<dataSourceId>/syncs" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -d '{"versionId":"<DRAFT_VERSION_ID>"}'Full rebuild
Changing library-level parsing configuration does not rewrite historical chunks; to re-enqueue all ready documents for ingestion in bounded batches, use createReindex (returns 202, does not change embeddingModel), carrying the cursor to continue the next batch when nextCursor is non-null. The Web surface has no such capability.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
let res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50 });
while (res.nextCursor) { // Bounded batching: keep enqueueing until nextCursor is null
res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50, cursor: res.nextCursor });
}var res = kb.createReindex(base.getId(), 50L, null, null); // Positional parameters: limit / cursor / idempotencyKey
while (res.getNextCursor() != null) { // Bounded batching: keep enqueueing until nextCursor is null
res = kb.createReindex(base.getId(), 50L, res.getNextCursor(), null);
}
// 202 returns queued / skipped / failed / nextCursorres = kb.create_reindex(knowledge_base_id=base['$id'], limit=50)
while res['nextCursor']: # Bounded batching: keep enqueueing until nextCursor is null
res = kb.create_reindex(knowledge_base_id=base['$id'], limit=50, cursor=res['nextCursor'])res, err := kb.CreateReindex(base.Id, kb.WithCreateReindexLimit(50))
for res.NextCursor != "" { // Bounded batching: keep enqueueing until nextCursor is null
res, err = kb.CreateReindex(base.Id,
kb.WithCreateReindexLimit(50), kb.WithCreateReindexCursor(res.NextCursor))
}
// 202:queued / skipped / failed / nextCursorcurl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/reindex" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"limit":50,"idempotencyKey":"idem-reindex-01"}'
# 202: queued / skipped / failed / nextCursor; when nextCursor is non-null, pass it to continue calling