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()
See also
This method returns an account object. See class Account for an overview of the methods that can be called on such objects.
Class Account has two specializations: class Organization and class User. In line with these class specializations, there are also two method specializations:
-
Method
App.getOrganization(name: string)
returns an organization object. -
Method
App.getUser(name?: string)
returns a user object.
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()
See also
This method returns an organization object. See class Organization for an overview of the methods that can be called on such objects.
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()
See also
This method returns a user object. See class User for an overview of the methods that can be called on such objects.
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'
.
See also
To inspect the current version of the connected-to TriplyDB server, use App.getInfo()
.
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:
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/',
},
})
See also
This method returns a dataset object. See the Dataset section for an overview of the methods that can be called on such objects.
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.
or
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
(iftermType='Literal'
)- The datatype IRI for the literal variable.
language: string
(iftermType='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')
See also
This method returns an organization object. See class Organization for an overview of the methods that can be called on such objects.
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()
See also
This method returns an organization object. See class Organization for an overview of the methods that can be called on such objects.
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 callingAccount.addDataset(name: string, metadata?: object)
with the same arguments. - If this account already has a dataset with the given
name
and with the samemetadata
, then this method makes no changes.
Example
const account = await triply.getAccount('Triply')
const myDataset = await account.ensureDataset(`my-dataset`, {
license: 'PDDL',
})
See also
The meaning of the argument to this method are identical to those of the Account.addDataset(name: string, metadata?: object)
method.
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)
See also
This method returns a dataset object. See class Dataset for an overview of the methods that can be called on such objects.
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
oruser
. 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)
}
See also
This method returns various types of objects. Each class has different functionalities:
- See class Dataset for an overview of the methods for dataset objects.
- See class Query for an overview of the methods for query objects.
- See class Story for an overview of the methods for story objects.
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)
See also
See class Query for an overview of the methods for query objects.
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)
}
See also
See class Query for an overview of the methods for query objects.
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 callingAccount.addStory(name: string, metadata?: object)
with the same arguments. - If this account already has a story with the given
name
and with the samemetadata
, 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')
See also
See class Story for an overview of the methods for story objects.
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)
}
See also
See class Story for an overview of the methods for story objects.
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 callingDataset.addService(name: string, metadata?: object)
with the same arguments. - If this dataset already has a service with the given
name
, but with differentmetadata
specified for it, then the behavior is identical to callingAccount.getDataset(name: string)
andDataset.update(metadata: object)
. - If this dataset already has a service with the given
name
and with the samemetadata
, 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 whentype
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' },
})
See also
See class Service for an overview of the methods that can be used with service objects.
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()
See also
Sometimes it is more useful to only delete the graphs that belong to a dataset, but leave the dataset metadata, services, and assets in place. The following methods can be used for this purpose:
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)
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 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)
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 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)
}
See also
Memberships of organization are TriplyDB users.
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:
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:
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)
}
See also
The async iterator contains organization objects. See the section about the Organization
class for methods that can be used on such objects.
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 SPARQLselect
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 SPARQLconstruct
anddescribe
queriesQuery.results().bindings()
for SPARQLselect
queries