Skip to main content
External data provides a flexible key-value store within KDDB documents for storing custom data, processing results, or extension-specific information.

​
Commands

​
List Keys

View all external data keys in a document: 
kdx document external list <file.kddb>
Example: 
kdx document external list invoice.kddb

┌─────────────────┐
│       KEY       │
├─────────────────┤
│ ocr_results     │
│ extraction_config│
│ processing_status│
└─────────────────┘
If no external data exists: 
No external data keys found

​
Get Value

Retrieve the value for a specific key: 
kdx document external get <file.kddb> <key>
Example: 
kdx document external get invoice.kddb processing_status

┌───────────────┬─────────────────────────────────────┐
│     FIELD     │                VALUE                │
├───────────────┼─────────────────────────────────────┤
│ status        │ completed                           │
│ processed_at  │ 2024-01-15T10:30:00Z                │
│ pages_processed│ 5                                  │
└───────────────┴─────────────────────────────────────┘

​
Set Value

Store or update a value for a key: 
kdx document external set <file.kddb> <key> <json-value>
The value must be valid JSON. Strings must be quoted, objects use curly braces, etc.
Examples: 
# Set a string value
kdx document external set invoice.kddb status '"processed"'

# Set a number
kdx document external set invoice.kddb confidence '0.95'

# Set a boolean
kdx document external set invoice.kddb reviewed 'true'

# Set an object
kdx document external set invoice.kddb processing_status '{"status": "completed", "pages": 5}'

# Set an array
kdx document external set invoice.kddb tags '["invoice", "urgent", "reviewed"]'
Output: 
Set external data key: processing_status

​
Delete Key

Remove an external data key: 
kdx document external delete <file.kddb> <key>
Example: 
kdx document external delete invoice.kddb temp_data

Deleted external data key: temp_data

​
Output Formats

Use the global -o flag for different output formats: 
# JSON output
kdx document external get invoice.kddb processing_status -o json

# YAML output
kdx document external list invoice.kddb -o yaml
JSON output example: 
{
  "status": "completed",
  "processed_at": "2024-01-15T10:30:00Z",
  "pages_processed": 5
}

​
JSON Value Examples

Since values must be valid JSON, here are common patterns:
Value TypeJSON SyntaxExample
String"value"'"hello world"'
Number123 or 3.14'42'
Booleantrue or false'true'
Nullnull'null'
Array[...]'["a", "b", "c"]'
Object{...}'{"key": "value"}'
Use single quotes around the JSON value in bash to prevent shell expansion of special characters.

​
Use Cases

​
Store Processing Results

Save extraction or analysis results: 
# Store OCR confidence
kdx document external set invoice.kddb ocr_confidence '0.92'

# Store extraction results
kdx document external set invoice.kddb extraction '{"vendor": "Acme Corp", "total": 1234.56}'

​
Track Processing Status

Maintain workflow state: 
# Mark as processed
kdx document external set invoice.kddb status '"completed"'

# Store processing metadata
kdx document external set invoice.kddb processing '{"model": "invoice-v2", "timestamp": "2024-01-15T10:30:00Z"}'

​
Configuration Storage

Store document-specific configuration: 
# Store extraction config
kdx document external set invoice.kddb config '{"extract_tables": true, "language": "en"}'

​
Scripting Integration

Use external data in automated workflows: 
# Check if document was processed
STATUS=$(kdx document external get invoice.kddb status -o json 2>/dev/null)
if [ "$STATUS" = '"completed"' ]; then
  echo "Already processed"
else
  echo "Needs processing"
fi

# Copy external data between documents
VALUE=$(kdx document external get source.kddb config -o json)
kdx document external set target.kddb config "$VALUE"

​
Notes

External data is stored as JSON in the KDDB database. Complex nested structures are fully supported.
Modifying external data changes the KDDB file. Make backups before making changes to important documents.

SDK: External Data

Work with external data programmatically

Document Overview

Back to document commands overview