These global objects serve as main entry point into the API. See https://archive.topquadrant.com/doc/latest/scripting/index.html for background and more details on ADS.
The main entry point into the API (beside focusNode).
For editable graphs, this returns a GraphChanges object that can be used to fetch details about which triples have been added or removed by the current script, with the option to roll back those changes.
GraphChanges:
Performs a SPARQL CONSTRUCT query, resulting in an array of Triple objects.
(string)
a SPARQL SELECT query
(object??)
an optional object with name-value pairs to pre-bind for the query execution
(boolean??)
true to only return GraphNodes and neither boolean, number nor string
Array<Triple>:
the resulting triples
Checks if the graph contains any triple matching the provided subject, predicate, object combination, where each can be null to indicate a wildcard search.
(any?)
the object to match or null (JavaScript numbers that can be cast to integer will be matched to
either xsd:integer or xsd:decimal).
Evaluates a SPARQL expression, as used in BIND or FILTER. You can use EXISTS { ... } expressions similar to SPARQL ASK queries.
(string)
a SPARQL expression
(Object?)
an optional object with name-value pairs to pre-bind for the query execution
(boolean?)
true to only return GraphNodes and neither boolean, number nor string
any:
the result of the evaluation, either as a plain JavaScript value or a GraphNode (or null)
Returns a LiteralNode with datatype rdf:HTML with a given string as lexical form.
(string)
the lexical form
LiteralNode:
Returns a LiteralNode with datatype rdf:langString with a given string as lexical form and a given language tag.
LiteralNode:
Produces an instance of LiteralNode from a given input value.
LiteralNode:
a LiteralNode or null if the value is null or undefined
Converts a value into an instance of GraphNode. String are converted into LiteralNode with datatype xsd:string. Numbers are converted into either xsd:integer or xsd:decimal LiteralNodes. Booleans are converted into true or false LiteralNodes. If the input object already represents an instance of a subclass of GraphNode then that object will be morphed into an GraphNode. If the input object is an object with a field { uri: "..." } or { qname: "..." } then the result will be a URI node. If the input object is an object with a field { lex: "..." } then the result will be a literal. Use lang: "..." for rdf:langString literals and datatype: xsd.float for specific datatypes. xsd:string is the default datatype. An exception is raised if no suitable conversion is possible. Returns null if the input value is null or undefined.
GraphNode:
Performs a GraphQL query against the data graph and returns the response JSON. This is only supported for queries (not mutations) and only if the current query graph is an asset collection that is not an Ontology/shapes graph or File. The response JSON will use the field "data" for the actual query results or "error".
(string)
the query string
(object?)
an optional object with name-value pairs for the pre-defined variables
object:
the GraphQL query response or null in case of low-level errors
Deletes a triple (or multiple triples) from the (base) graph. If the triple is included from an imported sub-graph then it will remain in those. The function can take null as wildcards for any subject, predicate or object. In this case it will remove all matching triples.
Performs a SPARQL SELECT query.
(string)
a SPARQL SELECT query
(object??)
an optional object with name-value pairs to pre-bind for the query execution
(boolean??)
true to only return GraphNodes and neither boolean, number nor string
ResultSet:
the result bindings
Sets a namespace prefix for the query model, or removes a prefix declaration. As this is a low-level operation affecting all users of this graph, this needs to be used with care.
Runs an SWP element with a provided set of parameters. This can not be used in read-only mode and should be used by experienced TopBraid users only.
NOTE: This function is likely going to be deleted in future versions. Instead users are encouraged to explicitly mark the SWP scripts that they want to call by making them instances of ui:Service and assigning a value for dash:apiStatus (and possibly dash:canWrite) and then use the generated functions. Meanwhile this function here is kept to simplify experiments.
(string)
the qname of the view class in the ui:graph, e.g. 'ex:MyElement'
(object??)
name-value pairs for the arguments of the element, typically as GraphNodes
string:
the SWP response as a string
Performs a read/write transaction on either the current data graph (if first argument is null) or a selected graph. If the first argument if provided, the function temporarily switches the active data graph to the given named graph and executes a function with that active graph. The new graph will also become the default graph of SPARQL queries. After the function has been executed, the previously active data graph will become active again. The result of the transaction call is the result of its callback. Assuming the script is not executed in read-only mode, the inner graph is writable. The system will activate a "diff graph" that collects all changes, and features such as graph.changes can be used. At the end of the transaction, the changes will be committed, unless no changes have been made. Use graph.changes.rollBack() at the end of a transaction in case you want to make sure that no changes will be committed.
(string?)
a log message for the change history, or null for an automatically generated message
(function)
a function (that has no parameters) that will be called (immediately)
any?:
the result of the callback
Queries the graph and produces an array of objects with the fields { subject, predicate, object } for each triple that matches the given match subject, predicate and object (any of which may be null to act as a wildcard). Note that this may potentially return a very large number of matches, so needs to be handled with care. Also note that this will only return the asserted triples in the graph.
(NamedNode??)
the subject to match against or null for any
(NamedNode??)
the predicate to match against or null for any
(boolean??)
true to only return GraphNodes and neither boolean, number nor string for the object position
Array<Triple>:
an array of objects with subject, predicate and object fields
Performs a SPARQL UPDATE. This only works if the graph is in read/write mode. It can only modify the default query graph, i.e. don't use INSERT { GRAPH ... { } } or such. If the default query graph is a persistent temp graph then the diff graph infrastructure is bypassed for faster execution.
Gets an uploaded file from a provided ID.
(string)
the ID of the file, typically provided as parameter value from an Action
UploadedFile:
Temporarily switches the active data graph to a given named graph and executes a function with that active graph. The new graph will also become the default graph of SPARQL queries. After the function has been executed, the previously active data graph will become active again. The result of the withDataGraph call is the result of its callback. The graph becomes read-only inside of such blocks. To perform changes to other graphs than the default graph, use graph.transaction().
(function)
a function (that has no parameters) that will be called (immediately)
any?:
the result of the callback
Returns a LiteralNode with datatype rdf:XMLLiteral with a given string as lexical form.
(string)
the lexical form
LiteralNode:
A collection of functions to operate on the named graphs in TopBraid.
The URI of the graph that may be used to query the added triples from a dash:ChangeScript or dash:CommitScript.
The URI of the graph that may be used to query the deleted triples from a dash:ChangeScript or dash:CommitScript.
Creates a temporary graph with a fresh URI that can be used for the duration of the surrounding script. Such temp graphs may be used to collect triples, for example via graph.transaction. Temp graphs may be persistent if large processing tasks shall be performed on a temporary buffer. Despite their name, these will be automatically discarded once the script ends.
(boolean?)
true to create a graph that is persisted using a dedicated TDB dataset
string:
the URI of the new graph
Attempts to find the master graph URI for a given graph URI. The graph URI must either be of the form "urn:x-evn-master:XY" or "urn:x-evn-master:XY:UserName" or a workflow graph "urn:x-evn-tag:XY:UserName". It also handles cases where the graph is with imports.
(string)
the graph URI
string:
the master graph URI or null if the input URI does not match any of the expected patterns.
Prepares a GraphNode so that it can be used as a constant in remote SPARQL queries and updates. In particular, this converts blank nodes into URIs following TopBraid's blank node mapping syntax.
(GraphNode)
the node to convert
any:
the converted NamedNode or the node itself
Performs a SPARQL SELECT query against a SPARQL endpoint that is linked to a remote asset collection (using tosh:remoteEndpoint etc).
(string)
the URI of the asset collection, e.g. 'urn:x-evn-master:remotegeo'
(string)
the SELECT query string including prefixes where needed
(boolean??)
true to only return GraphNodes and neither boolean, number nor string
ResultSet:
the result bindings, same as graph.select
Performs a SPARQL UPDATE against a SPARQL endpoint that is linked to a remote asset collection. Note that this is not going to update the local TopBraid copy of that graph. If the asset collection is limited to a certain named graph (tosh:remoteNamedGraph) then the query must also only modify that graph (although this is currently not validated).
Gets a variant of an input graph URI that also includes the owl:imports. This uses a platform-specific URI naming convention that will be understood by most dataset operations. This is equivalent to the SPARQL function ui:graphWithImports(?graphURI).
string:
the graph URI with imports
These classes are instantiated by the graph API to represent RDF nodes. The root class GraphNode has the two subclasses NamedNode (for URIs and blank nodes) and LiteralNode (for literal values such as xsd:date nodes). Note that the most common literal types (xsd:string, xsd:boolean and numeric types) are typically represented by simple JavaScript values (strings, booleans and numbers).
GraphNode is the base class of all graph node types.
(any)
Compares this node with another node or value. For example, the other might be a string, and equals would return true if this is a corresponding xsd:string literal.
boolean:
true if this is equal to the other value
Evaluates a SPARQL expression with $this bound to the current node.
(string)
a SPARQL expression such as "EXISTS { $this a g:Country }" or "ex:function($this)"
(Object??)
an optional object with name-value pairs to pre-bind for the query execution
(boolean??)
true to only return GraphNodes and neither boolean, number nor string for the object position
any:
the result of the evaluation
Performs a SPARQL SELECT query with $this bound to the current node.
(string)
a SPARQL SELECT query
(object??)
an optional object with name-value pairs to pre-bind for the query execution
(boolean??)
true to only return GraphNodes and neither boolean, number nor string
ResultSet:
the result bindings
Gets a GraphNodeArray representing all asserted incoming/inverse values of a given property (or property array) of this.
GraphNodeArray:
The class of graph nodes that are representing RDF literals.
Extends GraphNode
The URI of the datatype, if this node represents a literal.
string:
the datatype URI
The language code, if this node represents a literal. Returns undefined otherwise.
string:
the language code such as "en"
The lexical (string) form, if this node represents a literal. Returns undefined otherwise.
string:
the literal, always as a string
Attempts to convert this into a primitive JavaScript literal of type boolean, string or number. If that is not possible due to the datatype, this returns this unchanged.
(boolean | number | string | LiteralNode):
The class of graph nodes that are representing URIs or blank nodes.
Extends GraphNode
(any)
The URI string of nodes where isURI() returns true, and '_:' + blankNodeId for those where isBlankNode() returns true.
string:
the URI string
Checks whether this is an instance of a given (RDFS) class.
boolean:
true if this has the type or a subclass thereof as its rdf:type, false otherwise
Gets the value of this node for a given path as a LiteralNode. If multiple values exist then it will make a random choice.
LiteralNode?:
the path value as LiteralNode or null
Gets the values of this node for a given path as a instances of LiteralNode.
Array<LiteralNode>:
the path values as LiteralNodes (dropping any non-literals)
Gets a GraphNodeArray representing all values of a given property or array of properties of this. This function only returns the asserted values, while the values function would also return inferred values.
GraphNodeArray:
Gets the value of this node for a given path as a NamedNode. If multiple values exist then it will make a random choice.
(object??)
an optional subclass of NamedNode to convert the result into
NamedNode?:
the path value as NamedNode or null if no value exists or it's a literal
Gets the value of this node for a given path as a string. If multiple values exist then it will make a random choice.
string?:
the path value as string or null if no value exists or is not a literal
Gets the value of this node for a given path. If multiple values exist then it will make a random choice.
(object??)
an optional subclass of NamedNode to convert the result into
(GraphNode? | boolean? | number? | string?):
the path value as GraphNode or primitive JavaScript value, or null
Gets all values of this node for a given path as an array.
(object??)
an optional subclass of NamedNode to convert the results into
(boolean??)
true to return the values by their dash:index (if exists)
GraphNodeArray:
an array of path values as GraphNodes or primitive JavaScript values
A subclass of Array for booleans, numbers, strings, LiteralNodes or NamedNodes, with dedicated helper functions for typical graph-based operations.
Extends Array
Produces a GraphNodeArray by changing the type of an existing JavaScript array.
(Array<any>)
the input array
GraphNodeArray:
the input array but with a different type
Returns a new GraphNodeArray that has any duplicate nodes eliminated, using equals semantics. This may be useful after concatenating two or more GraphNodeArrays.
GraphNodeArray:
Assuming the first array item represents a literal, this will return it as a LiteralNode, otherwise undefined.
LiteralNode?:
Gets a new GraphNodeArray consisting of all objects of triples where the members of this are the subjects and one or more given properties are the predicates.
(boolean?)
true to only return NamedNodes or LiteralNodes
GraphNodeArray:
Gets a new GraphNodeArray consisting of all subjects of triples where the members of this are the objects and one or more given properties are the predicates.
GraphNodeArray:
Returns a new GraphNodeArray consisting of only those items in the current array that are subject in triples with a given property and a given object, or any object.
(NamedNode)
the match predicate
GraphNodeArray:
Returns a new GraphNodeArray consisting of only those items in the current array that are object in triples with a given property and a given subject, or any subject.
(NamedNode)
the match predicate
(NamedNode?)
the match subject or nothing for any match
GraphNodeArray:
Returns a new GraphNodeArray consisting of the items in this and a given other array.
(GraphNodeArray)
GraphNodeArray:
(any)
GraphNodeArray:
(any)
GraphNodeArray:
Represents the graph types, aka asset collection types, of the system.
(any)
The URI of this graph type, e.g. 'http://edg.topbraid.solutions/model/DataAssetsProjectType' for Data Asset collections.
string:
Utility functions operating on GraphNodes.
Produces a JSON object by recursively walking a blank nodes (subject) and its (object) values. Each NamedNode is represented by a JSON object that has the property values as fields, so that the value key is the URI of each predicate, and the values are arrays of nested objects or primitive values. The algorithm will terminate recursion at URI nodes, for which it only produces label and uri.
(NamedNode)
the current named node
Object:
A helper function to enable TopBraid.installFunction(). It is used to prepare an object tree so that it can be serialized as JSON without containing all the property values of GraphNodes. If the input object is a GraphNode it will produce a simplified object with only the core fields such as uri and lex, plus a __type field with the name of the original class.
(any?)
the object to flatten the graph nodes of
The opposite of flattenGraphNodes. Attention: this may modify the input objects, replacing any object with a __type field to become GraphNode instances.
(any?)
the value to unflatten
any:
either the original obj or a new one
The class of SPARQL result sets, typically produced by a SELECT query.
(any)
A tag string function that inserts JavaScript expressions as well-formed SPARQL expressions.
For example, use sparqlASK { ${subject} rdfs:label ?label } where subject is a GraphNode.
This is an alternative to using pre-bound variables (e.g. the bindings argument of graph.select).
Note that producing distinct strings carries a bit of performance overhead (for parsing)
while pre-bound variables can reuse an already parsed query object, at least within the same request.
However, string substitution can be a more compact, more natural and more flexible solution.
(any)
the string segments
(...any)
string:
a string using SPARQL syntax substitution
An API to access common I/O operations including the ability to work with uploaded files and making HTTP requests.
If IO.debug logging has been activated, this will print the given arguments similar to console.debug() into the console and into the server log.
Performs a HTTP request and either returns the response or writes the response into a (temporary) file that can be processed separately. The API is similar to Axios but waits until the request has completed. This function can be disabled by the server setup configuration disableADSHTTP=true.
(Object)
the request descriptor
| Name | Description |
|---|---|
request.url string
|
The URL to send the request to. |
request.baseURL string?
|
Will be prepended to url (for convenience). |
request.method string?
|
The request method such as 'post', defaulting to 'get' |
request.headers Object?
|
Name-value pairs for HTTP request headers. |
request.params Object?
|
Name-value pairs for the HTTP request parameters. |
request.data string?
|
The request body data. Only applicable for PUT, POST, DELETE and PATCH. |
request.contentType string?
|
Overrides the default content type, which is text/plain if data is specified, or application/x-www-form-urlencoded otherwise. |
request.username string?
|
The user name for HTTP Basic authentication. |
request.password string?
|
The password to use for authentication. If left empty, and authentication is enabled (if userName is present), then the password will be retrieved from Secure Storage. |
request.securePasswordURL string?
|
When retrieving the password from Secure Storage, get the password for this URL instead of the password for url. Only allowed if the request URL (url) starts with the securePasswordURL. |
request.toFileSuffix string?
|
If present, the response body will be saved as a file that can the accessed using IO.uploadedFile(). The response JSON will include the file ID as value of the 'file' field. The value will be used as file suffix. For example if you are downloading a TSV file, use 'tsv' so that IO.uploadedFile(response.file).asSpreadsheet() does the right thing. |
HttpResponse:
response The HTTP response as an object
Parses the text of an RDF file (e.g., in Turtle format) and places them into a fresh temporary graph that can then be queried further, e.g. using graph.withDataGraph or SPARQL's GRAPH keyword.
(string)
the content of the file to parse, e.g. retrieved using IO.uploadedFile(file).text
(string?)
A content type such as "application/rdf+xml" defaulting to Turtle+
string:
the URI of a temp graph that contains the resulting RDF triples and prefixes
For dash:Actions that have dash:showProgress true, this updates the status text and potentially the progress monitor.
For use within ADS-based web services, this sets HTTP response headers that will be used when the
service ends normally.
Gets an uploaded file from a provided ID.
(string)
the ID of the file, typically provided as parameter value from an Action
UploadedFile:
The class of (uploaded) files, providing access to the content, mime type etc. The typical workflow is that a dash:Action requests a user to upload a file by setting dash:mimeTypes on one of its parameters, and keeps its ID as a reference. That fileId string is used to construct instances of this class here.
The name is not simply 'File' to avoid clashes with the namesake class from the W3C Web API.
(any)
Assuming this file represents a spreadsheet, cast it into a Spreadsheet instance. This is only supported for files with suitable mime types. Note this will load the whole spreadsheet into memory but provides random access to all rows and cells.
(string?)
the optional file encoding, defaulting to UTF-8
UploadedSpreadsheet:
Assuming this file represents a .csv or .tsv spreadsheet, cast it into a SpreadsheetIterator instance. Use this if your spreadsheet is potentially very large.
(string?)
the optional file encoding, defaulting to UTF-8
SpreadsheetIterator:
Assuming this is a valid RDF file, imports the content of the file into the currently active graph. This uses a streaming loader that will insert all triples without further checking. This operation is ONLY supported when the currently active graph is the production copy as this will bypass the change history.
(string?)
the mime type of the file; if unspecified it will try to derive it from the file
Gets the (client) name under which this file was uploaded to the server.
string:
The class of (uploaded) Spreadsheets, providing access to the columns, rows etc. Use UploadedFile.asSpreadsheet() to create instances.
(any)
Gets the value in a given row and column, as a string, number, boolean or LiteralNode.
(number)
the index of the row, starting at 0
(number?)
the index of the column, starting at 0, defaulting to 0
(number?)
the index of the sheet, starting at 0, defaulting to 0
(boolean | number | string | LiteralNode):
The class of spreadsheets that are opened in a streaming fashion, row by row. Use UploadedFile.asSpreadsheetIterator() to create instances. This class implements the Iterable protocol, e.g. use for(const row of s) { ... } to iterate over all rows.
(any)
Represents an XML DOM Node as delivered by UploadedFile.asXML(). In addition to the declared fields and methods, nodes that represent elements have all attributes of the XML node as direct properties. If attribute names clash with declared fields or methods then an underscore is appended.
(any)
Returns the local name. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getLocalName--
string:
Returns the namespace URI. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getNamespaceURI--
string:
Gets the node name, e.g. the tag name for element nodes. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getNodeName--
string:
Gets the node value, e.g. the content of a text node. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getNodeValue--
string:
Returns the prefix. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getPrefix--
string:
Gets the text context of this node and its descendants. See https://docs.oracle.com/javase/8/docs/api/org/w3c/dom/Node.html#getTextContent--
string:
The SQL object can be used to query a relational database using Active Data Shapes. This API can be disabled by the server setup configuration disableADSSQL=true.
Performs an SQL query against a database (specified by a connection object) and returns the result set rows as an array of name-value pairs.
(Object)
the connection descriptor
| Name | Description |
|---|---|
conn.url string
|
the URL of the database server |
conn.user string??
|
the name of the user |
conn.password string??
|
the password |
(string)
the SQL query string
Array<Object>:
an array of name-value pairs
Performs an SQL update against a database (specified by a connection object).
Type: Object
(number)
: The HTTP status code, e.g. 200 for OK
(number)
: The HTTP status message, e.g. "OK"
(Object)
: The response data if present and toFile was not true. Will be parsed JSON if response mime type contains 'json' and the result can be parsed OK.
(string)
: The file ID if toFile was set to true
(Object)
: The response headers
These are part of the API that you may rarely need directly.
Utility functions to produce values for certain dash:Viewers.
Produces an rdf:JSON literal that can be handled by the dash:GraphViewer. This function can be used in conjunction with sh:values rules that dynamically compute property values for rendering purposes on the client.
(GraphViewerProps)
the properties
LiteralNode:
an rdf:JSON literal
Produces a JSON literal that can be returned by a Modify action that has dash:wizard true, so that the action opens a "next" wizard page with additional input parameters. When you're implementing wizards, always go through this function instead of hand-producing the JSON.
(NextPageProps)
the properties of the next page (this object may get modified as a side effect)
LiteralNode:
an rdf:JSON literal in the format expected by the TopBraid ADS engine
Takes a result set object as input and produces an rdf:JSON literal that can be handled by the dash:JSONTableViewer. The result set must be an object with a string array 'vars' and an array 'bindings' with name-value pairs for each var. This is the same format as produced by graph.select(). This function can be used in conjunction with sh:values rules that dynamically compute property values for rendering purposes on the client.
(ResultSet)
the result set object with the 'raw' bindings
(JSONTableViewerProps?)
optional properties for the table viewer
LiteralNode:
an rdf:JSON literal wrapping the resultSet
Instances of this class are fetched through graph.changes and can be used to learn about the (uncommitted) changes to the graph in this session, and possibly to revert them.
Reverts all changes without committing them. After this operation, the added and removed triples will be empty.
The parameters for a GraphViewer.
Type: Object
(number?)
: an optional height in pixels, defaults to 400
(string)
: the display label of the viewer (required)
(string?)
: the name of a layout, one of: 'Circular', 'Hierarchical', 'Organic' (default)
The parameters for createNextPageJSON.
Type: Object
(Function)
: a reference to a function that is called to execute using the parameters
and which is defined in the API of the surrounding action. The function takes an optional parameter
called state but can also access the pre-assigned variables focusNode and for each provided parameter.
(boolean)
: true if this is the last page and the Finish button shall be displayed instead of Next.
(Array<WizardParameterDefinition>)
: the parameter declarations.
(boolean?)
: true to pass the parameter values as an object with name-value pairs instead
of named (scoped) variables. For example, the callback can then query params['varName'] instead of varName.
(any?)
: an arbitrary JS value to pass into the next page, becoming the variable 'state'.
Note that this JS value needs to be serializable to JSON, i.e. ADS types such as NamedNode cannot be
round-tripped correctly. Instead store their URIs as strings and then convert them back on the receiving script.
(string?)
: the optional title of the page
(string?)
: an optional message under the title
A SHACL validation result.
Type: Object
((LiteralNode | NamedNode))
: the focus node
((LiteralNode | NamedNode)?)
: the value node
(string?)
: the path in SPARQL syntax, if applicable
(string?)
: the message (in the most suitable language)
(string)
: the URI of the constraint component that produced the result
(string)
: 'Violation', 'Warning' or 'Info'
A parameter for a wizard page.
Type: Object
(string)
: the name of the variable (must be a valid JS variable name that isn't used yet)
(string?)
: the display label of the parameter
(string?)
: the URI of a dash editor to use
(string?)
: the allowed mime types for file upload
(boolean?)
: true to mark this parameter as optional
The base type for the properties of all NamedNodes, declaring the uri property.
(!string)
: the URI serving as unique identifier of the resource in the graph