Import a dataset

The onboarding interface inspects files, loads records, and imports ontologies into a selected database. Begin with a small sample so you can check identifiers and types before a larger import.

Before you begin

You need a running server, its HTTP address, an existing logical database ID, and permission to write to that database. These examples use the shrikedb command-line client built into the server executable. It sends requests to the running server; it does not start a second database process.

Use --upload when the input file is on the client computer. Without that flag, the input path is read on the server. See Command Line Interfaces for authentication options and Connect To ShrikeDB for database discovery.

Format	Use
CSV / TSV	Inspect inferred columns and load row nodes or a reviewed edge-list mapping.
JSONL	Inspect simple object rows; nested JSONL loading requires a separately supported mapping/import path.
Turtle / RDF/XML / OWL	Import asserted triples, with optional ontology materialization.
Parquet	Use lakehouse registration and mappings for external files.

Format

Use

CSV / TSV

Inspect inferred columns and load row nodes or a reviewed edge-list mapping.

JSONL

Inspect simple object rows; nested JSONL loading requires a separately supported mapping/import path.

Turtle / RDF/XML / OWL

Import asserted triples, with optional ontology materialization.

Parquet

Use lakehouse registration and mappings for external files.

1. Prepare a small file

Create a client-local CSV with stable identifiers:

cat > people.csv <<'EOF'
id,name,country
1001,Alice,US
1002,Bob,GB
EOF
export SHRIKEDB_DATABASE='YOUR_DATABASE_ID'

Set SHRIKEDB_DATABASE to an ID returned by your server’s database list.

2. Inspect the file

shrikedb --server http://127.0.0.1:8182 --db "$SHRIKEDB_DATABASE" \
  onboard inspect --input people.csv --format csv --upload --sample-rows 50

Review column names, inferred types, sample values, and any parse diagnostics. Treat identifiers as identifiers even when they contain only digits; leading zeros or very large numbers may be significant. Correct delimiter or encoding problems before loading.

3. Load a bounded sample

shrikedb --server http://127.0.0.1:8182 --db "$SHRIKEDB_DATABASE" \
  onboard load --input people.csv --format csv --upload --row-limit 100

The default tabular path loads row nodes. Use a reviewed load plan when columns should form relationships or require a particular mapping. Save the response and inspect the resulting labels, properties, and counts before loading the full dataset. Repeating a load may create or update records according to its mapping; keep identifiers and retry behavior explicit.

4. Check the loaded data

Submit this Cypher through your selected database’s direct query interface:

MATCH (n) RETURN n LIMIT 10

Use the returned labels and properties to write a count query specific to the imported records. Compare that count with the accepted rows reported by the loader, including any skipped or rejected records.

5. Add ontology context when needed

An ontology supplies classes and relationships for semantic interpretation. Import a Turtle file from your client with:

shrikedb --server http://127.0.0.1:8182 --db "$SHRIKEDB_DATABASE" \
  ontology import --input ontology.ttl --format turtle --upload --materialize

Supply your own ontology.ttl. --materialize asks the reasoner to add inferred facts during import. Omit it to import asserted facts only. Inspect the import report and query representative triples as described in Import and reason over ontologies.

6. Prepare natural-language questions

Direct Cypher and SPARQL queries can use the loaded data immediately. Natural-language questions also need a semantic profile that maps domain terms to the dataset. Follow Profiles and domain vocabulary to discover and review that vocabulary, then connect an agent using Connect an MCP agent.

Use HTTP or MCP instead

The same inspection operation is available through HTTP. This example reads a file already present on the server:

curl --fail-with-body http://127.0.0.1:8182/api/v1/onboarding/inspect \
  -H 'Content-Type: application/json' \
  -H "x-shrikedb-database: $SHRIKEDB_DATABASE" \
  -d '{"source":{"input":"/data/people.csv","format":"csv"},"sample_rows":50}'

For an authenticated server, add the credential header from Connect To ShrikeDB. MCP clients can discover onboarding_inspect, onboarding_load_dataset, and onboarding_import_ontology through tools/list; MCP Tools shows the request envelope.