TypeDB tutorial · First presented at ER 2026
Starting from real data on palm oil trade, from Indonesian districts and mills to EU importers, you'll design a TypeDB schema step by step, load the data and query it. No TypeDB experience needed. If you know entity-relationship modelling, you'll feel at home.
The path: TypeDB basics → the data → setup → build the model → load → query → where next
TypeDB is a database whose schema is a conceptual model. You describe your domain with entities, relations and attributes. TypeDB stores data in exactly those terms, checks every query against them, and enforces their constraints.
Types can specialise other types (sub), and an @abstract type has no instances of its own. A query for a supertype automatically finds instances of all its subtypes. That's why this model is called PERA: the polymorphic entity-relation-attribute model.
| Chen's ER model | TypeDB |
|---|---|
| entity set | entity type |
| relationship set | relation type |
| role (r/e) | relates on the relation, plays on the player |
| value set | attribute type with a value type (string, integer, …) |
| attribute, a function E → V | owns |
| relationship attribute | a relation that owns an attribute |
| subset entity sets | sub |
| participation, keys, value constraints | @card, @key, @values, @range, @regex |
Unlike most ER implementations, nothing is translated away: relations keep their roles and identity, n-ary relations stay n-ary, and subtypes stay subtypes.
A schema declares the types and how they connect: which attributes a type owns, which roles a relation relates, which roles a type plays. Annotations such as @key and @card add constraints. Here is a tiny schema for companies owning companies:
Data is instances of those types. Each instance is created with isa, given attributes with has, and linked into relations through roles:
A match query describes a pattern, and TypeDB returns every way the data fits it. This one returns one answer, LOUIS DREYFUS owning LDC EAST INDONESIA:
You don't need to run these three. The tutorial below builds a fuller version of the same schema.
@key and @card are checked by the time a transaction commits, so data that breaks them never gets in.A TypeQL query is a sequence of clauses, each passing its results to the next: match finds data, then insert, delete, reduce (aggregate), sort or fetch act on it. Schema changes use define and undefine. The syntax guide on this page lists the main keywords.
Learn more: Entities, relations, attributes · Schema & data · Query clauses & pipelines · The PERA model
The data comes from Trase's open supply-chain data: 81 real trade flows of palm oil from East Kalimantan, Indonesia, to EU countries in 2022.
Benedict, J. J., Biddle, H., Gollnow, F., Heilmayr, R., Mueller, C., Ribeiro, V., & Suavet, C. (2024). Indonesia palm oil supply chain (2018–2022) (Version 1.2) [Data set]. Trase. https://doi.org/10.48650/X83N-7M36. Licensed CC BY 4.0.
One row is one trade flow: palm oil grown in a district (kabupaten), processed at a mill, sometimes refined, exported by one company and imported by another into an EU country. The columns fall into three groups:
country_of_production, province_of_production, kabupaten_of_production, country_of_first_importmill, refinery, exporter, importer, each with a *_group column for its parent companyproduct_type, volume (tonnes), fob (value in USD), palm_oil_deforestation_10_year_total_exposure (hectares)NOT REFINED means the flow has no refiner. When importer_group equals importer, no parent is recorded. A refinery that shares its name with an exporter is read as owned by that company.You need a TypeDB server and a web browser.
Running TypeDB CE 3.13.6... and then Ready!. Or:http://localhost:8000, admin, password by defaultIn Studio, check at the top of the page that you're connected. Then create a new, empty database (next to the connection info).
To write queries, open the Query page. Each query in the tutorial can be pasted into the editor and run with the green Play button in the top right. Queries auto-commit, and schema changes show up in the left sidebar.
Learn more: TypeDB Studio · Installing TypeDB CE
Ready to go!
We read the data and model it a few columns at a time. Each step shows an ER diagram first and the TypeQL behind a reveal: try writing it yourself before you look, then run each snippet in order.
Reading the header and a first row, the easiest things to model are the places: the country, the province and the kabupaten (district) the palm oil comes from.
attribute name, value string; declares an attribute type and its value type. country_name and the other names are subtypes of name, so a query for name finds all of them.entity place @abstract; is a supertype with no direct instances. sub place makes country, province and kabupaten kinds of place.owns country_name @key: every country has exactly one name, and no two countries share it.Learn more: Type hierarchies · @abstract · @key
Presumably the places nest: a kabupaten lies in a province, which lies in a country.
relation containment, relates parent, relates child declares a relation and its two roles.plays containment:child says which types can fill a role. A province plays both roles.@card sets how many: each containment has exactly one parent and one child (@card(1)), and a place has at most one parent (@card(0..1)).define on an existing type, like entity country here, adds to it.Learn more: Constraining data · @card
Tip: open the Schema page in Studio to see what your schema contains so far, drawn as a graph.
The next columns are harder: the same names turn up as a mill's group, a refinery, an exporter and an importer. Is a refinery_group a different kind of thing from an exporter_group?
A few real rows (scroll sideways for more columns). Coloured: a name that appears more than once in the same row, each name in its own colour. NOT REFINED marks crude palm oil.
The data sheet says each *_group column "groups the [X] column into parent companies where applicable". So there are really only companies and facilities (mills and refineries), linked by ownership, and exporter is a role a company plays, not a kind of company.
mill and refinery are kinds of facility, and facilities and companies are kinds of legal_entity.owned.@key). Mills and refineries simply own a name.Learn more: Determining object types · Using type hierarchies
In some rows LDC EAST INDONESIA is both the refinery and the exporter, and LOUIS DREYFUS is the refinery's group.
We read this as: the company LDC EAST INDONESIA owns the refinery of the same name and handles exports, and LOUIS DREYFUS is its parent company. So companies need to be ownable by other companies too.
Open the Schema page in Studio again to inspect the current schema: companies, facilities and the ownership relation now sit alongside the places.
The data has two commodities, PALM OIL and REFINED PALM OIL. How would you model them?
Let's proceed with option a, as it's the simplest one.
@values(...) restricts an attribute to a fixed set of values, like an enum.Learn more: @values
Each row of the data is one trade flow linking a district, a mill, sometimes a refinery (crude palm oil isn't refined), an exporter, an importer, a destination country and a commodity. How would you model the flow itself?
@card(1)) and the refiner is optional (@card(0..1)).double and decimal are numeric value types.In TypeDB the seven-way relation is stored, typed and constrained as it is.
Snippets 1–6 combined into a single define query. Use it if you skipped ahead or want a clean start: run it in a new, empty database.
With the full schema in place, one insert query loads all 81 trade flows. It creates the places, companies and facilities first, binding each to a variable such as $co_louis_dreyfus, then uses those variables to create the containment, ownership and trade-flow relations. The whole query commits as one transaction, so if anything breaks the schema, none of it is saved.
Learn more: Inserting data · Transactions
Each question below hides a query. Try writing it first, then open it and run it. The result counts are for this dataset.
A query lists statements that must all be true. isa facility also matches every subtype of facility. isa! matches only the exact type, so $f isa! $t binds $t to each facility's own type.
Learn more: Variables & patterns · Polymorphic queries · reduce
links (role: $x) matches a relation through one of its roles; you only name the roles you care about. not { … } excludes matches, which suits optional roles like the refiner.
deforestation_ha) by importer.Learn more: Relation patterns · Negations · Aggregations
A facility can sit under several layers of companies. Can one query find all of a facility's owners? A disjunction ({ … } or { … }) handles a fixed number of hops. A recursive function handles any number: with fun defines a function for this query only, and let $c in owners($f) calls it.
Learn more: Disjunctions · Functions
These are meant to fail. The first two are rejected by the type checker before anything runs; the third breaks a schema constraint when it's committed.
Learn more: Query validation · Data validation
The schema is queryable with the same language. Variables can stand for types as well as data, and statements like relates, plays and sub work in match too.
Learn more: Querying schema types
You've built a typed, constrained model of a real supply chain, loaded it and queried it. To keep going:
Or extend this model: add the ports of export or the sustainability commitments from the full Trase dataset, or model ownership shares as an attribute of ownership.