TriplyDB.js

TriplyDB.js is the official programming library for interacting with TriplyDB. TriplyDB.js allows you to automate operations that would otherwise be performed in the TriplyDB GUI.

TriplyDB.js is implemented in TypeScript. TypeScript is a type-safe language that transpiles to JavaScript. This allows you to use TriplyDB.js in web browsers as well as on servers (using Node.js). TriplyDB.js is open source and its source code is published on GitHub.

Please contact support@triply.cc for questions and suggestions.

Overview

TriplyDB.js contains several classes, each with their own methods. The documentation for every method includes at least one code example. These code examples can be run by inserting them into the following overall script.

Notice that process.env.TOKEN picks up an API token that is stored in the environment variable called TOKEN. Follow the steps on this page to create a new API token in the TriplyDB GUI.

require('source-map-support/register')
import App from '@triply/triplydb'
const triply = App.get({ token: process.env.TOKEN })
async function run() {
  // This is where the code examples in this reference section should be placed.
}
run().catch(e => {
  console.error(e)
  process.exit(1)
})
process.on('uncaughtException', function (e) {
  console.error('Uncaught exception', e)
  process.exit(1)
})
process.on('unhandledRejection', (reason, p) => {
  console.error('Unhandled Rejection at: Promise', p, 'reason:', reason)
  process.exit(1)
})

The following sections document the various TriplyDB.js classes. Each class comes with its own methods. Classes are related through methods that connect them. For example, calling the getAccount method on a App object returns an Account object.

App

Instances of the App class are specific application connections that are set-up with a TriplyDB server.

Connections to TriplyDB servers can be created with and without setting an API token. When no API token is set, the connection can be used to perform read-only operations over public data. When an API token is set, the connection can be used to perform read/write operations over public/private data the API token grants access to.

The following snippet creates an instance of the App object that establishes read-only access to the TriplyDB server at https://triplydb.com:

import App from '@triply/triplydb'
const triply = App.get({ url: 'https://api.triplydb.com' })

Notice that the URL must point to the API of the TriplyDB server that the App object connects to. The API URL is typically created by adding the api. subdomain in front of the server's host name. For example, since [1] is the web-based GUI for the TriplyDB server, then [2] is the corresponding API for that instance.

[1] https://triplydb.com
[2] https://api.triplydb.com

When an API token is specified, the operations that can be performed through the App object are determined by:

The access level of the token: either “Read access”, “Write acces”, or “Management access”.
The credentials of the user account for which the API token is created. When a user is a member of an organization, she has access to all its datasets, stories, and queries; a user always has access to her own datasets, stores and queries.

The following token access levels are available:

“Read access” allows:
- Read operations over data with access level “Public”.
- Read operations over data with access level “Internal”.
- Read operations over data with access level “Private” that belongs to the user who created the token.
- Read operations over data with access level “Private” that belongs to organizations to which the user who created the token is a member.
“Write acces” allows:
- All operations allows by “Read acces”.
- Write operations over data that has access setting “Internal”.
- Write operations over data
“Management access” allows the following operations to be performed: creating organizations, adding/removing members to/from organizations.

The following creates a App object with an API token that is made available through an environment variable (see section Setting up a secure read/write project):

import App from '@triply/triplydb'
const triply = App.get({ token: process.env.TOKEN })

It is typical for one TriplyDB.js script to have exactly one App object.

App.getAccount(name?: string)

Returns the TriplyDB account with the given name.

If name is omitted, the TriplyDB account that is associated with the current API token is returned.

Examples

The following snippet returns the account called 'Triply'.
```
const account = await triply.getAccount('Triply')
```
The following snippet returns the current account. This is the account for which the currently configured API token was created.
```
const account = await triply.getAccount()
```

App.getAccounts()

Returns an async iterator over all accounts in the TriplyDB server.

Example

The following snippet prints the display names for all accounts in the TriplyDB server at https://triplydb.com:

const triply = App.get({ url: 'https://api.triplydb.com' })
for await (const account of triply.getAccounts()) {
  console.log((await account.getInfo()).name)
}

The following snippet returns an array that contains all account objects:
```
console.log(await triply.getAccounts().toArray())
```

See class Account for an overview of the methods that can be used with account objects.

App.getInfo()

Returns information about the TriplyDB server that the App is connected to.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

Examples

The following snippet prints the contact email for the TriplyDB server:

console.log((await triply.getInfo()).contactEmail)

The following snippet returns an object describing the used TriplyDB server:

console.log(await triply.getInfo())

App.getOrganization(name: string)

Returns the TriplyDB organization with the given name.

This method is similar to App.getAccount(name?: string), but differs in the following ways:

This method only works for accounts that represent TriplyDB organizations.
This method returns an organization object. Class Organization is a specialization of class Account.

Examples

The following snippet returns the organization called 'Triply':

const organization = await triply.getOrganization('Triply')

See class Organization for an overview of the methods that can be used with organization objects.

Alternatives

This method is a shorthand for calling the following two methods:

Call method App.getAccount(name?: string) to retrieve an account object.
Then call method Account.asOrganization() to cast the account object into an organization object.

The following snippet returns the same result as the previous example, but uses two methods instead of one:

const account = await triply.getAccount('Triply')
const organization = account.asOrganization()

App.getUser(name?: string)

Returns the TriplyDB user with the given name.

If name is omitted, the TriplyDB user that is associated with the current API token is returned. This only works if an API token is configured for the current App object.

Examples

The following snippet returns the user with name 'somebody':

const user = await triply.getUser('somebody')

The following snippet returns the user for whom the API token was created. This only works if an API token was configured when the App object was created:

const me = await triply.getUser()

Alternatives

This method is a shorthand for the following two methods:

Call method App.getAccount() to retrieve an account object.
Then call method Account.asUser() to cast the account object into a user object.

The following snippet returns the same result as the previous examples, but uses two methods instead of one:

const account = await triply.getAccount('somebody')
const user = account.asUser()

App.isCompatibleWith(minimumVersion: string)

Succeeds if and only if the currently connected to TriplyDB server has a version that is identical to or higher than the given minimum version.

Arguments

Argument minimumVersion must be a string that uses Semantic Versioning. For example '1.2.3'.

Account

Instances of the Account class denote TriplyDB accounts. Accounts can be either organizations (Organization) or users (User).

Account objects are obtained by calling the following method:

App.getAccount(name?: string)

Account.addDataset(name: string, metadata?: object)

Adds a new TriplyDB dataset with the given name to the current account.

The optional metadata argument is used to specify the metadata for the dataset.

Access restrictions

Creating a new dataset only succeeds if an API token is configured that provides write access to the current account.

The default access level for a newly created dataset is private. If you want to publish a dataset with a different access level, you must specify the accessLevel key in the metadata argument.

Arguments

The name argument specifies the URL-friendly name of the new dataset. The name must only contain alphanumeric characters and hyphens ([A-Za-z0-9\-]).

The full URL of the newly created dataset has the following structure:

https://{host}/{account}/{dataset}

The metadata argument optionally specifies the access level and other important metadata:

accessLevel

The access level of the dataset. The following values are supported:

'private' (default): The dataset can only be accessed by organization members.
'internal': The dataset can only be accessed by users that are logged into the TriplyDB server.
'public': The dataset can be accessed by everybody.

When no access level is specified, the most restrictive access level (private) is used.

description

The human-readable description of the dataset. This description can make use of Markdown.

displayName

The human-readable name of the dataset. This name may contain spaces and other characters that are not allowed in the URL-friendly name.

license

The license of the dataset. The following license strings are currently supported:

'CC-BY-SA'
'CC0 1.0'
'GFDL'
'ODC-By'
'ODC-ODbL'
'PDDL'
'None' (default)

prefixes

The IRI prefix declarations that are configured for the dataset. This is specified as a dictionary object whose keys are aliases and whose values are IRI prefixes.

Examples

The following snippet creates a new dataset called 'iris' under the account called 'Triply':

The dataset has private access, because the access level is not specified explicitly.
The dataset has a description.
The dataset has a display name.
The dataset has the PDDL license.

const account = await triply.getAccount('Triply')
const dataset = await account.addDataset('iris', {
  description: 'A multivariate dataset that quantifies morphologic variation of Iris flowers.',
  displayName: 'Iris',
  license: 'PDDL',
  name: 'iris',
  prefixes: {
    def: 'https://triplydb.com/Triply/iris/def/',
    id: 'https://triplydb.com/Triply/iris/id/',
  },
})

Account.addQuery(name: string, metadata: object)

Adds a new SPARQL query to the account.

Arguments

Required:

name: string: The URL-friendly name of the new query. The name must only contain alphanumeric characters and hyphens ([A-Za-z0-9\-]).
queryString: string: The SPARQL query string (e.g., 'select * { ?s ?p ?o }').
dataset: Dataset: An instance of class Dataset that the current API token gives access to.
service: Service: An instance of class Service that the current API token gives access to and that you want to be associated with this query. The Service given will be used as a preferred service for this query.

Optional:

The metadata argument specifies the required Dataset or Service and access level. Other important metadata can be set optionally:

accessLevel

The access level of the query. If none is set it defaults to 'private'. The following values are supported:

'private': The query can only be accessed by the Account object for which it is created.
'internal': The query can only be accessed by people who are logged into the TriplyDB server.
'public': The query can be accessed by everybody.

description: string

A human-readable description of the query.

displayName: string

The human-readable name of the query. This name may include spaces and other characters that are not allowed in the URL-friendly name.

output: string

The visualization plugin that is used to display the result set of the query. If none is set it defaults to 'table'.

'boolean': The [boolean](https://triply.cc/docs/yasgui#table) view is a special view for ask queries. The value is either 'true' or 'false', and is visualized as `X`(False) or `V`(True).
'gallery': The [gallery](https://triply.cc/docs/yasgui#gallery) view allows SPARQL results to be displayed in an HTML gallery.
'gchart': The [gchart](https://triply.cc/docs/yasgui#charts) renders geographical, temporal and numerical data in interactive charts such as bar-, line- and pie charts.
'geo': The [geo](https://triply.cc/docs/yasgui#geo) allows SPARQL results that contain GeoSPARQL semantics to be automatically interpreted and displayed on a 2D map.
'geoEvents': The [geoEvents](https://triply.cc/docs/yasgui#geoEvents) plugin renders geographical events as a story map.
'geo3d': The [geo3d](https://triply.cc/docs/yasgui#geo3d) allows SPARQL results that contain GeoSPARQL semantics to be automatically interpreted and displayed on a 3D globe.
'markup': The [markup](https://triply.cc/docs/yasgui#markup) can be used to render a variety of markup languages. This requires the use of the `?markup` variable to identify which variable to render.
'network': The [network](https://triply.cc/docs/yasgui#network) renders SPARQL Construct results in a graph representation. The maximum amount of results that can be visualized is 1.000 due to performance.
'pivot': The [pivot](https://triply.cc/docs/yasgui#pivot) view renders SPARQL results in an interactive pivot table where you are able to aggregate the results by dragging your binding variables to columns or rows.
'response': The [response](https://triply.cc/docs/yasgui#response) view shows the body of the response and offers a easy way to download the result as a file.
'table': The [table](https://triply.cc/docs/yasgui#table) view allows SPARQL results to be displayed in a table. Each column in the table corresponds to a variable that belongs to the outer projection.
'timeline': The [timeline](https://triply.cc/docs/yasgui#timeline) timeline renders the SPARQL results on a Timeline.

variables: Variable[]

A list of objects with the following keys:

IRI variable: An object of the form Variable (see below)

Instances of Variable are objects that can have the following keys:

Required:

name: string: A SPARQL variable name. The variable name must appear in the query string. The question mark (?) or dollar sign ($) is not included.
termType: 'Literal'|'NamedNode': The kind of variable. This must be either 'Literal' for literals or 'NamedNode' for IRIs.

Optional:

allowedValues: string[]: The list of string values that is allowed for this variable.
datatype: string (if termType='Literal'): The datatype IRI for the literal variable.
language: string (if termType='Literal'): The language tag for the literal variable. Setting this implies that the dataset IRI is rdf:langString.
defaultValue: string: The default string value for the
required: boolean: Whether a query request must include an explicit value for this variable. The default value is false.

Example

The following snippet creates a query with the given query string:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const myDataset = await user.getDataset('my-dataset')
const query = await user.addQuery('my-query', {
  dataset: myDataset,
  queryString: 'select (count(*) as ?n) { ?s ?p ?o. }',
  output: 'response',
})

Account.addStory(name: string, metadata?: object)

Adds a new data story.

Required

name: string: The URL-friendly name of the data story. The name must only contain alphanumeric characters and hyphens ([A-Za-z0-9\-]).

Optional

accessLevel

The access level of the dataset. If none is given the default of 'private' is used. The following values are supported:

'private': The dataset can only be accessed by the Account object for which it is created.
'internal': The dataset can only be accessed by people who are logged into the TriplyDB server.
'public': The dataset can be accessed by everybody.

content: StoryElementUpdate[]

A list of story elements. The building blocks of the Story.

displayName: string

The human-readable name of the data story. This name may include spaces and other characters that are not allowed in the URL-friendly name.

A story element is an object with the following keys:

caption: string: The caption is an explanatory text about a specific query.
id: string: Each Story element gets an Id when it is created. When you want to update a Story element you will need this Id. The Id is only required when updating an element and not needed when adding an object.
paragraph: string: The Markdown content of a story paragraph. Only allowed when the type is set to 'paragraph'
query: Query: An instance of class Query.
queryVersion: number: The version that is used of the specified query.
type: Either 'paragraph' or 'query'.

Examples

Example 1 - creates a new story that has access level 'private':

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const newStory = await user.addStory('name-of-story')

Example 2 - creates a new story that has access level 'public':

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const newStory = await user.addStory('name-of-story', {
  accessLevel: 'public',
})

Account.asOrganization()

Casts the TriplyDB account object to its corresponding organization object.

Class Organization is a specialization of class Account.

Calling this method on an Organization object does nothing.

Examples

The following snippet retrieves the account named 'Triply' and casts it to an organization:

const account = await triply.getAccount('Triply')
const organization = account.asOrganization()

Alternatives

This method is not needed if the organization is directly retrieved with the specialization method App.getOrganization(name: string).

The following snippet returns the same result as the above example, but in a more direct way:

const organization = await triply.getOrganization('Triply')

Account.asUser()

Casts the TriplyDB account object to its corresponding user object.

Class User is a specialization of class Account.

Calling this method on a User object does nothing.

Examples

The following snippet retrieves the account that represents the current user, and casts it to a user object:

const account = await triply.getAccount()
const user = account.asUser()

Alternatives

This method is not needed if the user is directly retrieved with the specialization method App.getUser(name?: string).

The following snippet returns the same result as the above example, but in a more direct way:

const user = await triply.getUser()

Account.ensureDataset(name: string, metadata?: object)

Ensures the existence of a dataset with the given name and with the specified metadata if given.

Calling this method ensures that the necessary changes (if any) are made in the connected-to TriplyDB server that result in an end state in which a dataset with the given name and metadata exists.

This method is useful in practice, because it removes the burden on the programmer to have to write custom code for checking for the existence of a dataset, and conditionally create a new dataset or make metadata changes to an existing dataset.

The changes made as a result of calling this method depend on the current state of the connected-to TriplyDB server:

If this account does not yet have a dataset with the given name, then the behavior is identical to calling Account.addDataset(name: string, metadata?: object) with the same arguments.
If this account already has a dataset with the given name and with the same metadata, then this method makes no changes.

Example

const account = await triply.getAccount('Triply')
const myDataset = await account.ensureDataset(`my-dataset`, {
  license: 'PDDL',
})

Account.getDataset(name: string)

Returns the dataset with the given name that is published by this account.

Examples

The following snippet prints the name of the Iris dataset that is published by the Triply account:

const account = await triply.getAccount('Triply')
const dataset = await triply.getDataset('iris')
console.log((await dataset.getInfo()).name)

Account.getDatasets()

Returns an async iterator over the accessible datasets for the current account.

Access restrictions

The iterator only includes datasets that are accessible for the current connection with a TriplyDB server:

If no API token is configured, the iterator will include all and only public datasets belonging to this account.
If an API token is configured, the iterator will include all public and internal datasets belonging to this account, and will include all private datasets belonging to this account if the API token gives read access to the account.

Examples

The following snippet prints the names of all accessible dataset under the Triply account:

const account = await triply.getAccount('Triply')
for await (const dataset of account.getDatasets()) {
  console.log((await dataset.getInfo()).name)
}

The following snippet prints the list of names of all accessible datasets under the Triply account:

const account = await triply.getAccount('Triply')
console.log(await account.getDatasets().toArray())

Account.getInfo()

Returns information about this account.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

The information object for accounts includes the following keys:

avatarUrl: A URL to the account image.
accountName: The URL-friendly name of the account.
name: The human-readable display name of the account
description: The human-readable description of the account.
createdAt: The date and time on which the account was created.
datasetCount: The number of datasets for the account.
queryCount: The number of queries for the account.
storyCount: The number of stories for the account
pinnedDatasets: An array containing the pinned dataset for the account.
pinnedItems: An array containing the pinned items (datasets, stories and queries) for the account.
type: The account type: either organization or user.
role: The role of the account
orgs: An array of organizations of which the account is a member.
Email address: The email address of the account.
updatedAt: The date and time on which the account was last updated.
lastActivity: The date and time on which the account was last online on TriplyDB.

Examples

The following snippet prints the full information object for the account called ‘Triply’:

const account = await triply.getAccount('Triply')
console.log(await account.getInfo())

The output for this snippet can look as follows:

{
  'accountName': 'Triply',
  'avatarUrl': 'https://www.gravatar.com/avatar/9bc28997dd1074e405e1c66196d5e117?d=mm',
  'createdAt': 'Mon Mar 19 2018 14:39:18 GMT+0000 (Coordinated Universal Time)',
  'datasetCount': 16,
  'name': 'Triply',
  'queryCount': 37,
  'storyCount': 7,
  'type': 'org',
  'updatedAt': 'Tue Nov 27 2018 09:29:38 GMT+0000 (Coordinated Universal Time)'
}

The following snippet prints the name of the account called ‘Triply’:

const account = await triply.getAccount('Triply')
console.log((await account.getInfo()).name)

Account.getPinnedItems()

Returns the list of datasets, stories and queries that are pinned for the current account.

A pinned item is an item that is displayed in a prominent way on the account web page.

Order considerations

The order in which the pinned datasets are returned reflects the order in which they appear on the organization homepage (from top-left to bottom-right).

Examples

The following snippet prints the names of the items that are pinned on the Triply account page:

const account = await triply.getAccount('Triply')
for await (const item of account.getPinnedItems()) {
  console.log((await item.getInfo()).name)
}

Account.getQuery(name: string)

Returns the TriplyDB query with the given name.

Examples

The following snippet prints the query string for a query called animal-gallery that belongs to the account called Triply:

const account = await triply.getAccount('Triply')
const query = await account.getQuery('animal-gallery')
console.log((await query.getInfo()).requestConfig?.payload.query)

Account.getQueries()

Returns an async iterator over the accessible queries that belong to the account.

Access restrictions

The iterator only includes datasets that are accessible for the current connection with a TriplyDB server:

If no API token is configured, the iterator will include all and only public queries belonging to this account.
If an API token is configured, the iterator will include all public and internal queries that belong to this account, and will include all private queries that belong to this account if the API token gives read access to the account.

Examples

The following snippet prints the names of the queries that belong to the account called Triply:

const account = await triply.getAccount('Triply')
for await (const query of account.getQueries()) {
  console.log((await query.getInfo()).name)
}

Account.ensureStory(name: string, metadata: object)

Ensures the existence of a story with the given name and with the specified metadata, if given.

Calling this method ensures that the necessary changes (if any) are made in the connected-to TriplyDB server that result in an end state in which a story with the given name and metadata exists.

This method is useful in practice, because it removes the burden on the programmer to have to write custom code for checking for the existence of a story, and conditionally create a new story or make metadata changes to an existing story.

The changes made as a result of calling this method depend on the current state of the connected-to TriplyDB server:

If this account does not yet have a story with the given name, then the behavior is identical to calling Account.addStory(name: string, metadata?: object) with the same arguments.
If this account already has a story with the given name and with the same metadata, then this method returns that story.

Optional

displayName: Accepts a string value to be used as the display name for the story.
accessLevel: Accepts either of the following values: 'private' (default), 'internal', 'public'.
content: Accepts a list of StoryElementUpdate objects, defined below.

Note: If no accessLevel is specified, the default used is 'private'.

Examples

Example 1: To ensure a Story only requires a name of type string. It's access level will default to private

await someUser.ensureStory(`someStoryName`)

Example 2: Ensure a Story setting it's accessLevel and displayName.

await someUser.ensureStory(`someStoryName`, {
  accessLevel: 'public',
  displayName: `This is a Story`,
})

Account.addStory(name: string, newStoryOptions?: object)

Required

Adds and returns the TriplyDB story with the given name.

Optional

The optional new story object that can be passed accepts the following properties:

displayName: Accepts a string value to be used as a display name for the story
accessLevel: Sets the access level for the story. Accepts either of the following: 'private' (default), 'internal', 'public'.

If no accesslevel is specified, the default value private is used.

Examples:

Example 1 - creates a newStory that is 'private'

const newStory = await someUser.addStory('name-of-story')

Example 2 - creates a newStory that is 'public'

const newStory = await someUser.addStory('name-of-story', {
  accessLevel: 'public',
})

Account.getStory(name: string)

Returns the TriplyDB story with the given name.

Examples

The following snippet prints the paragraphs in the story called the-iris-dataset that is published under the account called Triply. Stories are sequences of paragraphs and queries. This program prints the paragraphs in the sequence in which they appear in the story.

const account = await triply.getAccount('Triply')
const story = await account.getStory('the-iris-dataset')

Account.getStories()

Returns an iterator with the TriplyDB stories that belong to the account.

Examples

The following snippet prints the names of the queries that belong to the Triply account:

const account = await triply.getAccount('Triply')
for await (const story of account.getStories()) {
  console.log((await story.getInfo()).name)
}

Account.pinItems(items: array[Dataset|Story|Query])

Pins the given datasets, stores, and/or queries to the home page of this account.

The pinned elements can be seen by people who visit the account online. They are also included in the account metadata.

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const query = await user.getQuery('name-of-query')
const newStory = await user.getStory('name-of-story')
user.pinItems([query,newStory])

Account.setAvatar(file: string)

Sets a new image that characterizes this account.

A circular version of this image is displayed inside the TriplyDB GUI. This image is also published as part of account metadata.

Examples

The following snippet uploads the local image in file logo.svg and set it as the characterizing image for the Triply account:

const account = await triply.getAccount('Triply')
await account.setAvatar('logo.svg')

Account.update(metadata: object)

Updates the metadata for this account.

To update the metadata profile with information within the metadata itself, we need the following steps:

Obtain the relevant piece of information as a variable/const: getObject()
Update the metadata profile with the obtained information stored in the variable/const: update()

getObject() Define a constant (const) and assign it to ctx.store.getObjects(). The arguments for the function will be the subject, predicate, and graph. The function retrieves the object so the other 3 parts of a quad need to be specified.

update() Update the relevant part of the metadata profile with the corresponding piece of information. .update({})

Example If one wants to update the display name of a metadata profile with the object of the following triple within the metadata: <https://example.org/example> <https://schema.org/name> 'Example Name'@en

async (ctx) => {
  // Fetch displayName
  const displayName = ctx.store
    .getObjects(
      'https://example.org/example',
      'https://schema.org/name',
      graph.metadata
    )
    .find(
      (node) => node.termType === 'Literal' && node.language === 'en'
    )?.value;

  // Specify the environment variable, if necessary
  const _dataset =
    process.env['MODE'] === 'Production'
      ? (await app.triplyDb.getOrganization(organization)).getDataset(dataset)
      : (await app.triplyDb.getUser()).getDataset(organization + '-' + dataset)

  // Update the display name
  if (displayName) await (await _dataset).update({ displayName })
};

The metadata object for accounts can include the following keys:

accountName: The URL-friendly name of the account.
name: The human-readable display name of the account
description: The human-readable description of the account.
pinnedItems: An array containing the pinned items (datasets, stories and queries) for the account.
Email address: The email address of the account.

Asset

Not all data can be stored as RDF data. For example images and video files use a binary format. Such files can also be stored in TriplyDB as Assets and can be integrated into the Knowledge Graph. Each asset has a specific identifier that can be used in the Knowledge Graph.

An asset is always uploaded per dataset, for which the function uploadAsset() is used. see Dataset.uploadAsset() for uploading an asset.

If the asset already has been created following functions can retrieve it from the dataset.

TriplyDB.js supports several functions to manipulate an asset on TriplyDB.

Asset.addVersion(path: File | string)

Update an asset with a new version of the document using the addVersion function. The input of this function is a path to the file location that you want to update the asset with. The file you want to add as a new version does not in any ways have to correspond to the asset.

Example

The following snippet uploads the an file my-file.pdf and upload it as the new version of the asset:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
await asset.addVersion('my-file.pdf')

Asset.delete()

To delete an asset with all of its versions execute the delete() function.

Example

The following snippet uploads the an file my-file.pdf and upload it as the new version of the asset:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
await asset.delete()

Asset.getInfo(version?: number)

Returns information about this asset.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

Optionally you can give the version number to retrieve the assetInfo of a particular version.

The information object for assets includes the following keys:

assetName: The URL-friendly name of the asset.
identifier: The hexadecimal identifier of the asset
createdAt: The date and time on which the asset was created.
url: The url of the asset.
versions: An array containing all versions of the asset.
uploadedAt: The date and time on which the asset was uploaded.
fileSize: Number with the bytesize of the asset

Examples

The following snippet prints the full information object for the asset called ‘my-asset’:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
console.log(await asset.getInfo())

Asset.getVersionInfo(version: number)

Returns version specific information about this asset.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

The version specific information object for assets includes the following keys:

id: The hexadecimal identifier of the asset
fileSize: Number with the bytesize of the asset
url: The url of the asset.
uploadedAt: The date and time on which the asset was uploaded.

Examples

The following snippet prints the version information object for the asset called ‘my-asset’ at version 1:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
console.log(await asset.getVersionInfo(1))

Asset.selectVersion(version: number)

With the selectVersion() function you can select a specific version of an Asset. Each version corresponds to a iteration of the file that is added as an asset. The argument of the selectVersion() function is a number of the version you want to retrieve.

Example

To select the first asset from the list of assets use the selectVersion with the argument 1.

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
const versionedAsset = asset.selectVersion(1)

Asset.toFile(path: string, version?: number)

The binary representation of an asset can be retrieved and written to file via the asset.toFile() function. This function takes as input a string path to the download location and optionally a version number.

Example

To download the latest version of my-asset asset to the file my-file-location.txt.

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
asset.toFile('my-file-location.txt')

Asset.toStream(version?: number)

If instead of downloading the asset to a file for later usage you want to directly use the asset. The toStream() functionality is available. This downloads the asset as a stream for use in a script. The toStream() has as optional argument a version number.

Example

To get the latest version of my-asset asset as a stream available.

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('my-dataset')
const asset = await dataset.getAsset('my-asset')
asset.toStream()

Dataset

The Dataset class represents a TriplyDB dataset.

Dataset.addPrefixes(prefixes: object)

Adds IRI prefix declarations to the dataset.

The prefixes argument is a dictionary object whose keys are aliases and whose values are IRI prefixes.

Examples

The following snippet adds prefix declarations for aliases id and def to the Iris dataset:

const organization = await triply.getOrganization('Triply')
const dataset = await organization.getDataset(iris)
await dataset.addPrefixes({
  def: 'https://triplydb.com/Triply/iris/def/',
  id: 'https://triplydb.com/Triply/iris/id/',
})

Dataset.ensureService(name: string, metadata?: object)

Ensures the existence of a service with the given name and with the specified metadata if given.

Calling this method ensures that the necessary changes (if any) are made in the connected-to TriplyDB server that result in an end state in which a service with the given name and metadata exists.

This method is useful in practice, because it removes the burden on the programmer to have to write custom code for checking for the existence of a service, and conditionally create a new service or make metadata changes to an existing service.

The changes made as a result of calling this method depend on the current state of the connected-to TriplyDB server:

If this dataset does not yet have a service with the given name, then the behavior is identical to calling Dataset.addService(name: string, metadata?: object) with the same arguments.
If this dataset already has a service with the given name, but with different metadata specified for it, then the behavior is identical to calling Account.getDataset(name: string) and Dataset.update(metadata: object).
If this dataset already has a service with the given name and with the same metadata, then this method returns that service.

Required

name: Accepts a string value which is the name of the service to ensure.

Optional: metadata

serviceMetadata = {
  type:  'elasticsearch' | 'virtuoso' | 'jena' ;
  config?: {
    reasoner?: 'OWL' | 'RDFS' | 'None';
  };
};

type

Accepts a string value of one of the following: 'virtuoso', 'elasticsearch', 'jena'.

config

Config is an optional property. It accepts an object with a reasoner property.

reasoner: The reasoner property accepts a string value of either 'OWL', 'RDFS', or 'None'.

Note:

If no options are specified the default service is of type: virtuoso.
Note that the config.reasoner will only accept a value when type is: 'jena'

Examples Example 1: Ensure a service with no arguments. If not found it's type defaults to virtuoso.

await someDataset.ensureService('someServiceName')

Example 2: Ensure a service of type jena.

await someDataset.ensureService('someServiceName', { type: 'jena' })

Dataset.addService(name: string, metadata?: object)

Creates a new service for this dataset.

Arguments

Required

name: The URL-friendly name of the service. The name must only contain alphanumeric characters and hyphens (`[A-Za-z0-9\-]`).

Optional

The service type is specified with the type parameter. If no type is given, a default of 'virtuoso' is used. It supports the following values:

'virtuoso': Starts a SPARQL service. A SPARQL 1.1 compliant service is very scalable and performance, but without advanced reasoning capabilities.
'jena': Starts a SPARQL JENA service. A SPARQL 1.1 compliant service that is less scalable and less performant, but allows reasoning (RDFS or OWL) to be enabled.
'elasticSearch': Starts an Elasticsearch service. A text search engine that can be used to power a search bar or similar textual search API.

The name argument can be used to distinguish between different endpoints over the same dataset that are used for different tasks.

Examples

The following snippet starts two SPARQL endpoints over a specific dataset. One endpoint will be used in the acceptance environment while the other endpoint will be used in the production system.

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const acceptance = await dataset.addService('acceptance')
const production = await dataset.addService('production', {
  type: 'elasticsearch',
})
const reasoning = await dataset.addService('reasoning', {
  type: 'jena',
  config: { reasoner: 'OWL' },
})

Dataset.clear(...resourceType: string)

Removes one or more resource types from the current dataset.

Arguments

The resources are specified by the rest parameter resourceType, which supports the following values :

'assets': Removes all assets in the dataset.
'graphs': Removes all graphs in the dataset.
'services': Removes all services in the dataset.

Examples

The following example code removes all graphs and services for a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.clear('graphs', 'services')

Dataset.copy(account: string, dataset: string)

Creates a copy of the current dataset.

The owner (user or organization) of the copy is specified with parameter account. The name of the copy is specified with parameter dataset.

This operation does not overwrite existing datasets: if the copied-to dataset already exists, a new dataset with suffix -1 will be created.

Examples

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
console.log(await dataset.copy('account name', 'copy dataset name'))

Dataset.delete()

Deletes the dataset.

This includes deleting the dataset metadata, all of its graphs, all of its services, and all of its assets.

Examples

The following snippet deletes a specific dataset that is part of the account associated with the current API token:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.delete()

Dataset.deleteGraph(name: string)

Deletes the graph with the given name from this dataset.

Graph names are IRIs.

Examples

The following snippet deletes a specific graph from a specified dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.deleteGraph('https://example.org/some-graph')

Dataset.describe(iri: string|NamedNode)

Each dataset is a collection of triples that describe objects in linked data. Each object is defined with an IRI, an identifier for that object. An object often has incoming and outgoing connections. The Dataset.describe() call can retrieve the incoming and outgoing triples per object. The function returns for a given iri a list of quads where the iri is either in the subject or the object position.

Examples

The following snippet returns all triples that have https://example.org/id/some-instance in the subject or the object position:

const user = await triply.getUser()
const dataset = await account.getDataset('my-dataset')
console.log(await dataset.describe('https://example.org/id/some-instance'))

Dataset.getAsset(name: string, version?: number)

Returns the asset with the given name for this dataset.

Optionally allows the version number (version) of the asset to be specified. If the version number is absent, the latest version of the assert with the given name is returned.

Examples

The following snippet returns the original version of an image of a dog from the animals dataset:

const user = await triply.getUser()
const dataset = user.getDataset('my-dataset')
const asset = await dataset.getAsset('file.png', 1)

Dataset.getAssets()

Returns an async iterator over the assets that belong to this dataset.

Assets are binary files that are stored together with data graphs. Common examples include documents, images and videos.

Examples

The following snippet prints the assets for a specific dataset:

const user = await triply.getUser()
const dataset = user.getDataset('my-dataset')
for await (const asset of dataset.getAssets()) {
  console.log(asset)
}

The following snippet prints the list of assets for a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
console.log(await dataset.getAssets().toArray())

Dataset.getGraph(name: string)

Each dataset with data consists out of one or more named graphs. All graphs together are thus the collection of triples of the dataset. Often the graph is used to denote a part of the dataset. For example the data model of the dataset or the metadata of the dataset. Instead of searching over the complete dataset where you want to scope it to a certain graph you can use the getGraph() function to specify the graph.

Dataset.getGraph(name: string) returns the graph with the given name that belongs to this dataset. The name is the string representation of the graph IRI.

The Dataset.getGraph returns a graph object.

Examples

The following snippet returns the graph about cats from the dataset about animals:

const user = await triply.getUser()
const dataset = await user.getDataset('animals')
const graph = dataset.getGraph('https://example.com/cats')

Dataset.getGraphs()

Returns an async iterator over graphs that belong to this dataset.

Examples

The following snippet retrieves the graphs for a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
console.log(await dataset.getGraphs().toArray())

Dataset.getInfo()

Returns information about this dataset.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

Examples

The following snippet prints the information from the specified dataset of the current user:

const user = await triply.getUser()
const dataset = await user.getDataset('my-dataset')
console.log(await dataset.getInfo())

Dataset.getPrefixes()

Returns the prefixes that are defined for this dataset.

This contains prefix declarations that are generic and configured for this TriplyDB server, and prefix declarations that are defined for this specific dataset.

Examples

The following snippet prints the prefix declarations that hold for my-dataset:

const user = await triply.getUser()
const dataset = user.getDataset('my-dataset')
for await (const prefix of dataset.getPrefixes()) {
  console.log(prefix)
}

Dataset.getService(name: string)

Returns the service with the given name for this dataset.

Examples

The following snippet retrieves the acceptance service for the product catalog of an imaginary company:

const organization = triply.getOrganization('some-company')
const dataset = organization.getDataset('product-catalog')
const service = dataset.getService('acceptance')

Dataset.getServices()

Returns an async iterator over TriplyDB services under a dataset.

See class Service for an overview of the methods for service objects.

Examples

The following snippet emits the services that are enabled for a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
for await (const service of dataset.getServices()) {
  console.log(service)
}

If you do not want to iterate over the services with an async iterator, but instead want to get an array of services use the .toArray() call instead:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
console.log(await dataset.getServices().toArray())

Dataset.getStatements({subject?: string, predicate?: string, object?: string, graph?: string})

Returns an async iterator with statements (quadruples) that fit the specified pattern.

Arguments

subject, if specified, is the subject term that should be matched.
predicate, if specified, is the predicate term that should be matched.
object, if specified, is the object term that should be matched.
graph, if specified, is the graph name that should be matched.

Example

The following prints all statements in the dataset:

const user = triply.getUser()
const dataset = await user.getDataset('my-dataset')
for await (const statement of dataset.getStatements()) {
  console.log(statement)
}

The following prints the description of the Amsterdam resource in the DBpedia dataset:

const association = triply.getOrganization('DBpedia-association')
const dbpedia = association.getDataset('dbpedia')
for await (const statement of dbpedia.getStatements({subject: 'http://dbpedia.org/resource/Amsterdam'})) {
  console.log(statement)
}

Get the data locally

Most of the time you do not need to download the entire dataset locally as TriplyDB supports a variety of methods to use linked data directly. But if you want to use the entire graph locally that is possible with TriplyDB.js. There are three methods to retrieve linked data from TriplyDB. graphsToFile(), graphsToStore() and graphsToStream().

Dataset.graphsToFile(destinationPath: string, arguments?: object)

The first method downloads the linked data graphs directly and writes the data to the location of the destinationPath. The extension on the destinationPath defines the linked data type that is downloaded. The extensions that are supported are: nt, nq, trig, ttl, jsonld, json. If no extension is set or the extension is not recognized the function will throw an error.

Optional

The optional properties accepted as arguments for graphsToFile

Compressed: Argument compressed optionally is a boolean defining if a graph is compressed with GNU zip (gzip) compression algorithm and will end with a `.gz` extension.
Graph: Argument Graph optionally is an specific graph that you want to write to file. These graph is an instance of a 'Graph' class

Examples

The following example downloads the dataset to file:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
await dataset.graphsToFile('my-filename.ttl', {compressed: true})

Dataset.graphsToStore(graph?: Graph)

The second method is to download the file into a N3.store. The n3 library is one of the most complete libraries for handling linked data in memory. The N3.js library is an implementation of the RDF.js low-level specification that lets you handle RDF in JavaScript easily, with an asynchronous, streaming approach.

To reduce the overhead of downloading your data to file and then insert it in the N3 Store. TriplyDB.js has a graphsToStore() where a N3 store is returned as a result of the graphsToStore() function.

Optional

The optional argument for graphsToStore is Graph. With Graph you can optionally define a specific graph that you want to write to file. These graph is an instance of a 'Graph' class.

Examples

The following example downloads the dataset as N3.store:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const store = await dataset.graphsToStore()

Dataset.graphsToStream(type: 'compressed' | 'rdf-js', arguments?: object)

The final method to download linked data to a local source is the graphsToStream this function returns a stream of quads that can directly be iterated over. The Stream is either of the type compressed which returns a gzipped stream of linked data, or type rdf-js which returns a stream of quads parsed according to the rdf-js standard.

Optional

The following arguments can be defined in the optional arguments object.

Extension: Argument Extension optionally defines the linked data type that is streamed. The extensions that are supported are: `nt`, `nq`, `trig`, `ttl`, `jsonld`, `json`.
Graph: Argument Graph optionally is an specific graph that you want to write to file. This graph is an instance of a 'Graph' class

Examples

The following example streams through the dataset as rdf-js quad objects and prints the quad to the screen. Notice that the stream is an async iterator.

Example 1

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const stream = await dataset.graphsToStream('rdf-js', {extension: '.nq'})
for await(const quad of stream){
  console.log(quad)
}

The following example streams through the dataset as chunks of ttl. and prints the buffer to the screen.

Example 2

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const stream = await dataset.graphsToStream('compressed', {extension: '.ttl'})
for await(const quad of stream.pipe(zlib.createGunzip())){
  console.log((quad as Buffer).toString())
}

Dataset.importFromDataset(fromDataset: Dataset, arguments?: object)

Imports one or more named graphs from a different dataset into this dataset.

Data reuse is an important principle in linked data. This functionality makes it very easy to pull in vocabularies and datasets from other places.

Changes in the fromDataset dataset are not automatically reflected in this dataset. If you want to synchronize with changes made in the imported-from dataset, the graphs must be explicitly imported. This protects this dataset against unanticipated changes in the imported-from dataset, while still being able to stay in sync with the imported-from dataset if this is explicitly requested.

Required

Argument fromDataset is the dataset object from which one or more graphs are imported over to this dataset.

Optional

The optional properties accepted as arguments for importFromDataset

graphMap: Argument `graphMap` optionally is an object with keys and values that implements a mapping from existing graph names (keys) to newly created graph names (values). Each key must be an existing graph name in the `from` dataset. Each value must be the corresponding graph name in this dataset. If this argument is not specified, then graph names in the `from` dataset are identical to graph names in this dataset. Note that either graphNames or graphMap can be given as optional argument and not both.
graphNames: Argument `graphNames` optionally is an array of graph names. These names can be one of three types: 'string', instances of a 'Graph' class, or instances of 'NamedNodes'. Note that either graphNames or graphMap can be given as optional argument and not both.
overwrite: Accepts a Boolean value. An optional property that determines whether existing graph names in this dataset are allowed to be silently overwritten. If this argument is not specified, then `false` is used as the default value.

Examples

The following snippet creates a new dataset (newDataset) and imports one graph from an existing dataset (existingDataset). Notice that the graph can be renamed as part of the import.

Example 1 Imports the complete 'existingDataset' dataset to the 'newDataset'.

const account = await triply.getAccount()
const existingDataset = await account.getDataset('existingDataset')
const newDataset = await account.addDataset('newDataset')
await newDataset.importFromDataset(existingDataset)

Example 2 Imports 'anotherDataset' dataset to a 'newDataset' Where a graph from the existing dataset is renamed to the a graphname in the new dataset. Only the graphs from the graphMap are imported.

const account = await triply.getAccount()
const anotherDataset = await account.getDataset('anotherDataset')
const newDataset = await account.addDataset('newDataset')
await newDataset.importFromDataset(anotherDataset, { graphMap:
  { 'https://example.org/existingDataset/graph':  'https://example.org/newDataset/graph'}
})

Example 3 Import 'oneMoreDataset' dataset to the 'newDataset' Where a graph specific graph from the existing dataset is added to the new dataset. If the graph name already occurs in the 'newDataset' it will get overwritten.

const account = await triply.getAccount()
const oneMoreDataset = await account.getDataset('oneMoreDataset')
const newDataset = await account.addDataset('newDataset')
await newDataset.importFromDataset(oneMoreDataset, {
  graphNames: ['https://example.org/existingDataset/graph'],
  overwrite: true,
})

Dataset.importFromFiles(files: list(string || File), defaultsConfig?: object)

Required

Imports one or more files into this dataset.

The files must contain RDF data.

Optional: defaultsConfig: object

defaultGraphName: Accepts a string value that is set as the default graph name for each imported file
baseIRI: Accepts a string value that is set as the default baseIRI for each imported file
overwriteAll: Accepts a boolean value that overwrites previously added graph names or baseIRIs (regardless of whether they came from a URL or a file)

Supported files

The files must contain RDF data and must be encoded in one of the following standardized RDF serialization formats: N-Quads, N-Triples, TriG, Turtle.

Examples

Example 1

const account = await triply.getAccount('Triply')
const dataset = await account.getDataset(iris)
await dataset.importFromFiles('test.nt')
await dataset.importFromFiles(['file.nq', 'file.tar.gz'])

Example 2

const account = await triply.getAccount('Triply')
const dataset = await account.getDataset(iris)
await dataset.importFromFiles('test.nt')
await dataset.importFromFiles(['file.nq', 'file.tar.gz'], {
  defaultGraphName: 'https://triplydb.com/Triply/example/graph/default',
  overwriteAll: true,
})

Dataset.importFromStore(store: n3.Store, defaultsConfig?: object)

One of the most complete libraries for handling linked data in memory is the n3 library. The N3.js library is an implementation of the RDF.js low-level specification that lets you handle RDF in JavaScript easily, with an asynchronous, streaming approach.

To reduce the overhead of converting your data from the N3 Store to a file and uploading to TriplyDB. TriplyDB.js has a importFromStore() where a N3 store is given as first argument and uploaded directly to triplyDB.

Examples

const store = new Store()
store.addQuad(DataFactory.namedNode('https://triplydb.com/id/me'),DataFactory.namedNode('http://www.w3.org/2000/01/rdf-schema#label'),DataFactory.literal('me'),DataFactory.namedNode('https://triplydb.com/Triply/example/graph/default'))

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const dataset = (await user.getDatasets().toArray())[0]
dataset.importFromStore(store)

Dataset.importFromUrls(urls: list(string), defaultsConfig?: object)

Required

Imports one or more URLs into this dataset.

The URLs must provide access to RDF data.

Optional: defaultsConfig: object

defaultGraphName: Accepts a string value that is set as the default graph name for each imported URL
baseIRI: Accepts a string value that is set as the default baseIRI for each imported URL
overwriteAll: Accepts a boolean value that overwrites previously added graph names or baseIRIs (regardless of whether they came from a URL or a file)

Examples

dataset1.importFromUrls(['url1', 'url2', 'url3'])

Dataset.removeAllGraphs()

Removes all graphs from this dataset.

Examples

The following snippet removed all graphs from a specific dataset:

const user = await triply.getUser()
const dataset = await user.getDataset('my-dataset')
await dataset.removeAllGraphs()

Dataset.removePrefixes(prefixes: string[])

Removes IRI prefixes from this dataset.

The prefixes argument is a string array, containing the prefix labels to be removed.

Examples

The following snippet removes the def and id prefixes from the specified dataset.

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.removePrefixes(['def', 'id'])

Dataset.renameGraph(from: string, to: string)

Renames a graph of this dataset, where from is the current graph name and to is the new graph name. The string arguments for from and to must be valid IRIs.

Examples

The following snippet renames a specific graph of a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.renameGraph(
  'https://example.org/old-graph',
  'https://example.org/new-graph'
)

Dataset.update(metadata: object)

Updates the metadata for this dataset.

Arguments

The metadata argument takes a dictionary object with the following optional keys:

Required:

accessLevel

The access level of the dataset. The following values are supported:

'private': The dataset can only be accessed by the Account object for which it is created.
'internal': The dataset can only be accessed by people who are logged into the TriplyDB server.
'public': The dataset can be accessed by everybody.

Optional:

description

The description of the dataset. This description can make use of Markdown.

displayName

The human-readable name of the dataset. This name may contain spaces and other characters that are not allowed in the URL-friendly name.

license

The license of the dataset. The following license strings are currently supported:

'CC-BY-SA'
'CC0 1.0'
'GFDL'
'ODC-By'
'ODC-ODbL'
'PDDL'

Example

The following snippet updates the dataset's access level, description, display name and license:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
dataset.update({
  accessLevel: 'private',
  description: 'desc',
  displayName: 'disp',
  license: 'PDDL',
})

Dataset.uploadAsset(assetName: string, filePath: string)

Uploads a file that does not contain RDF data as an asset.

User cases

There are several use cases for assets:

Source data that will be used as input files to an ETL process.
Documentation files that describe the dataset.
Media files (audio/image/video) that are described in the RDF graph.

Examples

The following snippet uploads a source CSV data file and a PDF documentation file:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
await dataset.uploadAsset('my-source-data', 'source.csv.gz')
await dataset.uploadAsset('my-documentation', 'documentation.pdf')

Graph

Each dataset with data consists out of one or more named graphs. All graphs together is thus the collection of triples of the dataset. Often the graph is used to denote a part of the dataset. For example the data model of the dataset or the metadata of the dataset. A graph has as advantage that is can partition data while at the same time keep the data in the same dataset. Reducing the overhead of having to move between datasets to traverse a graph.

You can retrieve either retrieve all graphs from a dataset in the form of an async iterator. Or retrieve a specific graph from a dataset.

Examples

The following snippet retrieves the graph 'https://example.com/my-graph' for a specific dataset:

const user = await triply.getUser()
const dataset = await user.getDataset('my-dataset')
const graph = await dataset.getGraph('https://example.com/my-graph')

The following snippet retrieves all the graphs for a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const graphs = dataset.getGraphs()

The Graph is the smallest object that can be individually deleted or modified.

Graph.delete()

Deletes the graph of this dataset. Any copies of the graph will not be deleted. All services containing this graph will still contain the graph until the service is synced again.

Examples

The following snippet deletes a specific graph that is part of the account associated with the current API token:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const graph = await dataset.getGraph('https://example.com/my-graph')
await graph.delete()

Graph.getInfo()

Returns information about this graph.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

The following keys and values are returned for graph.getInfo()

id

A hexadecimal hash of the graph to identify the graph for internal identification.

graphName

The URL-friendly name of the graphName that is used as identifier and name.

numberOfStatements

The number of statements in the graph.

uploadedAt (Optional)

The date/time at which the graph was uploaded to TriplyDB.

importedAt (Optional)

The date/time at which the query was imported from another dataset.

importedFrom (Optional)

graphName: The graphname of the graph from the dataset from which the graph was imported.
dataset: The dataset from which the graph was imported.

Examples

The following snippet prints the information from the specified graph of the specified dataset of the current user:

const user = await triply.getUser()
const dataset = await user.getDataset('my-dataset')
const graph = await dataset.getGraph('https://example.com/my-graph')
console.log(await graph.getInfo())

Graph.rename(name: string)

Renames the graph, the argument name is the new graph name. The string argument for name must be a valid IRI.

Examples

The following snippet renames a specific graph of a specific dataset:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const graph = await dataset.getGraph('https://example.com/my-graph')
await dataset.rename('https://example.org/new-graph')

Get the data locally

Most of the time you do not need to download a graph locally as TriplyDB supports a variety of methods to use linked data directly. But if you want to use a graph locally that is possible with TriplyDB.js. There are three methods to retrieve linked data from a graph. toFile(), toStore() and toStream().

Graph.toFile(destinationPath: string, arguments?: object)

Optional

The optional properties accepted as arguments for toFile

Compressed: Argument compressed optionally is an boolean defining if a graph is compresssed with GNU zip (gzip) compression algorithm and will end with a `.gz` extension.

Examples

The following example downloads the graph to file:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const graph = await dataset.getGraph('https://example.com/my-graph')
await graph.toFile('my-filename.ttl', {compressed: true})

Graph.toStore(graph?: Graph)

To reduce the overhead of downloading your data to file and then insert it in the N3 Store. TriplyDB.js has a toStore() where a N3 store is returned as a result of the the toStore() function.

Examples

The following example downloads the graph as N3.store:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const graph = await dataset.getGraph('https://example.com/my-graph')
const store = await graph.toStore()

Graph.toStream(type: 'compressed' | 'rdf-js', arguments?: object)

The final method to download linked data to a local source is the toStream this function returns a stream of quads that can directly be iterated over. The Stream is either of the type compressed which returns a gzipped stream of linked data, or type rdf-js which returns a stream of quads parsed according to the rdf-js standard.

Optional

The following arguments can be defined in the optional arguments object.

Extension: Argument Extension optionally defines the linked data type that is streamed. The extensions that are supported are: `nt`, `nq`, `trig`, `ttl`, `jsonld`, `json`.

Examples

The following example streams through the graph as rdf-js quad objects. and prints the quad to the screen. notice that the stream is an async iterator.

Example 1

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const graph = await dataset.getGraph('https://example.com/my-graph')
const stream = await graph.toStream('rdf-js', {extension: '.nq'})
for await(const quad of stream){
  console.log(quad)
}

The following example streams through the graph as chunks of ttl. and prints the buffer to the screen.

Example 2

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('pokemon')
const graph = await dataset.getGraph('https://example.com/my-graph')
const stream = await graph.toStream('compressed', {extension: '.ttl'})
for await(const quad of stream.pipe(zlib.createGunzip())){
  console.log((quad as Buffer).toString())
}

Organization

Instances of class Organization denote organizations in TriplyDB.

Obtaining instances

Organizations are obtained with method App.getOrganization(name: string):

const organization = await triply.getOrganization('Triply')

Alternatively, organizations are obtained by first obtaining an account (App.getAccount(name?: string)) and then casting it to an organization (Account.asOrganization()):

const account = await triply.getAccount('Triply')
const organization = account.asOrganization()

Inheritance

Organization is a subclass of Account, from which it inherits most of its methods.

Organization.addDataset(name: string, metadata?: object)

Adds a new TriplyDB dataset with the given name to the current organization.

Inherited from Account.addDataset(name: string, metadata?: object).

Organization.addMember(user: User, role?: Role)

Adds a member to the given Organization, with the given role of either member or owner.

Arguments

The user argument has to be a user object of the user which should be added to the organization.
The role argument can be either 'member' or 'owner'. If this argument is not specified, then 'member' is used as the default.

'member': A regular member that is allowed to read and write the datasets that are published under the organization.
'owner': An owner of the organization. Owners have all the rights of regular users, plus the ability to add/remove users to/from the organization, the ability to change the roles of existing users, and the ability to delete the organization.

Examples

The following snippet adds user John Doe to the Triply organization as a regular member.

const organization = await triply.getOrganization('Triply')
const johnDoe = await app.getUser('john-doe')
await organization.addMember(johnDoe)

Organization.removeMember(user: User)

Removes a member from the given Organization.

Organization.addQuery(name: string, metadata: object)

Adds a new TriplyDB query to the current organization.

Inherited from Account.addQuery(name: string, metadata: object).

Organization.ensureStory(name: string, metadata: object)

Ensures the existence of a story with the given name and with the specified metadata.

Inherited from Account.ensureStory(name: string, metadata: object).

Organization.addStory(name: string, metadata?: object)

Adds a new TriplyDB story with the given name to the current organization.

Inherited from Account.addStory(name: string, metadata?: object).

Organization.delete()

Deletes this account. This also deletes all datasets, stories and queries that belong to this organization.

Examples

The following code example deletes the specified organization:

const organization = await triply.getOrganization('Neo4j')
await organization.delete()

Organization.ensureDataset(name: string, metadata?: object)

Ensures the existence of a dataset with the given name and with the specified metadata.

Inherited from Account.ensureDataset(name: string, metadata?: object).

Organization.getDataset(name: string)

Returns the dataset with the given name that is published by this organization.

Inherited from Account.getDataset(name: string).

Organization.getDatasets()

Returns an async iterator over the accessible datasets that belong to this organization.

Inherited from Account.getDatasets().

Organization.getMembers()

Returns the list of memberships for the given organization.

Return type

A membership contains the following components:

role: The role of the membership (OrgRole): either 'owner' for owners of the organization, or 'member' for regular members. The difference between owners and regular members is that owners can perform user management for the organization (add/remove/change memberships).
user: An instance of class User.
createdAt: A date/time string.
updatedAt: A date/time string.

Examples

const org = await triply.getOrganization('acme')
for (const membership of await org.getMembers()) {
  console.log(user)
}

Organization.getPinnedItems()

Returns the list of datasets, stories and queries that are pinned for the current organization.

Inherited from Account.getPinnedItems().

Organization.removeMember(user: User)

Removes the specified user from this organization.

Arguments

The user argument has to be a User object of a user.

Existence considerations

The user must be a current member of the organization for this method to succeed. If the user is not a current member of the organization, an error is thrown.

Examples

The following snippet removes John Doe from the Triply organization, using a string argument:

const organization = await triply.getOrganization('Triply')
const johnDoe = await app.getUser('john-doe')
await organization.removeMember(johnDoe)

The following snippet removes John Doe from the Triply organization, using a User object:

const organization = await triply.getOrganization('Triply')
const user = await triply.getUser('john-doe')
await organization.removeMember(user)

Organization.setAvatar(file: string)

Sets a new image that characterized this organization.

Inherited from Account.setAvatar(file: string).

Organization.update(metadata: object)

Updates the metadata for this account.

Inherited from Account.update(metadata: object).

Query

A Saved Query is a versioned SPARQL query with its own URL. Using this URL, users are able to view any version of the query and its results. It can also be used to run the query and retrieve the results from a browser or a program, removing the hassle of figuring out how to run a SPARQL query.

Saved queries come with a REST API that can be configured with the use a SPARQL API variables.

Query.delete()

Permanently deletes this query and all of its versions.

Query.getInfo()

The returned dictionary object includes the following keys:

accessLevel

The access level of the query. The following values are possible:

'private' (default): The dataset can only be accessed by organization members.
'internal': The dataset can only be accessed by users that are logged into the TriplyDB server.
'public': The dataset can be accessed by everybody.

autoselectService

Whether the SPARQL service is automatically chosen (true), or whether a specific SPARQL service is configured (false).

createdAt

The date/time at which the query was created.

dataset

A dictionary object representing the dataset against which the query is evaluated.

description

The human-readable description of the query. This typically explains what the query does in natural language.

displayName

The human-readable name of the query. This name may include spaces and other characters that are not allowed in the URL-friendly name.

name

The URL-friendly name of the query that is used in URL paths. This name can only include ASCII letters and hyphens.

numberOfVersions

The number of currently stored versions of this query.

owner

A dictionary object representing the account (organization or user) to which the query belongs.

🚧link

Stores part of the URL to run the query. Please use Query.getRunLink() to obtain the full URL to run the query.

service

The location of the SPARQL endpoint that is used to run the query.

updatedAt

The date/time at which the query was last modified.

Query.getString(apiVariables?: object)

Returns the query string of the current version of this query.

Optionally, arguments can be specified for the API variables to this query.

Examples

The following code stores the SPARQL query string for the query object:

const queryString = await query.getString()

Query.addVersion(metadata: object)

Adds a new version to the query used. It requires similar options to that of Query.addQuery.

Arguments

At least one of the following arguments is required to create a new version. Any argument not given will be copied from the previous version of that query.

queryString: string

the SPARQL compliant query as a string value

output: string

The visualization plugin that is used to display the result set. If none is set it defaults to 'table'. Other options may include: 'response', 'geo', 'gallery', 'markup', etc

variables: Variable[]

A list of objects with the following keys:

IRI variable: An object of the form `Variable` (see [`Account.addQuery()`](#accountaddqueryname-string-metadata-object)

You can see how many versions exist on a query accessing Query.getInfo().numOfVersions
You can use a specified version of a query accessing Query.useVersion(x: number)

Query.getRunLink()

Returns the URL link to run the query. It currently does not support the use of variables.

Query.results(apiVariables?: object, options?: object)

Query.results() function will automatically return all the results from a saved query. You can retrieve both results from a select or ask query and a construct or describe query. The results are returned as an async iterator.

If there are more than 10 000 query results, they could be retrieved using pagination with TriplyDB.js.

Examples

Get the results of a query by setting a results variable. More specifically, for construct queries you use the statements() call:

const triply = App.get({token: process.env.TOKEN})
const account = await triply.getAccount('account-name')
const query = await account.getQuery('name-of-some-query')

// For select queries you use the `statements()` call:
const results = query.results().statements()
// For select queries you use the `bindings()` call:
const results = query.results().bindings()

Additionally, saved queries can have 'API variables' that allow you to specify variables that are used in the query. Thus, if you have query parameters, pass their values as the first argument to results as follows:

const triply = App.get({token: process.env.TOKEN})
const account = await triply.getAccount('account-name')
const query = await account.getQuery('name-of-some-query')
// For SPARQL construct queries.
const results = query.results({
 someVariable: 'value of someVariable',
 anotherVariable: 'value of anotherVariable'
}).statements()
// For SPARQL select queries.
const results = query.results({
 someVariable: 'value of someVariable',
 anotherVariable: 'value of anotherVariable'
}).bindings()

Query.update(metadata: object)

Updates the metadata for the saved query. This does not result in a new query version. It requires similar options to that of Query.addQuery.

Arguments

At least one of the following arguments is required to update the metadata. Any argument given will be copied from the previous version of that query.

accessLevel

The access level of the query. The following values are possible:

'private' (default): The dataset can only be accessed by organization members.
'internal': The dataset can only be accessed by users that are logged into the TriplyDB server.
'public': The dataset can be accessed by everybody.

autoselectService

Whether the SPARQL service is automatically chosen (true), or whether a specific SPARQL service is configured (false).

dataset

A dictionary object representing the dataset against which the query is evaluated.

description

The human-readable description of the query. This typically explains what the query does in natural language.

displayName

The human-readable name of the query. This name may include spaces and other characters that are not allowed in the URL-friendly name.

name

The URL-friendly name of the query that is used in URL paths. This name can only include ASCII letters and hyphens.

preferredService

If the autoselectService is not selected the user can set the preferred service.

Query.useVersion(version: number|'latest')

A saved query is saved with a version number. Each time the query or the visualization changes the version number is incremented with one. When you want to retrieve a saved query with a particular version you need the useVersion function. The function returns the query object corresponding to that version of the query. If you want to use the latest version of the query you need to set the version argument to 'latest'.

Example

const user = await triply.getAccount('my-account')
const query = await user.getQuery('my-query')
const query_1 = await query.useVersion(1)

Service

Service objects describe specific functionalities that can be created over datasets in TriplyDB.

Service objects are obtained through the the following methods:

Dataset.addService
Dataset.getServices

A service always has one of the following statuses:

Removing: The service is being removed.
Running: The service is running normally.
Starting: The service is starting up.
Stopped: The services was stopped in the past. It cannot be used at the moment, but it can be enable again if needed.
Stopping: The service is currently being stopped.

Service.delete()

Permanently deletes this service.

Examples

const user = await triply.getAccount('my-account')
const dataset = await user.getDataset('my-dataset')
const service = await dataset.addService('my-service')
await service.delete()

Service.getInfo()

Returns information about this service.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

Examples

The following snippet prints information about the newly created service (named my-service):

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const service = await dataset.addService('my-service')
console.log(await service.getInfo())

Service.isUpToDate()

Returns whether this service is synchronized with the dataset contents.

Synchronization

Because services must be explicitly synchronized in TriplyDB, it is possible to have services that expose an older version of the dataset and services that expose a newer version of the dataset running next to one another. There are two very common use cases for this:

The production version of an application or website runs on an older service. The data does not change, so the application keeps working. The acceptance version of the same application or website runs on a newer service. Once the acceptance version is finished, it becomes the production version and a new service for the new acceptance version is created, etc.
An old service is used by legacy software. New users are using the newer endpoint over the current version of the data, but a limited number of older users want to use the legacy version.

Examples

The following code checks whether a specific service is synchronized:

const account = await triply.getAccount()
const dataset = await account.getDataset('my-dataset')
const service = await dataset.ensureService('my-service', {type: 'sparql'})
console.log(await service.isUpToDate())

Service.update()

Synchronizes the service. Synchronization means that the data that is used in the service is made consistent with the data that is present in the graphs of the dataset.

When one or more graphs are added or deleted, existing services keep exposing the old state of the data. The changes in the data are only exposed in the services after synchronization is performed.

Examples

When there are multiple services, it is common to synchronize them all in sequence. This ensures that there are always one or more services available. This allows applications to use such services as their backend without any downtime during data changes.

The following code synchronizes all services of a dataset in sequence:

for (const service of await dataset.getServices()) {
  service.update()
}

Although less common, it is also possible to synchronize all services of a dataset in parallel. This is typically not used in production systems, where data changes must not result in any downtime. Still, parallel synchronization can be useful in development and/or acceptance environments.

The following code synchronizes all services of a dataset in parallel:

await Promise.all(dataset.getServices().map(service => service.update()))

Service.waitUntilRunning()

A service can be stopped or updated. The use of asynchronous code means that when a start command is given it takes a while before the service is ready for use. To make sure a service is available for querying you can uesr the function waitUntilRunning() to make sure that the script will wait until the service is ready for use.

Example

An example of a service being updated and afterwards a query needs to be executed:

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getAccount()
const dataset = await user.getDataset('some-dataset')
const service = await dataset.getService('some-service')
// starting a service but does not wait until it is started
await service.start()
// Function that checks if a service is available
await service.waitUntilRunning()

Story

A TriplyDB data story is a way of communicating information about your linked data along with explanatory text while also being able to integrate query results. To create Data stories with TriplyDB.js You can use the User.ensureStory or User.addStory functions to create. If you want to retrieve an already created data story you can use the functions User.getStories to iterate over all stories, or retrieve a particular one with User.getStory.

Story objects are obtained through the the following methods:

User.addStory
User.ensureStory
User.getStories
User.getStory

Story.delete()

Deletes this story. This deletes all paragraphs that belong to this story.

This does not delete the queries that are linked into this story. If you also want to delete the queries, then this must be done with distinct calls of Query.delete().

Examples

The following code example deletes a story called 'example-story' under the current user's account:

const user = await triply.getUser()
const story = await user.getStory('example-story')
await story.delete()

Story.getInfo()

Returns information about this data story.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

Examples

The following snippet prints the paragraphs that appear in a data story:

for (const element of (await story.getInfo()).content) {
  if ((element.type = 'paragraph')) {
    console.log(element.paragraph)
  }
}

User

Instances of class User denote users in TriplyDB.

Obtaining instances

Users are obtained with method App.getUser(name?: string):

const user = triply.getUser('john-doe')
const user = triply.getUser()

Alternatively, users are obtained by first obtaining an account (App.getAccount(name?: string)) and then casting it to a use (Account.asUser()):

const account = await triply.getAccount('john-doe')
const user = account.asUser()

Inheritance

User is a subclass of Account, from which it inherits most of its methods.

Limitations

Users cannot be created or deleted through the TriplyDB.js library. See the Triply Console documentation for how to create and delete users through the web-based GUI.

User.addDataset(name: string, metadata?: object)

Adds a new TriplyDB dataset with the given name to the current account.

Inherited from Account.addDataset(name: string, metadata?: object).

User.addQuery(metadata: object)

Adds a new TriplyDB query to the current user.

Inherited from Account.addQuery(metadata: object).

User.ensureStory(name: string, metadata: object)

Ensures the existence of a story with the given name and with the specified metadata.

Inherited from Account.ensureStory(name: string, metadata: object).

User.addStory(name: string, metadata?: object)

Adds a new TriplyDB story with the given name to the current user.

Inherited from Account.addStory(name: string, metadata?: object).

User.createOrganization(name: string, metadata?: object)

Creates a new organization for which this user will be the owner.

Access restrictions

This method requires an API token with write access for this user.

Arguments

Argument name is the URL-friendly name of the new organization. This name can only contain alphanumeric characters and hyphens ([A-Za-z0-9\-]).
The optional metadata argument can be used to specify additional metadata. This is a dictionary object with the following optional keys:

description: The description of the organization. This description can make use of Markdown.
email: The email address at which the organization can be reached.
name: The human-readable name of the organization. This name may contain spaces and other non-alphanumeric characters.

Examples

The following snippet creates a new organization for which John Doe will be the owner. Notice that both a required URL-friendly name ('my-organization') and an optional display name ('My Organization') are specified.

const user = await triply.getUser('john-doe')
await user.createOrganization(my-organization, {name: 'My Organization'}))

User.ensureDataset(name: string, metadata?: object)

Ensures the existence of a dataset with the given name and with the specified metadata.

Inherited from Account.ensureDataset(name: string, metadata?: object).

User.getDataset(name: string)

Returns the TriplyDB dataset with the given name that is published by this user.

Inherited from Account.getDataset(name: string).

User.getDatasets()

Returns an async iterator over the accessible datasets for the current user.

Inherited from Account.getDatasets().

User.getInfo()

Returns information about this user.

Information is returned in a dictionary object. Individual keys can be accessed for specific information values.

The information object for users includes the following keys:

avatarUrl: A URL to the user image.
accountName: The URL-friendly name of the user.
name: The human-readable display name of the user
description: The human-readable description of the user.
createdAt: The date and time on which the user was created.
datasetCount: The number of datasets for the user.
queryCount: The number of queries for the user.
storyCount: The number of stories for the user
pinnedItems: An array containing the pinned items (datasets, stories and queries) for the user.
role: The role of the user. Either 'light', 'regular' or 'siteAdmin'.
orgs: An array of organizations of which the user is a member.
Email address: The email address of the user.
updatedAt: The date and time on which the user was last updated.
lastActivity: The date and time on which the user was last online on TriplyDB.

Examples

The following snippet prints an overview of account that is associated with the used API token:

const user = await triply.getUser()
console.log(await user.getInfo())

User.getOrganizations()

Returns an async iterator over the organizations that this user is a member of.

Order considerations

The order in the list reflects the order in which the organizations appear on the user page in the Triply GUI.

Examples

The following snippet prints the list of organizations that John Doe is a member of:

const user = await triply.getUser('john-doe')
for await (const organization of await user.getOrganizations()) {
  console.log((await organization.getInfo()).name)
}

User.getPinnedItems()

Returns the list of datasets, stories and queries that are pinned for the current user.

Inherited from Account.getPinnedItems().

User.setAvatar(file: string)

Sets a new image that characterized this user.

Inherited from Account.setAvatar(file: string).

User.update(metadata: object)

Updates the metadata for this user.

Inherited from Account.update(metadata: object).

FAQ

This section includes answers to frequently asked questions. Please contact info@triply.cc if you have a question that does not appear in this list.

How to perform a SPARQL query?

The SPARQL 1.1 Protocol standard specifies a native HTTP API for performing SPARQL requests. Such requests can be performed with regular HTTP libraries.

Here we give an example indicating how such an HTTP library can be used:

import SuperAgent from 'superagent';
const reply = await SuperAgent.post('SPARQL_ENDPOINT')
  .set('Accept', 'application/sparql-results+json')
  .set('Authorization', 'Bearer ' + process.env.TOKEN)
  .buffer(true)
  .send({ query: 'select * { WHERE_CLAUSE } offset 0 limit 10000' })
// break condition when the result set is empty.

// downsides: caching, string manipulation

What is the latest version of TriplyDB.js?

The latest version of TriplyDB.js can be found in the NPM repository.

What to do when the “Error: Unauthorized” appears?

This error appears whenever an operation is performed for which the user denoted by the current API token is not authorized.

One common appearance of this error is when the environment variable TOKEN is not set to an API token.

The current value of the environment variable can be tested by running the following command in the terminal:

echo $TOKEN

How do I get the results of a saved query using TriplyDB.js?

To reliably retrieve a large number of results as the output of a construct or select query, follow these steps:

Import the triplydb library.
```
import App from '@triply/triplydb';
```

Set your parameters, regarding the TriplyDB server and the account in which you have saved the query as well as the name of the query.

const triply = App.get({ url: 'https://api.triplydb.com' })
const account = await triply.getAccount('account-name')
const query = await account.getQuery('name-of-some-query')

If the query is not public, you should set your API token rather than the URL.

const triply = App.get({ token: process.env.TOKEN })

Do not forget that we perform TriplyDB.js requests within an async context. That is:
```
async function run() {
  // Your code goes here.
}
run()
```

Get the results of a query by setting a results variable. More specifically, for construct queries:

const results = query.results().statements()

For select queries:

const results = query.results().bindings()

Note that for SPARQL construct queries, we use method .statements(), while for SPARQL select queries, we use method .bindings().

Additionally, saved queries can have API variables that allow you to specify variables that are used in the query. Thus, if you have query parameters, pass their values as the first argument to results as follows:

// For SPARQL construct queries.
const results = query
  .results({
    someVariable: 'value of someVariable',
    anotherVariable: 'value of anotherVariable',
  })
  .statements()
// For SPARQL select queries.
const results = query
  .results({
    someVariable: 'value of someVariable',
    anotherVariable: 'value of anotherVariable',
  })
  .bindings()

To read the results you have three options:

5a. Iterate through the results per row in a for-loop:
```
// Iterating over the results per row
for await (const row of results) {
  // execute something
}
```
5b. Save the results to a file.

For saving SPARQL construct queries:
```
// Saving the results of a SPARQL construct query to a file.
await results.toFile('my-file.nt')
```
For saving SPARQL select queries. Currently we only support saving the file to a .tsv format:
```
// Saving the results of a SPARQL select query to a file.
await results.toFile('my-file.tsv')
```
5c. Load all results into memory. Note that this is almost never used. If you want to process results, then option 5a is better; if you want to persist results, then option 5b is better.
```
// Loading results for a SPARQL construct or SPARQL select query into memory.
const array = await results.toArray()
```

What is an async iterator?

TriplyDB.js makes use of async iterators for retrieving lists of objects. Async iterators are a method of fetching and iterating through large lists, without having to first fetch the whole set.

An example of an async iterator in TriplyDB.js is App.getAccounts(). The following code illustrates how it can be used.

for await (const account of triply.getAccounts()) {
  console.log(account)
}

For cases where you want the complete list, you can use the toArray function of the iterator.

const accounts = await triply.getAccounts().toArray()

TriplyDB.js returns async iterators from the following methods:

App.getAccounts()
Account.getDatasets()
Account.getQueries()
Account.getStories()
Dataset.getServices()
Dataset.getAssets()
Dataset.getGraphs()
Dataset.getStatements()
Query.results().statements() for SPARQL construct and describe queries
Query.results().bindings() for SPARQL select queries

TriplyDB.js

Overview

App

App.getAccount(name?: string)

Examples

See also

App.getAccounts()

Example

App.getInfo()

Examples

App.getOrganization(name: string)

Examples

Alternatives

See also

App.getUser(name?: string)

Examples

Alternatives

See also

App.isCompatibleWith(minimumVersion: string)

Arguments

See also

Account

Account.addDataset(name: string, metadata?: object)

Access restrictions

Arguments

Examples

See also

Account.addQuery(name: string, metadata: object)

Arguments

Example

Account.addStory(name: string, metadata?: object)

Required

Optional

Examples

Account.asOrganization()

Examples

Alternatives

See also

Account.asUser()

Examples

Alternatives

See also

Account.ensureDataset(name: string, metadata?: object)

Example

See also

Account.getDataset(name: string)

Examples

See also

Account.getDatasets()

Access restrictions

Examples

Account.getInfo()

Examples

Account.getPinnedItems()

Order considerations

Examples

See also

Account.getQuery(name: string)

Examples

See also

Account.getQueries()

Access restrictions

Examples

See also

Account.ensureStory(name: string, metadata: object)

Optional

Account.addStory(name: string, newStoryOptions?: object)

Required

Optional

Account.getStory(name: string)

Examples

See also

Account.getStories()

Examples

See also

Account.pinItems(items: array[Dataset|Story|Query])

Account.setAvatar(file: string)

Examples

Account.update(metadata: object)

Asset