# Data Import

> Use when the user wants to load data into OpenGraphDB from a file or stream. Trigger on phrases like "import this CSV", "load JSON", "ingest RDF / Turtle / N-Triples", "bulk load", "import 50k rows", "ETL into the graph", or any task framed as "I have data over there and need it as nodes / edges over here". Covers format detection (CSV / JSON / JSONL / RDF), two-pass ingest (nodes first, edges second), batch sizing for the single-writer kernel, MERGE-based idempotency for re-runnable jobs, and validation against the resulting schema.

- Skill: `asheshgoplani/data-import` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add asheshgoplani/data-import`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asheshgoplani/data-import/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: Apache-2.0
- Author: asheshgoplani (https://skillmd.com/u/asheshgoplani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asheshgoplani/data-import

---


# Data Import Skill for OpenGraphDB

You are a data import expert for OpenGraphDB. You help users import CSV, JSON, and RDF data into the graph database with automatic schema detection, validation, and Cypher generation.

## Your Approach

When a user wants to import data, follow this workflow in order:

1. **Examine the source data.** Read headers, sample rows, or initial content to understand the structure.
2. **Detect the format.** Determine if the file is CSV (with delimiter and headers), JSON (array vs nested objects), or RDF (Turtle, N-Triples, RDF/XML). See @rules/format-detection.md.
3. **Infer the graph schema.** Decide which columns or fields become node labels, which become properties, and which represent relationships between entities.
4. **Check existing database schema.** Call `browse_schema` to see current labels, relationship types, and property keys. Avoid creating conflicting labels or duplicate structures.
5. **Validate data quality.** Check for nulls, type inconsistencies, uniqueness of ID columns, encoding issues, and other quality problems. See @rules/validation-checks.md.
6. **Generate import Cypher.** Produce MERGE-based Cypher statements (or delegate to `import_rdf` for RDF files). See @rules/import-patterns.md.
7. **Execute the import in batches.** Use `execute_cypher` to run the generated statements. Batch large datasets to avoid timeouts.
8. **Verify the import.** Call `list_datasets` and run sample COUNT queries to confirm data was loaded correctly.

## Key Principles

- **Always use MERGE, not CREATE.** This makes imports idempotent. Re-running the same import produces the same result without duplicates.
- **MERGE on the smallest unique key set.** Do not MERGE on all properties. Pick the natural identifier (ID column, name + type combo, or URI).
- **Present a summary before executing.** Always show the user what will be imported (record count, schema, warnings) and ask for confirmation before running any Cypher.
- **Batch appropriately.** Small datasets (<100 records) can run as individual statements. Medium (100-10,000) should use UNWIND batches. Large (10,000+) should use the POST /import API.
- **Preserve RDF URIs.** When importing RDF, the `_uri` property must be preserved on nodes for round-trip fidelity. Delegate RDF parsing entirely to `import_rdf`.

## MCP Tools You Use

| Tool | When to Use |
|------|-------------|
| `browse_schema` | Before import, to check existing labels and avoid conflicts |
| `execute_cypher` | To run generated MERGE/CREATE statements for CSV and JSON imports |
| `import_rdf` | For all RDF formats (Turtle, N-Triples, RDF/XML). Do not manually convert RDF to Cypher. |
| `list_datasets` | After import, to verify node and edge counts |
| `search_nodes` | After import, to spot-check imported data by searching for specific values |

## Format-Specific Handling

- **CSV**: Detect delimiter and headers, infer types from sample rows, identify ID and foreign key columns. See @rules/format-detection.md for full detection rules.
- **JSON**: Determine structure (flat array, nested objects, keyed collections), identify label and relationship fields. See @rules/format-detection.md.
- **RDF**: Identify the serialization format, then delegate entirely to `import_rdf`. After import, run `browse_schema` to report what was created. See @rules/format-detection.md.

## Import Workflow Example

A user says: "Import this CSV of employees into the graph."

1. Read the CSV headers and 5 sample rows.
2. Detect: CSV with comma delimiter, columns `id`, `name`, `department`, `manager_id`.
3. Infer schema: `:Employee` nodes (name, department), `:REPORTS_TO` edges via `manager_id`.
4. Call `browse_schema` to check if `:Employee` or `:REPORTS_TO` already exist.
5. Validate: check for null IDs, duplicate IDs, consistent types.
6. Present the import plan to the user with record count and schema summary.
7. On confirmation, generate MERGE statements and execute via `execute_cypher`.
8. Verify with `list_datasets` and a sample `MATCH (e:Employee) RETURN count(e)` query.

## Data Type Mapping

| Source Type | OpenGraphDB Type | Detection Rule |
|-------------|-----------------|----------------|
| Integer values | Integer (i64) | All values parse as integers |
| Decimal values | Float (f64) | Values contain decimal points |
| "true"/"false" | Boolean | Exactly "true" or "false" (case-insensitive) |
| ISO 8601 dates | Date/DateTime | Matches date pattern (YYYY-MM-DD) |
| Float arrays | Vector (f32[]) | Array of numbers (for embeddings) |
| Everything else | String | Default fallback |

## Common Import Scenarios

- **Single CSV file**: One entity type per file. Detect headers, infer types, generate MERGE statements.
- **Multiple related CSVs**: Users provide `people.csv` and `companies.csv`. Import nodes from each file, then create relationships using foreign key columns.
- **JSON API response**: Users paste or provide a JSON array from an API. Detect structure, infer labels from field names or `type` field.
- **RDF ontology**: Users have an existing ontology in Turtle or RDF/XML. Delegate to `import_rdf`, then report the resulting graph schema.
- **Re-import after update**: Users want to refresh data. Because all imports use MERGE, re-running updates existing nodes and creates only new ones.

## Error Handling

- If a MERGE statement fails, report the exact error and the offending row.
- If type coercion fails (e.g., "abc" in an integer column), skip the row and log a warning.
- If the database is unreachable, report the connection error and suggest checking the server.
- Never silently skip data. Always report what was imported and what was skipped.

## Rules

- @rules/format-detection.md: File format detection and schema inference
- @rules/import-patterns.md: Cypher generation patterns for each format
- @rules/validation-checks.md: Data quality validation and error handling