On this page:

Account

Account¶

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

Account objects are obtained by calling the following method:

App.getAccount(name?: string)

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

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

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

Access restrictions¶

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

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

Arguments¶

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

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

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

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

accessLevel

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

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

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

description

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

displayName

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

license

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

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

prefixes

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

Examples¶

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

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

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

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

Adds a new SPARQL query to the account.

Arguments¶

Required:

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

Optional:

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

accessLevel

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

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

description: string

A human-readable description of the query.

displayName: string

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

output: string

The visualization plugin that is used to display the result set of the query. If none is set it 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,
  queryString: 'select (count(*) as ?n) { ?s ?p ?o. }',
  output: 'response',
})

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

Adds a new data story.

Required¶

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

Optional¶

accessLevel

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

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

content: StoryElementUpdate[]

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

displayName: string

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

A story element is an object with the following keys:

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

Examples¶

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

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

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

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

Account.asOrganization()¶

Casts the TriplyDB account object to its corresponding organization object.

Class Organization is a specialization of class Account.

Calling this method on an Organization object does nothing.

Examples¶

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

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

Alternatives¶

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

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

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

Account.asUser()¶

Casts the TriplyDB account object to its corresponding user object.

Class User is a specialization of class Account.

Calling this method on a User object does nothing.

Examples¶

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

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

Alternatives¶

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

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

const user = await triply.getUser()

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

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

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

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

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

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

Example¶

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

Account.getDataset(name: string)¶

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

Examples¶

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

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

Account.getDatasets()¶

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

Access restrictions¶

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

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

Examples¶

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

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

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

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

Account.getInfo()¶

Returns information about this account.

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

The information object for accounts includes the following keys:

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

Examples¶

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

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

The output for this snippet can look as follows:

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

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

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

Account.getPinnedItems()¶

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

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

Order considerations¶

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

Examples¶

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

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

Account.getQuery(name: string)¶

Returns the TriplyDB query with the given name.

Examples¶

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

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

Account.getQueries()¶

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

Access restrictions¶

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

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

Examples¶

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

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

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

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

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

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

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

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

Optional¶

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

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

Examples

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

await someUser.ensureStory(`someStoryName`)

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

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

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

Required¶

Adds and returns the TriplyDB story with the given name.

Optional¶

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

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

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

Examples:

Example 1 - creates a newStory that is 'private'

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

Example 2 - creates a newStory that is 'public'

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

Account.getStory(name: string)¶

Returns the TriplyDB story with the given name.

Examples¶

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

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

Account.getStories()¶

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

Examples¶

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

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

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

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

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

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

Account.setAvatar(file: string)¶

Sets a new image that characterizes this account.

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

Examples¶

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

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

Account.update(metadata: object)¶

Updates the metadata for this account.

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

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

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

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

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

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

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

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

The metadata object for accounts can include the following keys:

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

Account¶

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

Access restrictions¶

Arguments¶

Examples¶

See also¶

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

Arguments¶

Example¶

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

Required¶

Optional¶

Examples¶

Account.asOrganization()¶

Examples¶

Alternatives¶

See also¶

Account.asUser()¶

Examples¶

Alternatives¶

See also¶

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

Example¶

See also¶

Account.getDataset(name: string)¶

Examples¶

See also¶

Account.getDatasets()¶

Access restrictions¶

Examples¶

Account.getInfo()¶

Examples¶

Account.getPinnedItems()¶

Order considerations¶

Examples¶

See also¶

Account.getQuery(name: string)¶

Examples¶

See also¶

Account.getQueries()¶

Access restrictions¶

Examples¶

See also¶

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

Optional¶

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

Required¶

Optional¶

Account.getStory(name: string)¶

Examples¶

See also¶

Account.getStories()¶

Examples¶

See also¶

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

Account.setAvatar(file: string)¶

Examples¶

Account.update(metadata: object)¶