UUID v7 Keys and Faster JSON Loading

TerminusDB 12.0.8 adds UuidV7 document keys that accept IDs issued by other systems, and loads raw JSON about 4.6× faster. It was released on 12 October 2026.

UuidV7 keys — keep the IDs your data already has, or let TerminusDB create time-ordered UUIDs.
Faster inserts — ID creation is about 6× faster. A 100 MB raw JSON file now loads in 27 s instead of 125 s.
Fixes — 11 fixes for GraphQL, UTF-8, @unfold, bundles and JWT scopes.

UuidV7 keys

What it does

UuidV7 is a new @key type for classes. It works in two ways:

You supply an @id. TerminusDB uses it as it is. It does not need to start with the class @base. UUIDs, GUIDs and full IRIs from other systems are all accepted.
You leave out @id. TerminusDB creates one: the class @base plus a new RFC 9562 UUID v7, for example Artwork/01a120f0-47a7-7f20-9295-b3034d7fc5d3.

UUID v7 values contain a timestamp, so new IDs sort by creation time.

Why it matters

Enterprise data often arrives with identifiers that were created somewhere else. Ontologies such as Linked Art use instance IRIs like https://linked.art/example/object/47. Before 12.0.8, the Random key refused these, because a submitted @id had to sit under the class @base. You had to rewrite every IRI before you could load the data.

With UuidV7 you can load that data into your knowledge graph as it is, and still get generated IDs for new records.

Example

Example: JSON

{
  "@id": "Artwork",
  "@type": "Class",
  "@key": { "@type": "UuidV7" },
  "title": "xsd:string"
}

Insert one document with an external IRI and one without an @id:

Example: JSON

[
  { "@type": "Artwork", "@id": "https://linked.art/example/object/47", "title": "Night Watch" },
  { "@type": "Artwork", "title": "New acquisition" }
]

The second document gets an ID like Artwork/01a120f0-47a7-7f20-9295-b3034d7fc5d3.

UuidV7 works for top-level classes, @subdocument classes and TaggedUnion members. It is also available in WOQL (UuidV7, like RandomKey), in the JavaScript client (WOQL.idgen_uuid_v7(base, uri)) and in the Python client (UuidV7Key).

Faster inserts

ID creation is one of the most common steps when you insert documents. In 12.0.8:

Creating one ID went from about 1,200 ns to about 200 ns. This also speeds up Random, Lexical and Hash keys.
Content hashes for raw JSON (sys:JSON, sys:JSONDocument) are now computed in Rust. A nested document of about 60 triples inserts in 0.47 ms instead of 2.0 ms (about 4.3×).
A 100 MB raw JSON file loads, converts to triples and commits in 27.2 s instead of 125.5 s on the same hardware.

The IDs are byte-identical to before, so existing data does not change.

Read more: Raw JSON IDs

Fixes

Fixed unbundle failing with unknown_layer_reference across stores (#2540)
Fixed insert performance regressions (#2529)
Field-level @unfold now works for List and multi-dimensional Array properties (#2513)
GraphQL frames accept the @shared class annotation (#2533)
GraphQL __typename and fragments resolve on generated types (#2551)
Removed GraphQL debug logging that could panic on multibyte UTF-8 (#2532)
PUT with charset=utf-8 writes documents again (#2544)
Streaming history endpoint returns correct UTF-8 (#2545)
WOQL JSON inserts booleans and list scalars correctly (#2546)
JWT scope upgrade resolves roles by id, not display name (#2539)
Removed a leftover debug log (#2534)

Also: faster CLI and integration tests (#2543) and dependency bumps. Thanks to our two new contributors, @hideo67 and @bixycler.

Upgrade

Example: Bash

docker pull terminusdb/terminusdb-server:v12.0.8

No data migration is needed. Docker install guide · Full changelog on GitHub

Previous: TerminusDB 12.0.7: Resolve Merge Conflicts with Insert and Delete Patches · All 12.0 releases: TerminusDB 12.0 changelog · Release index

TerminusDB 12.0.8: UUID v7 Keys and 4.6× Faster Raw JSON Loading