TuringDB home pagelight logodark logo
  • Discord
  • GitHub
  • Website
TuringDB

Get Started

  • Introduction
  • Get Started
  • Claude Code Skill
  • Commands

Concepts

  • Overview
  • A Columnar Graph Database
  • Versioning System
  • The DataPart System
  • Zero-Locking Architecture
  • Snapshots Isolation

Benchmarks

  • Results Summary
  • Technical Report

Query Language

  • Overview
  • Matching
  • Paths
  • Results and Aggregation
  • NEXT and WHEN
  • Subqueries
  • Functions and Types
  • Writing Data
  • Procedures and Commands
  • CheatSheet

Importing data

  • JSONL
  • CSV
  • Neo4j
  • GML
  • Parquet

Graph Development

  • Create Graph
  • Load Graph
  • Load External data
  • Create a Change
  • List Changes
  • Create Nodes and Edges
  • Update Properties
  • Submit a Change
  • Time Travel
  • Graph Examples

Vector Search

  • Vector Search

Graph Algorithms

  • Shortest Path

Tutorials

  • Example Notebooks

Python SDK

  • Get Started
  • Reference

JavaScript SDK

  • Get Started
  • Reference

Release Notes

  • All Releases
  • TuringDB 3.1

Troubleshooting

  • Troubleshooting

  • Expected file format
  • Property values
  • Loading date, duration, point and embedding properties
  • Loading embedding properties
  • Import steps
  • Verify the import
Importing data

Import a JSONL file

Load a JSONL graph file into TuringDB using the LOAD JSONL command

TuringDB natively imports JSONL files through the LOAD JSONL command. The expected format is compatible with Neo4j APOC’s JSON export (produced by apoc.export.json.all with useTypes:true).

If you are migrating from Neo4j, you do not need to write this file by hand — see the Neo4j import guide.

​
Expected file format

Each line is a self-contained JSON object representing either a node or a relationship:

{"type":"node","id":"0","labels":["Person"],"properties":{"name":"Alice","age":30}}
{"type":"node","id":"1","labels":["Person"],"properties":{"name":"Bob","age":25}}
{"type":"node","id":"2","labels":["Company"],"properties":{"name":"Acme Corp"}}
{"type":"relationship","id":"0","label":"KNOWS","start":{"id":"0"},"end":{"id":"1"},"properties":{"since":2021}}
{"type":"relationship","id":"1","label":"WORKS_AT","start":{"id":"0"},"end":{"id":"2"}}

Nodes ("type": "node"):

FieldRequirement
typeMust be the string "node"
idRequired. Integer or string parseable as integer. Ids do not need to be contiguous.
labelsRequired. Array with at least one label.
propertiesOptional. Dictionary with property keys and values.

Relationships ("type": "relationship"):

FieldRequirement
typeMust be the string "relationship"
idRequired. Integer or string parseable as integer.
labelRequired. Exactly one label.
start / endRequired. Either:
- a bare integer (or string parseable as integer) referencing a node id
- a dictionary with an id key holding an integer (or string parseable as integer) referencing a node id.
propertiesOptional. Dictionary with property keys and values.

​
Property values

  • Scalars (strings, integers, doubles, booleans) become properties of the matching type, and null values are skipped.
  • Arrays load as List properties.
  • Nested objects are stored as JSON strings, unless you declare them as points (see below).
  • ISO date strings stay strings, and integer durations stay integers, unless you declare them (see below).

Each property name has a single type across the whole graph, so use the same type for a property on every node.

​
Loading date, duration, point and embedding properties

Typed options can be chained after the graph name:

LOAD JSONL 'mydata.jsonl' AS mygraph
  WITH EMBEDDINGS [{"emb", 384}, {"summary_vec", 768}]
  WITH DATETIMES [born, updatedAt]
  WITH DURATIONS [tenure]
  WITH POINTS [location]
  • WITH DATETIMES [prop, ...] parses ISO 8601 strings into DateTime values.
  • WITH DURATIONS [prop, ...] reads integers as microseconds and stores them as Duration values.
  • WITH POINTS [prop, ...] reads JSON objects as points, with the keys point() takes: {"longitude": 2.3522, "latitude": 48.8566} is a WGS-84 point and {"x": 1, "y": 2} a cartesian one. A JSON null leaves the property unset.
  • WITH EMBEDDINGS [{"prop", dim}, ...] stores arrays as Embedding values, see below.
  • A property can be declared with one type only.

​
Loading embedding properties

An array-valued property is stored as a List by default. To load specific array properties as embeddings (type Embedding, usable with cosine_similarity / euclidean_distance), append a WITH EMBEDDINGS clause listing each embedding property and its dimension:

LOAD JSONL 'mydata.jsonl' AS mygraph
  WITH EMBEDDINGS [{"embedding", 384}, {"summary_vec", 768}]

Each spec is {"<property name>", <dimension>}. The dimension must be greater than 1, and every array under that property must have exactly that many numeric elements. This works for both node and relationship properties. Array properties not listed in WITH EMBEDDINGS are stored as Lists.

When an import fails, the error names the line of the file that could not be read, for example JSONL error 'JSONL parse' at line 2: .... More details are written to <turing-dir>/logs/turingdb.log.

This sets embeddings as node/edge properties. To bulk-load embeddings onto an existing graph from a Parquet file, use LOAD EMBEDDING FROM instead.

​
Import steps

1

Place your file in the TuringDB data directory

TuringDB only reads external files from the data subdirectory of its working directory (set by -turing-dir, default $HOME/.turing).

cp mydata.jsonl ~/.turing/data/
2

Load the file into a new graph

  • Cypher
  • Python SDK
LOAD JSONL 'mydata.jsonl' AS mygraph
from turingdb import TuringDB

client = TuringDB(host="localhost", port=6666)
client.query("LOAD JSONL 'mydata.jsonl' AS mygraph")

TuringDB creates a new graph named mygraph and populates it with all nodes and relationships from the file.

3

Set the graph as active and query it

  • Cypher
  • Python SDK
cd mygraph

MATCH (n) RETURN n
client.set_graph("mygraph")

df = client.query("MATCH (n) RETURN n")
print(df)

Your JSONL data is now loaded and queryable as a TuringDB graph.

​
Verify the import

Use procedures to inspect what was imported:

  • Cypher
  • Python SDK
CALL db.labels()
CALL db.edgeTypes()
CALL db.propertyTypes()
print(client.query("CALL db.labels()"))
print(client.query("CALL db.edgeTypes()"))
print(client.query("CALL db.propertyTypes()"))
CheatSheetCSV
githublinkedinyoutubediscord