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\-]).
dataset: Dataset
An instance of class Dataset that the current API token gives access to.
serviceType: "speedy" | "virtuoso" | "jena" | "blazegraph"
A service type that will be used as a preferred SPARQL service to execute the query against. If serviceType is "virtuoso", "jena" or "blazegraph", that service is expected to exist in the dataset before the query can be successfully run. See Dataset
queryString: string
The SPARQL query string (e.g., 'select * { ?s ?p ?o }').

Optional:

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 will either set ldFrame if provided or default to table.
'boolean'
The boolean 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 view allows SPARQL results to be displayed in an HTML gallery.
'gchart'
The gchart renders geographical, temporal and numerical data in interactive charts such as bar-, line- and pie charts.
'geo'
The geo allows SPARQL results that contain GeoSPARQL semantics to be automatically interpreted and displayed on a 2D map.
'geoEvents'
The geoEvents plugin renders geographical events as a story map.
'geo3d'
The geo3d allows SPARQL results that contain GeoSPARQL semantics to be automatically interpreted and displayed on a 3D globe.
'markup'
The 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 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 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 view shows the body of the response and offers a easy way to download the result as a file.
'table'
The 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 timeline renders the SPARQL results on a Timeline.
ldFrame: object
JSON LD frame object used to transform plain JSON LD into a framed JSON. Will be used only if an output is not provided.
variables: Variable[]
A list of objects with the following keys:
IRI variable
An object of the form Variable (see below)

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

Required:

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

Optional:

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

Example

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

const triply = App.get({ token: process.env.TOKEN })
const user = await triply.getUser()
const myDataset = await user.getDataset('my-dataset')
const query = await user.addQuery('my-query', {
  dataset: myDataset,
  serviceType: "speedy",
  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 calling Account.addDataset(name: string, metadata?: object) with the same arguments.
  • If this account already has a dataset with the given name and with the same metadata, then this method makes no changes.

Example

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

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 or user.
role
The role of the account
orgs
An array of organizations of which the account is a member.
Email address
The email address of the account.
updatedAt
The date and time on which the account was last updated.
lastActivity
The date and time on which the account was last online on TriplyDB.

Examples

  • The following snippet prints the full information object for the account called ‘Triply’:
const account = await triply.getAccount('Triply')
console.log(await account.getInfo())

The output for this snippet can look as follows:

{
  'accountName': 'Triply',
  'avatarUrl': 'https://www.gravatar.com/avatar/9bc28997dd1074e405e1c66196d5e117?d=mm',
  'createdAt': 'Mon Mar 19 2018 14:39:18 GMT+0000 (Coordinated Universal Time)',
  'datasetCount': 16,
  'name': 'Triply',
  'queryCount': 37,
  'storyCount': 7,
  'type': 'org',
  'updatedAt': 'Tue Nov 27 2018 09:29:38 GMT+0000 (Coordinated Universal Time)'
}
  • The following snippet prints the name of the account called ‘Triply’:
const account = await triply.getAccount('Triply')
console.log((await account.getInfo()).name)

Account.getPinnedItems()

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

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

Order considerations

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

Examples

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

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

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 calling Account.addStory(name: string, metadata?: object) with the same arguments.
  • If this account already has a story with the given name and with the same metadata, then this method returns that story.

Optional

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

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

Examples

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

await someUser.ensureStory(`someStoryName`)

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

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

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

Required

Adds and returns the TriplyDB story with the given name.

Optional

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

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

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

Examples:

Example 1 - creates a newStory that is 'private'

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

Example 2 - creates a newStory that is 'public'

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

Account.getStory(name: string)

Returns the TriplyDB story with the given name.

Examples

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

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

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:

  1. Obtain the relevant piece of information as a variable/const: getObject()
  2. 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.