Documents - Kodexa Developer Portal

At the heart of Kodexa is the concept of a Document. A document represents the content, metadata and features associated with any type of information. Rather than storing the information as text, we store it in KDDB (Kodexa Document Database) format — a SQLite-based structure containing a hierarchical tree of content nodes, metadata, tags, features, and extracted data.

Document Structure

A Kodexa Document consists of these core components:

Content Node Tree: A hierarchical tree of nodes representing the document’s structure (pages, paragraphs, lines, words, tables, cells, etc.)
Metadata: Flexible key-value pairs for document-level information
Source Metadata: Information about the document’s origin (filename, MIME type, checksum)
Native Documents: Embedded binary files (the original PDF, images, etc.)
Data Objects & Attributes: Structured extracted data organized by Data Definition
Tags: Annotations on content nodes linking them to extracted data
Audit Trail: Change history tracking

Creating Documents

Documents can be created using the SDK in Python or TypeScript:

from kodexa_document import Document

# Create an empty document
doc = Document()

# Create from text content
doc = Document.from_text("Hello, World!")

# Load from a KDDB file
doc = Document.from_kddb("my-document.kddb")

# Load from JSON
doc = Document.from_json(json_string)

import { Kodexa } from '@kodexa/document';

await Kodexa.init();

// Create an empty document
const doc = await Kodexa.createDocument();

// Create from text content
const doc = await Kodexa.fromText("Hello, World!");

// Load from a KDDB blob
const doc = await Kodexa.fromBlob(blob);

// Load from JSON
const doc = await Kodexa.fromJson(jsonString);

Accessing Original Source Content

Kodexa documents can embed the original source files (PDFs, images, Word documents) as native documents within the KDDB. This allows you to access the raw file data at any point during processing. You can use the get_source utility to retrieve the first embedded native document as bytes:

from kodexa_document.utils import get_source

# Get the original file data as BytesIO
source_bytes = get_source(document)

Alternatively, you can access native documents directly through the accessor:

# List all embedded files
native_docs = doc.native_documents.get_all()

# Get file data by ID
data = doc.native_documents.get_data(native_docs[0]["id"])

// List all embedded files
const nativeDocs = await doc.nativeDocuments.getAll();

// Get file data by ID
const data = await doc.nativeDocuments.getData(nativeDocs[0].id);

This capability is particularly useful for tasks like OCR processing or extracting content directly from the original file format at any stage of the processing pipeline.

Saving Documents

Documents are saved in KDDB format (SQLite) for efficient storage and retrieval:

# Save to KDDB file
doc.to_kddb("my-document.kddb")
doc.close()

// Export as binary blob
const blob = await doc.toBlob();

// Export as JSON
const json = await doc.toJson();
await doc.dispose();

Next Steps

Working with a Document - Learn how to navigate and manipulate document content
SDK Getting Started - Detailed guide with code examples for both Python and TypeScript
Content Nodes - Deep dive into the node hierarchy
Document Tagging - Learn about tagging and annotation

​Document Structure

​Creating Documents

​Accessing Original Source Content

​Saving Documents

​Next Steps

Document Structure

Creating Documents

Accessing Original Source Content

Saving Documents

Next Steps