Skip to main content
Notes provide a way to attach human-readable annotations, comments, and documentation to documents, data objects, and data attributes. They support multiple content formats and hierarchical organization.

Overview

Notes support:
  • Multiple Content Types: TEXT, MARKDOWN, or HTML
  • Attachment to Entities: Link notes to data objects or data attributes
  • Hierarchical Structure: Create parent-child note relationships
  • Grouping: Organize related notes with group keys
  • Custom Properties: Attach arbitrary metadata to notes

Creating Notes

from kodexa_document import Document
from kodexa_document.accessors import NoteInput, NoteType, DataObjectInput

with Document() as doc:
    root = doc.create_node("document", "Invoice")
    doc.content_node = root

    # Create a simple text note
    note = doc.notes.create(NoteInput(
        title="Review Comment",
        content="This invoice needs manager approval.",
        note_type=NoteType.text
    ))
    print(f"Created note: {note}")

    # Create a markdown note
    doc.notes.create(NoteInput(
        title="Processing Notes",
        content="## Summary\n- Vendor: Acme Corp\n- Status: **Pending Review**",
        note_type=NoteType.markdown
    ))

    # Create a note attached to a data object
    invoice = doc.data_objects.create(DataObjectInput(path="/invoice"))
    doc.notes.create(NoteInput(
        title="Extraction Note",
        content="Confidence is low for the total amount field.",
        note_type=NoteType.text,
        data_object_id=invoice['id']
    ))

Notes with Properties

Attach custom metadata to notes:
with Document() as doc:
    root = doc.create_node("document", "Content")
    doc.content_node = root

    doc.notes.create(NoteInput(
        title="QA Review",
        content="Reviewed and approved by QA team.",
        note_type=NoteType.text,
        properties={
            "reviewer": "[email protected]",
            "reviewDate": "2024-01-15",
            "status": "approved",
            "priority": "high"
        }
    ))

Hierarchical Notes

Create threaded conversations with parent-child notes:
with Document() as doc:
    root = doc.create_node("document", "Content")
    doc.content_node = root

    # Create a parent note
    parent = doc.notes.create(NoteInput(
        title="Discussion",
        content="Should we flag this for review?",
        note_type=NoteType.text
    ))

    # Create reply notes
    doc.notes.create(NoteInput(
        content="Yes, the confidence scores are below threshold.",
        note_type=NoteType.text,
        parent_note_id=parent['id']
    ))

    doc.notes.create(NoteInput(
        content="Agreed. I've escalated to the review queue.",
        note_type=NoteType.text,
        parent_note_id=parent['id']
    ))

    # Get root-level notes (no parent)
    root_notes = doc.notes.get_root_notes()
    print(f"Top-level notes: {len(root_notes)}")

    # Get replies
    for note in root_notes:
        children = doc.notes.get_child_notes(note['id'])
        print(f"  Replies: {len(children)}")

Retrieving Notes

with Document.from_kddb("processed.kddb") as doc:
    # Get all notes
    all_notes = doc.notes.get_all()
    print(f"Total notes: {len(all_notes)}")

    # Get notes for a specific data object
    obj_notes = doc.notes.get_by_data_object_id(data_object_id=1)

    # Get notes for a specific data attribute
    attr_notes = doc.notes.get_by_data_attribute_id(data_attribute_id=1)

    # Get notes by type
    markdown_notes = doc.notes.get_by_type("MARKDOWN")

    # Get by UUID
    note = doc.notes.get_by_uuid("note-uuid")

    # Get by group
    grouped = doc.notes.get_by_group_uuid("group-uuid")

Updating and Deleting Notes

with Document.from_kddb("processed.kddb") as doc:
    # Update a note
    doc.notes.update(note_id=1, input=NoteInput(
        title="Updated Title",
        content="Updated content with corrections.",
        note_type=NoteType.text
    ))

    # Delete a note
    doc.notes.delete(note_id=1)

NoteInput Reference

FieldPythonTypeScriptDescription
ContentcontentcontentThe note text (required)
TitletitletitleOptional note title
Typenote_typenoteTypeTEXT, MARKDOWN, or HTML
Data Objectdata_object_iddataObjectIdAttach to a data object
Data Attributedata_attribute_iddataAttributeIdAttach to a data attribute
Parent Noteparent_note_idparentNoteIdCreate as a child note
Groupgroup_uuid (Python) / groupKey (TS)Group related notes
PropertiespropertiespropertiesCustom metadata dictionary

API Reference

NoteAccessor Methods

Method (Python)Method (TypeScript)Description
get_all()getAll()Get all notes
get_by_data_object_id(id)getByDataObjectID(id)Notes for a data object
get_by_data_attribute_id(id)getByDataAttributeID(id)Notes for a data attribute
create(input)create(input)Create a new note
update(id, input)update(note)Update a note
delete(id)delete(id)Delete a note
get_by_uuid(uuid)getByID(id)Get a specific note
get_by_type(type)getByType(type)Filter by content type
get_by_group_uuid(uuid)getByGroupKey(key)Get grouped notes
get_root_notes()getRootNotes()Get top-level notes
get_child_notes(id)getChildNotes(id)Get replies/children