binder-import

Binder Import

Import external data into a Binder knowledge graph by mapping source structure onto the existing schema, then generating transaction files.

Supported Sources

• Tabular: CSV, TSV (rows become records, headers become field candidates)
• Structured: JSON array, YAML list (objects become records, keys become field candidates)
• Single Markdown: one file with repeating structure (tables, heading-delimited sections, lists)
• Markdown directory: folder of .md files where each file becomes one or more records (frontmatter fields + body content)

Process Overview

1. Sample the source to understand structure
2. Inspect the target schema
3. Analyze gaps between source data and schema
4. Propose mapping and present to user
5. Check for duplicates against existing records
6. Generate transactions in batches
7. Dry-run and apply each batch

Step 1: Sample the Source

Do not read the entire source upfront. Sample enough to understand structure and value patterns.

Tabular files (CSV, JSON, YAML):

• Small (< 200 rows): read the whole file
• Large (200+ rows): read the first 50 rows. Note total row count. Ask the user if the structure is uniform throughout

Single Markdown file:

• Small (< 300 lines): read the whole file
• Large (300+ lines): read the first 200 lines. Ask the user if the pattern continues or if there are structurally different sections later

Markdown directory:

• List all files: find <dir> -name '*.md' | head -100
• Count total: find <dir> -name '*.md' | wc -l
• Read 3-5 files chosen for variety (different sizes, different subdirectories, first and last alphabetically)
• Note if files have frontmatter, consistent heading structure, or freeform content

Report what you found: number of items, identified columns/fields, sample values, any inconsistencies.

Step 2: Inspect Target Schema

binder schema
binder schema -n config

Identify which types and fields already exist. Pay attention to:

• Field data types and constraints
• Required fields and defaults
• Relation fields and their targets
• Option fields and their allowed values