Class Dataset

A TriplyDB dataset: a collection of named graphs, together with its services and assets.

Remarks

Obtain one from an Account with getDataset, addDataset or ensureDataset. Datasets are never constructed directly.

Example: Get a dataset that already exists

import App from "@triply/triplydb";

const app = App.get({ token: process.env.TOKEN });
const account = await app.getAccount("my-account");
const dataset = await account.getDataset("my-dataset");

Example: Create it on first run, then load a file into it

const dataset = await account.ensureDataset("my-dataset", { accessLevel: "private" });
await dataset.importFromFiles(["./data.trig"]);

Properties

slug

slug: string

The dataset's short name, as it appears in its URL.

Methods

addPrefixes

addPrefixes(newPrefixes: Prefixes): Promise<{ [prefixLabel: string]: string }>
Adds IRI prefix declarations to this dataset.
Parameters
- newPrefixes: Prefixes
  Alias-to-IRI pairs, for example { ex: "https://example.org/" }.
Returns Promise<{ [prefixLabel: string]: string }>

Remarks
These shorten IRIs in the console and in query results. Adding a label that already exists replaces its IRI.

addService

addService(name: string, opts?: NewService): Promise<Service>

Creates a service that makes this dataset queryable.

Parameters

name: string
Name for the service, which becomes part of its URL.
Optionalopts: NewService
Which kind to create; a SPARQL service (virtuoso) when omitted.

Returns Promise<Service>

Remarks

The service starts out empty and syncs the dataset in the background, so it cannot answer queries yet — wait with Service.waitUntilRunning.

Throws

If this dataset already has a service with that name. Use Dataset.ensureService when you want the existing one.

Example: A search service whose index is built from your own template

// `index_patterns` has to be "index" — that is what the service calls its index, and a
// template that matches nothing is silently unused.
const service = await dataset.addService("my-search", {
  type: "elasticSearch",
  config: {
    indexTemplates: [{ name: "my-template", index_patterns: "index" }],
  },
});
await service.waitUntilRunning();

Example: Read a string property as a date, so it can be sorted and filtered on

// Only needed for a property whose objects are plain strings: one already typed `xsd:date`
// or `xsd:dateTime` is mapped as a date by the service, and keeps that mapping regardless of
// this template. The mapping lives in a component template, which takes effect only once an
// index template pulls it in by name. Field names are IRIs with every "." replaced by a space.
await dataset.addService("my-search", {
  type: "elasticSearch",
  config: {
    componentTemplates: [
      {
        name: "dates",
        template: { mappings: { properties: { "https://schema org/dateCreated": { type: "date" } } } },
      },
    ],
    indexTemplates: [{ name: "my-template", index_patterns: "index", composed_of: ["dates"] }],
  },
});

See

ServiceConfigElastic for what an Elasticsearch service accepts, and ServiceConfigJena for the Jena reasoner.

clear

clear(resourceType: DsResourceType, ...rest: DsResourceType[]): Promise<Dataset>
Deletes the named resources of this dataset, leaving the dataset itself in place.
Parameters
- resourceType: DsResourceType
  The first kind of resource to delete.
- ...rest: DsResourceType[]
  Further kinds, to clear several in one call.
Returns Promise<Dataset>
Remarks
Destructive and not undoable. Only what you name is removed — clearing "graphs" leaves the assets and services alone, and clearing "services" deletes them outright rather than emptying them. The dataset and its metadata always survive.
Example: Empty the data but keep the assets and services
```
await dataset.clear("graphs");
```

copy

copy(toAccountName: string, newDatasetName?: string): Promise<Dataset>
Copies this dataset, with its data, to another account on the same instance.
Parameters
- toAccountName: string
  Account to copy into. Your token must be allowed to write there.
- OptionalnewDatasetName: string
  Name for the copy; this dataset's name is reused when omitted.
Returns Promise<Dataset>
The new dataset, not this one.

delete

delete(): Promise<void>

Deletes this dataset, with its graphs, assets and services.

Returns Promise<void>

Remarks
Destructive and not undoable. Use Dataset.clear to empty a dataset you want to keep.

deleteGraph

deleteGraph(graphNameOrIri: string | NamedNode<string>): Promise<void>
Deletes one named graph and its statements.
Parameters
- graphNameOrIri: string | NamedNode<string>
Returns Promise<void>

Remarks
Destructive and not undoable. Resolves the graph first, so it shares Dataset.getGraph's cost and its error when the graph is absent.

describe

describe(iri: string | NamedNode<string>): Promise<Quad[]>
The instance's description of one resource.
Parameters
- iri: string | NamedNode<string>
  The resource to describe.
Returns Promise<Quad[]>
The description as RDF/JS quads.

Remarks
Answers "what does this thing look like" without needing a running service. What counts as part of the description is decided by the instance, not by this library.

ensureService

ensureService<T extends Dataset>(
    this: T,
    name: string,
    args?: NewService,
): Promise<Service>
The service with this name, created first if this dataset does not have one yet.
Type Parameters
- T extends Dataset
Parameters
- this: T
- name: string
- Optionalargs: NewService
Returns Promise<Service>

Remarks
The idempotent form of Dataset.addService. Either way the result may still be syncing, so follow it with Service.waitUntilRunning.

getAsset

getAsset(assetName: string, versionNumber?: number): Promise<Asset>
The asset with this name.
Parameters
- assetName: string
  The asset's name, as given when it was uploaded.
- OptionalversionNumber: number
  Pin the result to this version; the latest is used when omitted.
Returns Promise<Asset>

Throws
If this dataset has no asset with that name, or no such version of it.

getAssets

getAssets(): ResultIterator<AssetInfo, Asset>

This dataset's assets, as an iterator that fetches pages as you consume it.

Returns ResultIterator<AssetInfo, Asset>

getGraph

getGraph(graphNameOrIri: string | NamedNode<string>): Promise<Graph>
The named graph with this IRI.
Parameters
- graphNameOrIri: string | NamedNode<string>
  The graph's IRI, as a string or an RDF/JS named node.
Returns Promise<Graph>

Remarks
Resolved by listing the dataset's graphs and comparing IRIs, so the cost grows with the number of graphs. Prefer Dataset.getGraphs when you are going to look at several of them.

Throws
If this dataset has no graph with that IRI.

getGraphs

getGraphs(): ResultIterator<GraphInfo, Graph>

This dataset's named graphs, as an iterator that fetches pages as you consume it.

Returns ResultIterator<GraphInfo, Graph>

getInfo

getInfo(
optsOrRefresh?: boolean | { refresh?: boolean; signal?: AbortSignal },
): Promise<DatasetInfo>
This dataset's metadata: its name, description, access level, prefixes and statement counts.
Parameters
- optsOrRefresh: boolean | { refresh?: boolean; signal?: AbortSignal } = false
  true to refetch, or an object also accepting an AbortSignal.
Returns Promise<DatasetInfo>

Remarks
Cached after the first call, so repeated reads cost nothing. Pass true, or { refresh: true }, after a change made elsewhere.

getPrefixes

getPrefixes(refresh?: boolean): Promise<{ [prefixLabel: string]: string }>
Every prefix that applies to this dataset, including the instance-wide ones.
Parameters
- refresh: boolean = false
  Fetch again rather than reusing the cached result.
Returns Promise<{ [prefixLabel: string]: string }>
Prefix labels mapped to the IRIs they stand for.

Remarks
Cached after the first call, and refreshed by addPrefixes and removePrefixes.

getService

getService<T extends Dataset>(this: T, serviceName: string): Promise<Service>
The service with this name.
Type Parameters
- T extends Dataset
Parameters
- this: T
- serviceName: string
  The service's name, as given when it was created.
Returns Promise<Service>

Remarks
Being able to get a service does not mean it can answer queries — check Service.isUpToDate or wait with Service.waitUntilRunning.

Throws
If this dataset has no service with that name.

getServices

getServices(): ResultIterator<ServiceMetadata, Service>

This dataset's services, as an iterator that fetches pages as you consume it.

Returns ResultIterator<ServiceMetadata, Service>

getStatements

getStatements(
    payload: {
        graph?: string;
        object?: string;
        predicate?: string;
        subject?: string;
    },
): ResultIterator<NtriplyStatement, NtriplyStatement>
Statements matching a pattern, as an iterator that fetches pages as you consume it.
Parameters
- payload: { graph?: string; object?: string; predicate?: string; subject?: string }
  The terms to match on, each an IRI or literal in its RDF form.
Returns ResultIterator<NtriplyStatement, NtriplyStatement>

Remarks
Needs no service — this reads the stored data directly. Omitted parts of the pattern match anything, so passing {} walks the whole dataset.

graphsToFile

graphsToFile(
destinationPath: string,
opts?: { compressed?: boolean; graph?: Graph },
): Promise<void>
Writes this dataset's statements to a file.
Parameters
- destinationPath: string
  Where to write, extension included.
- Optionalopts: { compressed?: boolean; graph?: Graph }
  graph narrows the export to a single graph; compressed gzips the output.
Returns Promise<void>

Remarks
The serialisation follows the extension of destinationPath, so name it .trig or .nt rather than expecting a format argument.

graphsToStore

graphsToStore(graph?: Graph): Promise<Store<Quad, Quad, Quad, Quad>>
Loads this dataset's statements into an in-memory store.
Parameters
- Optionalgraph: Graph
  Load only this graph instead of the whole dataset.
Returns Promise<Store<Quad, Quad, Quad, Quad>>

Remarks
Everything is held in memory at once — use Dataset.graphsToStream for large data.

graphsToStream

graphsToStream(
type: "compressed" | "rdf-js",
opts?: { extension?: string; graph?: Graph },
): Promise<Readable>
Streams this dataset's statements, for data too large to hold in memory.
Parameters
- type: "compressed" | "rdf-js"
  "rdf-js" for parsed RDF/JS quads, "compressed" for the raw gzipped bytes.
- Optionalopts: { extension?: string; graph?: Graph }
  graph narrows to a single graph; extension picks the serialisation, .trig by default.
Returns Promise<Readable>

importFromDataset

importFromDataset(
fromDataset: Dataset,
args?: ImportFromDatasetArgs,
): Promise<Imports>
Copies graphs from another dataset on the same instance into this one.
Parameters
- fromDataset: Dataset
  The dataset to take graphs from.
- Optionalargs: ImportFromDatasetArgs
  Which graphs to take, and what to name them here. All graphs are taken when omitted.
Returns Promise<Imports>

Remarks
Records the link, so the imported graphs can be refreshed from the source later. For datasets on a different instance, use Account.importDataset.

Throws
If args sets both graphMap and graphNames — they are two ways of naming the same thing, so pass one.

importFromFiles

importFromFiles(
files: string[] | File[],
defaultsConfig?: JobDefaultsConfig,
): Promise<Dataset>
Loads RDF files from disk into this dataset.
Parameters
- files: string[] | File[]
  Paths, or File objects. Each file's graph comes from the file itself, so use a quad format such as TriG to control it.
- OptionaldefaultsConfig: JobDefaultsConfig
  Fallbacks for files that name no graph, and the base IRI to resolve relative IRIs against.
Returns Promise<Dataset>

Remarks
Runs as a job on the server and resolves once it has finished, so a large upload keeps the promise pending rather than returning early. Statements are added to what is already there.

Each file is parsed according to its extension rather than by sniffing its contents, and one whose extension is not recognised is skipped: the import still succeeds, and the skip is not reported back here. RDF serializations: .nt, .nq, .ttl, .trig, .n3, .jsonld, .rdf, .rdfs, .owl, .owx. Other formats, mapped to RDF on the way in: .json, .jsonl, .ndjson, .csv, .tsv, .xml, .gpx. Any of these may arrive compressed or archived as .gz, .bz2, .xz, .zip, .tar or .tgz, including combinations such as .trig.gz.

Throws
If an import is already running for this dataset in this process — they are refused rather than queued, so await the first one.

Throws
If a file makes no upload progress at all for five minutes. A stalled upload fails the import rather than being sent again, because it cannot be told apart from one the server in fact completed, and re-sending a file it already holds would leave the job with it twice.

importFromStore

importFromStore(store: Store, opts?: JobDefaultsConfig): Promise<Dataset>
Loads the contents of an in-memory store into this dataset.
Parameters
- store: Store
- Optionalopts: JobDefaultsConfig
Returns Promise<Dataset>

Remarks
Convenient for data you have just built or transformed in process. The store is written to a temporary N-Quads file and handed to Dataset.importFromFiles, so it needs room on disk and behaves the same way from there — including refusing to run beside another import.

importFromUrls

importFromUrls(
urls: string[],
defaultConfig?: JobDefaultsConfig,
): Promise<Dataset>
Loads RDF from URLs into this dataset.
Parameters
- urls: string[]
- OptionaldefaultConfig: JobDefaultsConfig
Returns Promise<Dataset>

Remarks
The server fetches each URL itself, so the data never passes through this process — the way to load something large that is already published. The URLs must be reachable from the instance.

Throws
If an import is already running for this dataset in this process.

removePrefixes

removePrefixes(
prefixLabels: string[],
): Promise<{ [prefixLabel: string]: string }>
Removes IRI prefix declarations from this dataset.
Parameters
- prefixLabels: string[]
  The aliases to remove.
Returns Promise<{ [prefixLabel: string]: string }>

Remarks
Removes only this dataset's own prefixes. A label it does not have is ignored rather than reported, so this is safe to call speculatively.

renameGraph

renameGraph(from: string, to: string): Promise<Graph>
Changes one graph's IRI, keeping its statements.
Parameters
- from: string
  The graph's current IRI.
- to: string
  Its new IRI.
Returns Promise<Graph>

Throws
If no graph has the from IRI.

setAvatar

setAvatar(
pathBufferOrFile: string | Buffer<ArrayBufferLike> | File,
): Promise<Dataset>
Replaces this dataset's image.
Parameters
- pathBufferOrFile: string | Buffer<ArrayBufferLike> | File
  Path to an image file, or its contents.
Returns Promise<Dataset>

sparqlQuery

sparqlQuery(queryString: string): SparqlResults
Runs a SPARQL query against this dataset.
Parameters
- queryString: string
  The query to run.
Returns SparqlResults
Remarks
Answered by TriplyDB's built-in engine, which reads the dataset's data directly and so needs no service. To query a service instead, use Service.sparqlQuery on it.

Nothing is sent until you pick a result form on what this returns — see SparqlResults. Every form is a single request that returns the whole result set.

This call itself never throws: an unusable query is reported by the result form you await, so a single catch covers both that and the request.

SPARQL Update goes through Dataset.sparqlUpdate instead.

Throws
From the awaited result form, if queryString is not valid SPARQL or is a SPARQL Update.
Example
```
const bindings = await dataset.sparqlQuery("select * { ?s ?p ?o } limit 10").bindings()
```
See
SPARQL 1.1 Query Language

sparqlUpdate

sparqlUpdate(updateString: string): Promise<void>
Applies a SPARQL Update to this dataset.
Parameters
- updateString: string
  The update to apply.
Returns Promise<void>
Remarks
The whole update is one transaction: either every operation in it takes effect, or none does. Queries go through Dataset.sparqlQuery instead.

Throws
If updateString is a query rather than an update.

Throws
If the instance has SPARQL Update disabled, or the token may not write to this dataset.
Example
```
await dataset.sparqlUpdate("insert data { <a:s> <a:p> <a:o> }")
```
See
SPARQL 1.1 Update

update

update(config: UpdateDataset): Promise<Dataset>
Changes this dataset's metadata.
Parameters
- config: UpdateDataset
Returns Promise<Dataset>

Remarks
Only the fields you pass are changed. This edits metadata only — the statements are untouched.

uploadAsset

uploadAsset(
fileOrPath: string | File,
opts?: { mode?: UploadAssetModes; name?: string },
): Promise<Asset>
Attaches a file to this dataset as an asset.
Parameters
- fileOrPath: string | File
  Path to the file, or a File object.
- Optionalopts: { mode?: UploadAssetModes; name?: string }
  name overrides the asset name, which otherwise is the file's own name without its directories. mode decides what happens when that name is taken: refuse (the default), replace it, or keep both by adding a version.
Returns Promise<Asset>

Remarks
Assets are stored beside the data and are not parsed as RDF, so this is where images, spreadsheets and source files belong.

Throws
If the name is taken and mode leaves it at "throw-if-exists".
uploadAsset(fileOrPath: string | File, name?: string): Promise<Asset>
Attaches a file to this dataset as an asset, under this name.
Parameters
- fileOrPath: string | File
  Path to the file, or a File object.
- Optionalname: string
  Name for the asset; the file's own name, without its directories, is used when omitted.
Returns Promise<Asset>

Throws
If an asset with that name already exists. Pass an options object with mode: "replace-if-exists" to overwrite instead.

Class Dataset

Remarks

Example: Get a dataset that already exists

Example: Create it on first run, then load a file into it

Index

Properties

Methods

Properties

slug

Methods

addPrefixes

Parameters

Returns Promise<{ [prefixLabel: string]: string }>

Remarks

addService

Parameters

Returns Promise<Service>

Remarks

Throws

Example: A search service whose index is built from your own template

Example: Read a string property as a date, so it can be sorted and filtered on

See

clear

Parameters

Returns Promise<Dataset>

Remarks

Example: Empty the data but keep the assets and services

copy

Parameters

Returns Promise<Dataset>

delete

Returns Promise<void>

Remarks

deleteGraph

Parameters

Returns Promise<void>

Remarks

describe

Parameters

Returns Promise<Quad[]>

Remarks

ensureService

Type Parameters

Parameters

Returns Promise<Service>

Remarks

getAsset

Parameters

Returns Promise<Asset>

Throws

getAssets

Returns ResultIterator<AssetInfo, Asset>

getGraph

Parameters

Returns Promise<Graph>

Remarks

Throws

getGraphs

Returns ResultIterator<GraphInfo, Graph>

getInfo

Parameters

Returns Promise<DatasetInfo>

Remarks

getPrefixes

Parameters

Returns Promise<{ [prefixLabel: string]: string }>

Remarks

getService

Type Parameters

Parameters

Returns Promise<Service>

Remarks

Throws

getServices

Returns ResultIterator<ServiceMetadata, Service>

getStatements

Parameters

Returns ResultIterator<NtriplyStatement, NtriplyStatement>

Remarks

graphsToFile