Class: IngestionBatchSession

@kortexya/reasoninglayer / IngestionBatchSession

Class: IngestionBatchSession

Defined in: src/resources/ingestion-session.ts:517

Handle for a queued batch ingestion — the HTTP 202 answer of ingestDocumentBatch with sync: false, and of ingestMarkdownBatch on a deployment that runs a task queue.

Remarks

Every document of the batch is tracked under the one session. The documentIds are session-tracking ids, not document-registry ids.

Example

const session = await client.ingestion.ingestDocumentBatch(request, { sync: false });
console.log(`${session.documentCount} documents queued`);
const stats = await session.waitForCompletion();

Extends

IngestionSessionHandle

Properties

documentCount

readonly documentCount: number

Defined in: src/resources/ingestion-session.ts:519

Number of documents enqueued.

documentIds

readonly documentIds: readonly string[]

Defined in: src/resources/ingestion-session.ts:522

Session-tracking ids of the enqueued documents.

sessionId

readonly sessionId: string

Defined in: src/resources/ingestion-session.ts:201

The session ID (UUID).

Inherited from

IngestionSessionHandle.sessionId

status

readonly status: string

Defined in: src/resources/ingestion-session.ts:204

The status at enqueue time. The engine always sends "pending".

Inherited from

IngestionSessionHandle.status

statusUrl

readonly statusUrl: string

Defined in: src/resources/ingestion-session.ts:207

Path of the session resource (/api/v1/ingest/sessions/<sessionId>).

Inherited from

IngestionSessionHandle.statusUrl

Methods

getDocumentStats()

getDocumentStats(documentId, requestOptions?): Promise<DocumentStatsDto | null>

Defined in: src/resources/ingestion-session.ts:315

Get the stats of one document of the session.

Parameters

documentId

string

The document’s session-tracking id (the documentId the 202 answer, or DocumentStatsDto.documentId, names).

requestOptions?

RequestOptions

Per-call request options.

Returns

Promise<DocumentStatsDto | null>

The document’s stats once it completed, or null while it is still pending or in progress (HTTP 204).

Throws

404 if the session or the document does not exist, the document is an RDF import (its receipt is on IngestionSessionHandle.getSession), or it completed without recording stats.

Throws

409 if the document failed or was cancelled; the reason is documents[].error on IngestionSessionHandle.getSession.

Remarks

Maps to GET /api/v1/ingest/sessions/{session_id}/documents/{document_id}/stats. The engine publishes DocumentStatsDto as the 200 body; a 204 (still pending or in progress) reads as null. DocumentStatsDto.alreadyIngested tells a duplicate upload from a fresh ingestion.

Example

const stats = await session.getDocumentStats(documentId);
if (stats?.alreadyIngested) console.log(`already in the library as ${stats.documentTermId}`);

Inherited from

IngestionSessionHandle.getDocumentStats

getProgress()

getProgress(requestOptions?): Promise<SessionProgressResponse>

Defined in: src/resources/ingestion-session.ts:263

Get live pipeline progress for all documents in the session.

Parameters

requestOptions?

RequestOptions

Returns

Promise<SessionProgressResponse>

Progress snapshots for each document being processed.

Remarks

Maps to GET /api/v1/ingest/sessions/{session_id}/progress. Returns real-time counters, current pipeline step, and step log.

Inherited from

IngestionSessionHandle.getProgress

getSession()

getSession(requestOptions?): Promise<IngestionSessionDetailResponse>

Defined in: src/resources/ingestion-session.ts:246

Get the current session details: status, document counts, and every document with how its ingestion ended.

Parameters

requestOptions?

RequestOptions

Per-call request options.

Returns

Promise<IngestionSessionDetailResponse>

The session, with documents[]: each document’s status, its failure reason (error) and, once complete, its receipt.

Throws

404 if the session does not exist.

Throws

If the request fails.

Remarks

Maps to GET /api/v1/ingest/sessions/{session_id}. A receipt is tagged by kind: markdown carries the document stats, rdf the RDF import counts (an RDF document has no other stats route).

Example

const session = await handle.getSession();
for (const doc of session.documents) {
  if (doc.receipt?.kind === 'rdf') console.log(`${doc.receipt.sortsCreated} sorts`);
}

Inherited from

IngestionSessionHandle.getSession

getStats()

getStats(requestOptions?): Promise<SessionStatsResponse>

Defined in: src/resources/ingestion-session.ts:280

Get stats for all completed documents in the session.

Parameters

requestOptions?

RequestOptions

Returns

Promise<SessionStatsResponse>

Per-document stats (term IDs, sort names, token usage, etc.).

Remarks

Maps to GET /api/v1/ingest/sessions/{session_id}/stats. May be empty if no documents have completed yet.

Inherited from

IngestionSessionHandle.getStats

waitForCompletion()

waitForCompletion(options?): Promise<SessionStatsResponse>

Defined in: src/resources/ingestion-session.ts:351

Poll the session until it completes or fails, then return final stats.

Parameters

options?

IngestionPollOptions

Polling configuration (interval, timeout, progress callback, abort signal).

Returns

Promise<SessionStatsResponse>

Final session stats once all documents are complete. These are the markdown pipeline’s stats: an RDF document has none, so for an ingestRdf session use IngestionSessionHandle.waitForSession, whose documents carry the RDF receipt.

Throws

IngestionFailedError If the session status becomes "failed".

Throws

TimeoutError If timeoutMs is exceeded.

Throws

ReasoningLayerError If the abort signal is triggered.

Example

const stats = await session.waitForCompletion({
  pollIntervalMs: 2000,
  timeoutMs: 300_000,
  onProgress: (p) => {
    const doc = p.documents[0];
    if (doc) console.log(`${doc.currentStepLabel} — chunk ${doc.chunksProcessed}/${doc.totalChunks}`);
  },
});
console.log(`Created ${stats.documents[0]?.termIds.length} terms`);

Remarks

Polls getSession() to check status, and calls onProgress with live progress data between checks. Terminal states are "complete" and "failed".

Inherited from

IngestionSessionHandle.waitForCompletion

waitForSession()

waitForSession(options?): Promise<IngestionSessionDetailResponse>

Defined in: src/resources/ingestion-session.ts:382

Poll the session until it completes or fails, then return the session with every document’s receipt.

Parameters

options?

IngestionPollOptions

Polling configuration (interval, timeout, progress callback, abort signal).

Returns

Promise<IngestionSessionDetailResponse>

The completed session. Each document carries its receipt: kind: 'markdown' with the document stats, or kind: 'rdf' with the RDF import counts.

Throws

IngestionFailedError If the session status becomes "failed"; its session.documents[].error names each reason.

Throws

TimeoutError If timeoutMs is exceeded.

Throws

ReasoningLayerError If the abort signal is triggered.

Remarks

Polls getSession() the same way IngestionSessionHandle.waitForCompletion does, and returns its last answer instead of fetching the markdown stats. Use it for an ingestRdf session queued with sync: false.

Example

const handle = await client.ingestion.ingestRdf(request, { sync: false });
const session = await handle.waitForSession();
const receipt = session.documents[0]?.receipt;
if (receipt?.kind === 'rdf') console.log(`${receipt.termsCreated} terms`);

Inherited from

IngestionSessionHandle.waitForSession