JavaScript API | AllegroGraph 9.0.1
Author: Franz Incorporated

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# AllegroGraph 9.0.1 JavaScript API

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- Overview
- Parts and Triples
- The Triple Store
- Cursors
- Namespace Management
- Geospatial Part Encoding
- Graph/Network Operations
- UPI Hash Tables
- Custom Service Definitions

Documentation Index

The AllegroGraph server can be scripted using Common Lisp or JavaScript. The easiest way to get started with Javascript is to open a repository in WebView and select 'Utilities->Scripts' from the navigation bar.

This document describes the programming interface available to JavaScript programs running in an AllegroGraph server.

## Overview

The simplest way to run scripts is to use the `/eval` HTTP service, using a `text/javascript` content-type for your request. This will cause the body of the request to be evaluated as JavaScript. If an error is raised, it will be returned as an HTTP error. If not, the result of evaluating the code is returned. Usually, you'll want to specify that you accept `application/json` responses, and receive the result in that form. If your code returns a cursor, you can also specify one of the formats suitable for that kind of cursor (like `application/trix` for triple cursors, or `application/sparql-results+xml` for SPARQL SELECT cursors).

It is also possible to define custom HTTP services using JavaScript. Here, you'll probably want to put your code in a server-side script file, with a `.js` extension, and use the `x-scripts` header to ensure your service is available. See the `server.defineService` API function described below.

Note that, unless you are using a session, each `/eval` request will run in its own environment, and thus not see variables and state created by previous requests.

## Parts and Triples

The `Part` function, when given a string, tries to parse it using N-Triples syntax, and returns a part value. This constructor has the following properties, used for constructing parts in other ways:

`literal(string [, language])`
  Create a literal.
`literalTyped(string, type)`
  Create a typed literal.
`resource(string [, namespace])`
  Create a resource. If namespace is given, it is looked up (see namespaces) and prepended to the resource name.
`fromInt(int)`, `fromUnsignedInt(int)`, `fromLong(long)`, `fromUnsignedLong(long)`
  Create an encoded part from an integer value.
`fromFloat(float)`, `fromDouble(double)`
  Create an encoded part from a floating-point value.
`fromSeconds(seconds)`
  When given an amount of seconds relative to 1900, encodes the time as a part.
`fromDate(milliseconds)`
  Like `fromSeconds`, but divides its argument by 1000, and uses 1970 as reference point. This can be used to convert JavaScript `Date` objects to parts, since those (when converted to number, which this function implicitly does) will return an amount of milliseconds since 1970.

Part values themselves have the following properties:

`toString()`
  Returns an N-Triples representation of the part.
`value`
  The main value of the part. For resources, this is the URI, for literals, the string, for encoded values, usually a number.
`type`
  A string, such as `"literal"` or `"resource"`, which identifies the type of the part.
`language`
  The language of a literal, or `null` if no language is specified.
`datatype`
  The datatype of a literal, or `null` if no language is specified.

`Triple` objects, as returned by, for example, `store.getTriples`, have `object`, `predicate`, `subject`, and `graph` properties, which will return parts, and an `id` property, which will return an integer.

## The Triple Store

The top-level `store` variable provides an interface to the current triple store (as determined by the URL from which the request is made). It is an instance of the `Store` type, and has the following properties:

`name`
  The name of the store.
`getTriples(subject, predicate, object, graph)`
  Returns a triple cursor containing the triples in the store that match the given query. Each of the arguments can be left as null (or not given) to specify a wildcard. The arguments may be `Part`s or arrays of two `Part`s. The latter case is used to specify range queries. Note that only one range query can be specified at a time.
`getTriplesArray(subject, predicate, object, graph [, limit])`
  Like getTriples, but returns an array instead of a cursor. If `limit` is given, it provides a maximum length for the returned array.
`deleteTriples(subject, predicate, object, graph)`
  Deletes all matching triples. As in `getTriples`, null and undefined count as wildcards and arrays can be used to specify a range query.
`addTriple(subject, predicate, object [, graph])`
  Adds a new triple. Graph is optional.
`size`
  The amount of triples in the store.
`commit()`, `rollback()`
  Commit or roll back the store.
`newBlankNode()`
  Returns a newly allocated blank node.
`runSparql(query)`
  Evaluates the given SPARQL query, and returns, depending on the type of query, a boolean, a triple cursor, or a row cursor. SPARQL/Update is supported (when the user has write access).
`runProlog(query)`
  Evaluates the given Prolog query. Will typically return an array of arrays of parts, but the exact format returned depends on the form of the query.
`textIndices`
  A list of names, corresponding to the full text indices present in the store.
`createTextIndex(name [, options])`
  Create a text index. `options`, if given, is an object containing options for the store. The properties `predicates`, `indexFields`, `indexResources`, `indexLitrals`, `minimumWordSize`, `stopWords`, and `wordFilters` are supported, and accept values similar to those in the Lisp API.
`dropTextIndex(name)`
  Drop a text index.
`textSearch(query [, index])`
  Search the given text index (or all of them, when `index` is left off) for the given query string. Returns a triple cursor.
`indices`
  A list of indices present in the store.
`addIndex(type)`
  Add a new index. Type must be a `posgi`-style specifier.
`dropIndex(type)`
  Delete an index.

## Cursors

Cursors have the following properties:

`next()`
  Returns the next value from the cursor, or `null` if the cursor is exhausted. For triple cursors, this will return a triple. For row cursors, you get an array of parts.
`close()`
  Closes the cursor, freeing any resources it holds. Note that all cursors are closed automatically after a script runs, so you only need this when you expect to be creating a large amount of cursors.
`forEach(func)`
  Calls `func` on each row in the cursor.
`collect([limit])`
  Returns an array holding all the rows in the cursor. If `limit` is given, it limits the amount of rows that are collected.
`count()`
  Counts the amount of rows in the cursor (and exhausts it).
`names`
  Only available for row cursor. Returns an array of strings, the names of the rows.

## Namespace Management

There is a toplevel `namespaces` object with these methods:

`collect()`
  Returns an array of `{name, uri}` objects representing the namespaces.
`register(name, uri)`
  Register a new namespace.
`unregister(name)`
  Remove a namespace.
`clear()`
  Remove all namespaces.
`reset()`
  Go back to the standard namespaces.
`lookup(name)`
  Return the URI associated with the given name, or `null` if the namespace is not defined.

## Geospatial Part Encoding

The `GeoType` constructor provides an interface to geospatial encodings. Instances are created through these methods:

`cartesian(store, xmin, xmax, ymin, ymax, strip-width)`
  Defines a cartesian geospatial system for the given store.
`spherical(store, strip-width [, unit])`
  Defines a spherical system. `unit` can be one of degree, radian, km, or mile, and defaults to degree.

`GeoType` instances have these properties:

`datatype`
  The RDF datatype associated with this type.
`encode(x, y)`
  Encode a geospatial part in this system. For spherical systems, `x` takes the longitude, and `y` the latitude.

## Graph/Network Operations

All graph operations are modeled around 'generators', which, conceptually, are functions that take a node, and produce a set of 'neighbors', by some definition of neighbor. The `Generator` constructor can be called in two ways. In both, it takes a store as its first argument. When its second argument is a function, it wraps that function as a generator. The function should take a single part as an argument, and return an array of parts. When the second argument is not a function, the signature of the constructor is `(store, objects, subjects, undirected)`, where each of the last tree arguments can be `null`, a predicate part, or an array of predicates. The set of predicates indicated by the `objects` parameter causes relations with those predicates to be followed from the starting node to any objects. The `subjects` parameter does the reverse—it follows relations from object to subject. Finally, the `undirected` parameter causes both of these to happen for the given predicates.

Generator instances have the following methods:

`asMatrix(group, maxdepth)`
  Converting a generator to a matrix returns a new generator which is a pre-computed version of the original generator. The `group` parameter should be an array of parts, and `maxdepth` an integer, indicating how many 'jumps' (starting from this group) should be pre-computed. The return value is again an instance of `Generator`, and supports all the methods listed below.
`breadthFirstPath(from, to [, maxdepth])` `depthFirstPath(from, to [, maxdepth])` `bidirectionalPath(from, to [, maxdepth])`
  These three methods try to compute and return a path between two parts, giving up after `maxdepth` jumps (or not giving up if no maximum depth is given). The return value will be an array of parts, or `null` if no path was found.
`breadthFirstPaths(from, to [, maxdepth])` `bidirectionalPaths(from, to [, maxdepth])`
  These work just like the methods described above, but will return an array containing all the shortest paths found, or the empty array if no path was found.
`neighbors(node [, maxdepth])`
  Returns an array containing all the parts that can be reached within `maxdepth` jumps from `node`. If not given, `maxdepth` defaults to 1.
`cliques(node [, minsize [, maxsize]])`
  Finds and returns any cliques (completely connected subgraphs) that `node` is part of. `minsize` defaults to 3.
`isClique(nodes)`
  Given an array of parts, returns a boolean that indicates whether this group is a clique.

## UPI Hash Tables

Hash tables specialized for UPIs are exposed through the `UPIHash` constructor. These are much faster than using regular JavaScript objects to keep a mapping on triple parts. The constructor takes an optional size argument. Instances have the following methods:

`set(key, value)`
  Store `value` under the part given as `key`.
`get(key)`
  Retrieve the value stored under this key.
`del(key)`
  Remove the given key from the table.
`keys()`
  Returns an array holding all the keys in the table.
`forEach(func)`
  Calls `func` with `(key, value)` arguments for every entry in the table.

## Custom Service Definitions

The `server` variable exposes a method `defineService(method, name, func)` which can be used to define a JavaScript custom service. `method` must be a string (one of `"get"`, `"post"`, `"put"`, and `"delete"`), or an array of such strings. `name` is a string that will name the service, and finally, `func` must be a JavaScript function of one argument.

The service will be exposed at `/catalogs/CATALOG/repositories/REPO/custom/NAME` and `/repositories/REPO/custom/NAME`.

When the service is called, this function will be applied to a request object, and its return value will be returned to the user, using the same content-negotiation process that was used for `/eval` (as described before).

The request object can be used to get information about the request. It has the following properties:

`url`
  The URL to which this request was made.
`method`
  The method used for the request, as a lowercase string.
`param(name)`
  Retrieves the value of a parameter. This includes url-query ('get') parameters, and parameters found in the request body if it has a content-type of `application/x-www-form-urlencoded`. Returns `null` if the parameter was not given.
`paramArray(name)`
  Works like `param`, but returns an array, allowing you to see whether a parameter has been given multiple times.
`params`
  An object with the parameter names as property names, their values as property values.
`body`
  The body of the request, as a string, or `null` if no body was given.
`header(name)`
  Retrieves the value of a request header.