Class Group

A TriplyDB group: an account shared by several users.

Remarks

Obtain one with App.getGroup, or create one with User.createGroup or User.ensureGroup. Groups are never constructed directly.

Everything a group shares with a user — datasets, queries, stories — is described on Account.

Example: Get a group, then one of its datasets

import App from "@triply/triplydb";

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

Example: Create a group on first run

const me = await app.getUser();
const group = await me.ensureGroup("my-group", { accessLevel: "private" });

Hierarchy

SharedAccountMembers
- Group

Implements

AccountBase

Properties

`Readonly`accountType

accountType: "Group"

Always "Group", so an Account can be narrowed without a request.

slug

slug: string

The group's account name, which is part of every URL under it.

Methods

addDataset

addDataset(name: string, ds?: AddDatasetOptions): Promise<Dataset>
Creates a new, empty dataset owned by this account.
Parameters
- name: string
  Name for the new dataset, which becomes part of its URL.
- Optionalds: AddDatasetOptions
  Metadata to create it with. accessLevel defaults to the instance's own default.
Returns Promise<Dataset>

Remarks
A new dataset has no graphs; load data into it with Dataset.importFromFiles, Dataset.importFromUrls or Dataset.importFromDataset.

Throws
If the name is already taken — it becomes part of the dataset's URL, so an account cannot have two. Use ensureDataset when you want the existing dataset instead of an error.

Implementation of AccountBase.addDataset

addMember

addMember(user: User, role?: string): Promise<GroupMember>
Adds a user to this group.
Parameters
- user: User
  The user to add.
- role: string = "member"
  "member" by default; "owner" also allows managing the group itself.
Returns Promise<GroupMember>

Throws
If the user is already a member. Use Group.changeRole to change their role.

addQuery

addQuery(name: string, opts: AddQueryOptions): Promise<Query>
Creates a new saved query owned by this account.
Parameters
- name: string
  Name for the new query, which becomes part of its URL.
- opts: AddQueryOptions
  The query text plus the dataset and service type to run it against; both are required, because a saved query is stored together with what it queries.
Returns Promise<Query>

Throws
If the name is already taken. Use getQuery to fetch the existing one.

Implementation of AccountBase.addQuery

addStory

addStory(name: string, args?: NewStory | NewStory_deprecated): Promise<Story>
Creates a new story owned by this account.
Parameters
- name: string
  Name for the new story, which becomes part of its URL.
- Optionalargs: NewStory | NewStory_deprecated
  Initial content and access level. A story created without content is empty and can be filled in later.
Returns Promise<Story>

Throws
If the name is already taken. Use ensureStory when you want the existing one.

Implementation of AccountBase.addStory

asGroup

asGroup(): Promise<Group>

This account as a Group.

Returns Promise<Group>

Remarks
For narrowing an Account whose kind you have established. A user cannot become a group.

Throws
If this account is a User.

Implementation of AccountBase.asGroup

asOrganization

asOrganization(): Promise<Group>

Returns Promise<Group>

Deprecated
Use asGroup()

Implementation of AccountBase.asOrganization

asUser

asUser(): Promise<User>

This account as a User.

Returns Promise<User>

Remarks
For narrowing an Account whose kind you have established.

Throws
If this account is a Group.

Implementation of AccountBase.asUser

changeRole

changeRole(member: User, role: string): Promise<GroupMember[]>
Changes what a member is allowed to do in this group.
Parameters
- member: User
  An existing member.
- role: string
  Their new role.
Returns Promise<GroupMember[]>
The group's members, as they now stand.

delete

delete(): Promise<void>

Deletes this group, with everything it owns.

Returns Promise<void>

Remarks
Destructive and not undoable: the group's datasets, queries and stories go with it. Its members keep their own accounts.

ensureDataset

ensureDataset(name: string, newDs?: AddDatasetOptions): Promise<Dataset>
The dataset with this name, created first if this account does not have one yet.
Parameters
- name: string
  Name of the dataset to get or create.
- OptionalnewDs: AddDatasetOptions
  Metadata to create it with, used only when it does not exist yet.
Returns Promise<Dataset>

Remarks
The idempotent form of addDataset, for code that runs more than once.

Only the absence of the dataset is reconciled: when it already exists, newDs is ignored rather than applied, so this never edits an existing dataset's metadata.

Throws
If the dataset exists and newDs.accessLevel disagrees with the access level it already has — rather than silently leaving it as it was.

Implementation of AccountBase.ensureDataset

ensureStory

ensureStory(
name: string,
newStory?: NewStory | NewStory_deprecated,
): Promise<Story>
The story with this name, created first if this account does not have one yet.
Parameters
- name: string
- OptionalnewStory: NewStory | NewStory_deprecated
Returns Promise<Story>

Remarks
The idempotent form of addStory. As with ensureDataset, newStory applies only when the story does not exist yet, so this never edits an existing story.

Throws
If the story exists and newStory.accessLevel disagrees with the access level it already has — rather than silently leaving it as it was.

Implementation of AccountBase.ensureStory

getDataset

getDataset(name: string): Promise<Dataset>
The dataset with this name, owned by this account.
Parameters
- name: string
  The dataset's name, as it appears in its URL.
Returns Promise<Dataset>

Throws
If this account has no dataset with that name. Use hasDataset to test first, or ensureDataset to create it when missing.

Implementation of AccountBase.getDataset

getDatasets

getDatasets(): ResultIterator<DatasetInfo, Dataset>

This account's datasets, as an iterator that fetches pages as you consume it.

Returns ResultIterator<DatasetInfo, Dataset>

Remarks
Which datasets are visible depends on the configured token.

Implementation of AccountBase.getDatasets

getInfo

getInfo(refresh?: boolean): Promise<GroupInfo>
This group's metadata: its name, display name, access level and profile fields.
Parameters
- refresh: boolean = false
Returns Promise<GroupInfo>

Remarks
Cached after the first call. Pass true to refetch.

Implementation of AccountBase.getInfo

getMembers

getMembers(): Promise<GroupMember[]>

This group's members and the role each holds.

Returns Promise<GroupMember[]>

getPinnedItems

getPinnedItems(): Promise<(Dataset | Query | Story)[]>

The datasets, stories and queries pinned to this account's profile, in the order they appear.

Returns Promise<(Dataset | Query | Story)[]>

Remarks
A single list of mixed kinds; narrow with instanceof when you need to treat them differently.

Implementation of AccountBase.getPinnedItems

getQueries

getQueries(): ResultIterator<QueryInfo, Query>

This account's saved queries, as an iterator that fetches pages as you consume it.

Returns ResultIterator<QueryInfo, Query>

Remarks
Which queries are visible depends on the configured token.

Implementation of AccountBase.getQueries

getQuery

getQuery(name: string): Promise<Query>
The saved query with this name, owned by this account.
Parameters
- name: string
  The query's name, as it appears in its URL.
Returns Promise<Query>

Throws
If this account has no query with that name. Use hasQuery to test first.

Implementation of AccountBase.getQuery

getStories

getStories(): ResultIterator<StoryInfo, Story>

This account's stories, as an iterator that fetches pages as you consume it.

Returns ResultIterator<StoryInfo, Story>

Remarks
Which stories are visible depends on the configured token.

Implementation of AccountBase.getStories

getStory

getStory(name: string): Promise<Story>
The story with this name, owned by this account.
Parameters
- name: string
  The story's name, as it appears in its URL.
Returns Promise<Story>

Throws
If this account has no story with that name. Use hasStory to test first.

Implementation of AccountBase.getStory

hasDataset

hasDataset(name: string): Promise<boolean>
Whether this account has a dataset with this name, without throwing when it does not.
Parameters
- name: string
Returns Promise<boolean>

Implementation of AccountBase.hasDataset

hasQuery

hasQuery(name: string): Promise<boolean>
Whether this account has a saved query with this name, without throwing when it does not.
Parameters
- name: string
Returns Promise<boolean>

Implementation of AccountBase.hasQuery

hasStory

hasStory(name: string): Promise<boolean>
Whether this account has a story with this name, without throwing when it does not.
Parameters
- name: string
Returns Promise<boolean>

Implementation of AccountBase.hasStory

importDataset

importDataset(sourceDataset: Dataset, opts: ImportDatasetOpts): Promise<Dataset>
Copies a dataset from another instance into this account.
Parameters
- sourceDataset: Dataset
  The dataset to copy, obtained from the App it lives on.
- opts: ImportDatasetOpts
Returns Promise<Dataset>

Remarks
For moving content between deployments. Destructive: opts.overwrite must be true, and a dataset of the same name in this account is replaced rather than merged into.

Throws
If the source is on the same instance as this account — importing is only supported between different instances. Use Dataset.importFromDataset to copy within one.

Implementation of AccountBase.importDataset

importQuery

importQuery(sourceQuery: Query, opts: ImportQueryOpts): Promise<Query>
Copies a saved query from another instance into this account.
Parameters
- sourceQuery: Query
- opts: ImportQueryOpts
Returns Promise<Query>

Remarks
Destructive in the same way as AccountBase.importDataset. The query's dataset must already exist in this account, since a query without its data cannot run.

Throws
If the source is on the same instance as this account.

Implementation of AccountBase.importQuery

importStory

importStory(sourceStory: Story, opts: ImportStoryOpts): Promise<Story>
Copies a story from another instance into this account.
Parameters
- sourceStory: Story
- opts: ImportStoryOpts
Returns Promise<Story>

Remarks
Destructive in the same way as AccountBase.importDataset. A story is a shell around saved queries, so import those first or its elements will have nothing to show.

Throws
If the source is on the same instance as this account.

Implementation of AccountBase.importStory

pinItems

pinItems(items: (Dataset | Query | Story)[]): Promise<Group>
Sets which datasets, stories and queries are pinned to this account's profile.
Parameters
- items: (Dataset | Query | Story)[]
Returns Promise<Group>

Remarks
Replaces the pinned list rather than adding to it, and the array's order becomes the display order. To add one, read AccountBase.getPinnedItems first and pass the result back with your addition; passing an empty array unpins everything.

Implementation of AccountBase.pinItems

removeMember

removeMember(member: User): Promise<void>
Removes a user from this group.
Parameters
- member: User
Returns Promise<void>

Remarks
The group's datasets, queries and stories stay — they belong to the group, not to its members.

Throws
If the user is not a member.

runPipeline

runPipeline(opts: RunPipelineOpts): Promise<Pipeline>
Runs saved queries as one batch job and writes their results into a dataset.
Parameters
- opts: RunPipelineOpts
  The queries to run and the dataset to write to. source is only needed when the queries do not all target the same dataset.
Returns Promise<Pipeline>

Remarks
The way to materialise query results at scale, rather than paging through them in process. The returned Pipeline has started but not finished — wait for it with Pipeline.waitForPipelineToFinish, or follow it through opts.onProgress.

Throws
If opts.queries is empty; or, when opts.source is omitted, if the queries reference no dataset at all or reference more than one — in both cases pass source explicitly.

Implementation of AccountBase.runPipeline

setAvatar

setAvatar(pathOrBuffer: string | Buffer<ArrayBufferLike>): Promise<void>
Replaces this account's profile image.
Parameters
- pathOrBuffer: string | Buffer<ArrayBufferLike>
  Path to an image file, or its contents.
Returns Promise<void>

Implementation of AccountBase.setAvatar

update

update(updateObj: Omit<GroupUpdate, "pinnedDatasets">): Promise<Group>
Changes this account's profile fields.
Parameters
- updateObj: Omit<GroupUpdate, "pinnedDatasets">
Returns Promise<Group>

Remarks
Only the fields you pass are changed; the rest are left alone. Pinned items are not settable here — use AccountBase.pinItems.

A Group widens this to accept accessLevel as well, since only a group has one.

Implementation of AccountBase.update

Class Group

Remarks

Example: Get a group, then one of its datasets

Example: Create a group on first run

Hierarchy

Implements

Index

Properties

Methods

Properties

ReadonlyaccountType

slug

Methods

addDataset

Parameters

Returns Promise<Dataset>

Remarks

Throws

addMember

Parameters

Returns Promise<GroupMember>

Throws

addQuery

Parameters

Returns Promise<Query>

Throws

addStory

Parameters

Returns Promise<Story>

Throws

asGroup

Returns Promise<Group>

Remarks

Throws

asOrganization

Returns Promise<Group>

Deprecated

asUser

Returns Promise<User>

Remarks

Throws

changeRole

Parameters

Returns Promise<GroupMember[]>

delete

Returns Promise<void>

Remarks

ensureDataset

Parameters

Returns Promise<Dataset>

Remarks

Throws

ensureStory

Parameters

Returns Promise<Story>

Remarks

Throws

getDataset

Parameters

Returns Promise<Dataset>

Throws

getDatasets

Returns ResultIterator<DatasetInfo, Dataset>

Remarks

getInfo

Parameters

Returns Promise<GroupInfo>

Remarks

getMembers

Returns Promise<GroupMember[]>

getPinnedItems

Returns Promise<(Dataset | Query | Story)[]>

Remarks

getQueries

Returns ResultIterator<QueryInfo, Query>

Remarks

getQuery

Parameters

Returns Promise<Query>

Throws

`Readonly`accountType