TriplyDB at a glance¶

TriplyDB is a platform for linked data knowledge graphs. It stores them, lets you explore, model and edit them, and exposes them through SPARQL, GraphQL, Elasticsearch, Linked Data Fragments and REST. You can turn queries into APIs and stories, and build the pipelines that keep the data up to date. Everything is owned by users and groups, and access levels decide who can see it.

This page covers two things: what TriplyDB is for, and the words it uses for its own parts. Read it before you start. Several of those words mean something narrower here than they do in general use.

The ideas underneath — triples, IRIs, graphs as a data model, SPARQL — are not product-specific. They are covered in Linked data and Knowledge graphs.

What it is for¶

How the parts fit together¶

Read the solid arrows as ownership. An instance holds accounts. A group can hold subgroups. An account owns datasets, saved queries, stories and flows. A dataset holds graphs, assets and services.

The dotted arrows show how things use each other. A saved query runs on a dataset, directly or through one of its services. A story embeds saved queries. A flow can create datasets and change their data, and copy, move, publish or delete what an account holds. None of these links copies anything: change the saved query and every story that embeds it changes too.

Instance¶

An instance is one installation of TriplyDB. triplydb.com is an instance; so is a customer's own deployment.

An instance has two parts. The console is the web interface. The API sits between the console and the data. They are separate components with their own version numbers, which is why an administrator sees two versions rather than one.

Instance-wide settings are configured by administrators: branding, example datasets, site-wide prefixes, authentication, roles, and the maximum and default access level. So are optional features such as the Editor, GraphQL and Flows, which is why two instances can offer different things. See Admin settings.

Account¶

Everything on an instance is owned by an account. There are two kinds:

• A user account, belonging to a person.
• A group, belonging to several people, with members who hold roles.

Either kind can own datasets, saved queries, stories and flows. Content owned by a group belongs to the group and not to whoever created it, so it stays in place when people leave.

Nested groupsPrivate preview¶

A group can contain subgroups, and a subgroup can contain its own subgroups. That lets a group mirror how an organisation is actually structured: acme, then acme/research, then a subgroup per project. Three rules hold throughout:

• Membership is inherited downwards. A member of a group is also a member of every subgroup below it, with the same role. A direct role in a subgroup can only add to what that member already has.
• A subgroup is never more accessible than its parent. A new subgroup takes its parent's access level.
• A subgroup is a boundary. Someone added only to a subgroup does not see the parent group's non-public content. That makes a subgroup the natural place for an external collaborator.

See Access control for the details.

Dataset¶

A dataset is the unit you manage. It has an owner, an access level, metadata, and any services you start on it. It is also the unit that gets published, shared and exported.

A dataset contains graphs, and may also contain assets.

"Dataset" and "knowledge graph" describe the same thing from two angles — dataset emphasises the manageable unit, knowledge graph the connected data inside it. See Knowledge graphs.

Graph¶

A graph is a named group of statements inside a dataset. Every statement belongs to exactly one graph, and every graph belongs to one dataset.

That makes the arithmetic simple: a dataset's statement count is the sum of its graphs' statement counts.

Graphs are the unit of import and export. You add data one graph at a time, and you can export a single graph. When a graph changes, any service holding that data falls out of step.

Statement¶

A statement is a triple: a subject, a predicate and an object. The two words mean the same thing. TriplyDB says "statement" when it counts, as in the statement counts on datasets, graphs and services.

See Linked data.

Asset¶

An asset is a file that is not RDF — an image, a video, a PDF — stored inside a dataset alongside its graphs, so that the knowledge graph can refer to it.

Assets are counted separately from statements, and administrators see an asset count per dataset.

Service¶

A service runs a dedicated engine over a copy of a dataset. None is needed to query: every dataset can be queried with SPARQL through Speedy, TriplyDB's built-in engine, as soon as it holds data. A service adds what Speedy does not offer:

• SPARQL – Virtuoso and SPARQL – Jena, SPARQL engines of their own, each with an endpoint for the dataset alone.
• Elasticsearch, a text index for full-text search.

A dataset can have several services at once, and which of the three types are offered depends on how the instance is configured.

When a service is worth creating¶

Speedy is the default, and for most querying it is all a dataset needs. It is also the only engine that supports the SPARQL introspection functions, so a query that uses them has to stay on Speedy. A service earns its place for something Speedy does not do:

• Reasoning. A Jena service can be created with a reasoner, RDFS or OWL, so that queries also see the statements the dataset's schema implies.
• Full-text search. The Elasticsearch entry in a dataset's sidebar appears only once an Elasticsearch service is running.

Why a service falls out of step¶

A service loads the state of the dataset at the moment it is created, and holds its own copy from then on. Later changes to the dataset do not reach it: whenever a graph is added, deleted or renamed, the service holds older data than the dataset until it is synchronised. Speedy has no copy of its own, so it never falls behind.

Why a service stops on its own¶

Some services stop automatically once they have not been queried for a while, to free memory on the instance. The timer resets every time the service is used, and the service starts again when it is next queried.

So a query on a service that suddenly returns nothing, or returns old results, is usually one of two things, neither of them a problem with the query: a service that has stopped, or a service that has not been synchronised since the data changed.

See Manage services.

Saved query¶

A saved query is a SPARQL query with a persistent URL, metadata and an access level of its own. It is owned by an account, not by the dataset it queries. It runs against that dataset, either directly or through one of the dataset's services.

Saving never overwrites. Each save adds a version that holds the query string and its visualisation. A URL with a version number stays fixed. A URL without one always points to the latest version. Every saved query is also a REST API, and it can take variables, so one query can serve many requests.

A query bound to a service stops returning results when that service is stopped or removed, even though the query itself has not changed.

See Work with saved queries and the saved queries reference.

Story¶

A story presents data as a readable narrative. It is a sequence of paragraphs and saved query results, and like a saved query it has its own owner and access level. The results are live: they re-run when a reader opens the story, so the story keeps up with the data.

A story points to its queries and holds no copy of them. Editing a query changes every story that uses it, unless the story pins a version.

See Build a data story.

FlowPrivate preview¶

A flow is a data pipeline built inside TriplyDB. You arrange tasks on a canvas — import from a URL, transform with a CONSTRUCT query, validate with SHACL — and connect them in the order they should run. Each task reads and writes datasets and graphs directly. Tasks are not limited to data: a flow can also copy, move, publish or delete datasets, saved queries and stories, recreate services, and send emails and HTTP requests. A flow is owned by an account, versioned on every save, and made reusable with variables; masked values hold credentials.

Each execution is a run, which records who triggered it and how every task went. A run can be started by hand, on a schedule, or over HTTP. A single flow can take data from a source system all the way to a published dataset and a refreshed service, without a script outside TriplyDB.

See Flows for the model and Build your first flow to make one.

Access level¶

Datasets, saved queries, stories and groups each have an access level: Public, Internal or Private. New datasets, queries, stories and groups start at the instance's default level, which is Private unless an administrator changed it; a new subgroupPrivate preview takes its parent's level. An administrator can also cap the level for the whole instance.

The level decides who can find and open an item. Services follow their dataset, so the dataset's level also decides who can query it. A saved query or story has a level of its own, set independently of the dataset it draws on.

Roles are a separate mechanism. They apply only to members of a group, and only ever add to what the access level already allows.

See Access control for what each level means and how levels interact with groups.

Site-wide prefix¶

A site-wide prefix is a prefix defined once by an administrator and applied across every dataset on the instance whose IRIs match it. It saves each dataset declaring the same abbreviations.

See Linked data for what a prefix is.

Where to go next¶