@triply/triplydb
    Preparing search index...

    Class Query

    A saved query: a stored SPARQL query that can be run, versioned and shared.

    Obtain one from an Account with getQuery or addQuery, and iterate an account's queries with getQueries. Queries are never constructed directly.

    const query = await account.getQuery("my-query");
    for await (const binding of query.results().bindings()) {
      console.log(binding);
    }

    const v3 = await (await account.getQuery("my-query")).useVersion(3);
    Index
    slug
    version
    addVersion copy delete execute getApiUrl getDataset getInfo getRunLink getString results runAsSelectQueryJob runPipeline update useVersion
    slug: string

    The query's short name, as it appears in its URL.

    • get version(): number | undefined

      The version this object is pinned to, or undefined when it follows the latest.

      Returns number | undefined

    • Saves a new version of this query.

      Parameters

      Returns Promise<Query>

      This query, now on the new version.

      Versions are how a saved query changes without breaking callers pinned to an older one. Anything you leave out of args is carried over from the current latest version, and this object switches to the latest version before saving.

    • Copies this query, optionally into another account.

      Parameters

      • OptionalqueryName: string

        Name for the copy; this query's name is reused when omitted.

      • Optionalaccount: User | Group

        Account to copy into; the token's own account when omitted.

      • OptionalmetadataToReplace: DuplicateOptions

        Metadata to change on the copy rather than carry over.

      Returns Promise<Query>

      The new query, not this one.

      IncompatibleError against an instance older than 23.09.0.

    • Deletes this query and all its versions.

      Returns Promise<void>

      Destructive and not undoable. Stories built on this query lose what they were showing.

    • Applies this query, for a query whose text is a SPARQL Update.

      Parameters

      • OptionalvariableValues: VariableValues

        Values for the query's variables; its own defaults are used for the rest.

      Returns Promise<void>

      The whole update is one transaction: either every operation in it takes effect, or none does. It runs on TriplyDB's built-in engine and rewrites the dataset's own data, so any service of that dataset is left showing the older data until you update it — see Service.update.

      Applies the version this object is on, so pinning one with Query.useVersion decides which update text is applied. Queries go through Query.results instead.

      If this query is not a SPARQL Update, or is saved against a service rather than TriplyDB's built-in engine.

      If the instance has SPARQL Update disabled, or the token may not write to the dataset.

      const query = await account.getQuery("archive-old-things")
      await query.execute()

      SPARQL 1.1 Update

    • This query's URL on the API, for building your own requests against it.

      Returns Promise<string>

    • The dataset this query runs against.

      Returns Promise<Dataset | undefined>

      The dataset, or undefined for a query saved without one — possible for a query created through the console.

    • This query's metadata: its name, access level, variables and version count.

      Parameters

      • refresh: boolean = false

      Returns Promise<QueryInfo>

      Cached after the first call. Pass true to refetch after a change made elsewhere.

    • The URL that runs this query and returns its results, for use outside this library.

      Returns Promise<string>

    • The query text, with variables filled in.

      Parameters

      • OptionalvariableValues: VariableValues

        Values to substitute; the query's own defaults are used for the rest.

      Returns Promise<string>

      Useful for logging what will run, or handing the text to another tool.

      If the query has no versions, and therefore no text.

    • Runs the query and gives you an iterator over its results.

      Parameters

      • Optionalvariables: VariableValues

        Values for the query's variables; its own defaults are used for the rest.

      • Optionalopts: { cache?: Cache }

        Pass cache to reuse earlier results, so a rerun does not hit the server.

      Returns {
          bindings: () => QueryResultIterator<Binding, Binding>;
          boolean: () => QueryResultIterator<AskResponse, boolean>;
          statements: () => QueryResultIterator<Quad, Quad>;
      }

      • bindings: () => QueryResultIterator<Binding, Binding>

        The results as variable bindings, for a SELECT query.

        If this query is not a SELECT.

      • boolean: () => QueryResultIterator<AskResponse, boolean>

        The single answer to an ASK query, as an iterator that yields exactly one boolean.

        If this query is not an ASK.

      • statements: () => QueryResultIterator<Quad, Quad>

        The results as RDF statements, for a CONSTRUCT or DESCRIBE query.

        If this query is neither CONSTRUCT nor DESCRIBE.

      Nothing is fetched until you start consuming: call bindings() on the result for a SELECT query, statements() for CONSTRUCT or DESCRIBE, or boolean() for ASK — asking for the wrong one throws. Pages are fetched as you go, so a large result set never has to fit in memory.

    • Run job as a pipeline on TriplyDB. This works for construct queries of arbitrary duration and output size.

      Returns AsyncGenerator<any, void, unknown>

      An async iterable of parsed JSON objects, one per line. The first object contains an array of projected variables

      Marked as deprecated, as this functionality will move to TriplyDB flows in 2026

    • Runs this query as a batch job and writes its results into a dataset.

      Parameters

      • opts: Omit<RunPipelineOpts, "queries">

        Where to write the results, and optionally a progress callback.

      Returns Promise<Pipeline>

      The single-query form of Account.runPipeline. Use it to materialise results rather than paging through them in process; the returned Pipeline has started but not finished.

    • Pins this object to one version of the query.

      Parameters

      • version: number | "latest"

        Version number, or "latest".

      Returns Promise<Query>

      This query, for chaining.

      Mutates this object rather than returning a new one. Pin a version so a later edit by someone else cannot change what your code runs; pass "latest" to follow the newest again.

      If the query has no versions at all, or no version with that number.

    Settings

    On This Page
    Properties
    Accessors
    Methods