Ostrich for Node.js

This package provides TypeScript/JavaScript bindings for OSTRICH RDF archives.

Concretely, it has the following features:

• Creating a new OSTRICH store
• Appending to an OSTRICH store
• Querying (VM/DM/VQ) an OSTRICH store by triple pattern.
• Obtaining cardinality estimates (VM/DM/VQ) in an OSTRICH store by triple pattern.

Installation

$ npm install ostrich-bindings

or

$ yarn add ostrich-bindings

WARNING: OSTRICH requires ZLib, Kyoto Cabinet and CMake (compilation only) to be installed. See install-kc-ci.sh on how to install Kyoto Cabinet.

Usage

Opening and closing

An OSTRICH store can be opened using fromPath, which takes path name and an option object. The OSTRICH document will be passed to the callback. Close the document with close.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich');

// --- Do stuff ---

// Don't forget to close the store when you're done
await store.close();

By default, a store will be opened in read-only mode, which will be faster. To enable writing, open the store as follows:

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

// --- Do stuff ---

// Don't forget to close the store when you're done
await store.close();

Checking if a store is closed can be done via the field store.closed;

Reading the number of versions

The number of versions available in a store can be read as follows:

console.log(store.maxVersion);

Searching for triples matching a pattern in a certain version (VM)

Search for triples with searchTriplesVersionMaterialized, which takes subject, predicate, object, options, and callback arguments.

Subject, predicate, and object can be IRIs or literals, represented as RDF/JS terms. If any of these parameters is null or a variable, it is considered a wildcard.

Optionally, a version, offset and limit can be passed in an options object, The version parameter will default to the latest available version if it is not provided. The offset and limit parameters will select only the specified subset.

The async function will return an array of triples that match the pattern, and a field indicating an estimate of the total number of matching triples.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { triples, cardinality } = await ostrichStore
    .searchTriplesVersionMaterialized('http://example.org/s1', null, null, { version: 1, offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern in the given version.');
console.log(triples);

await ostrichStore.close();

Counting triples matching a pattern in a certain version (VM)

Retrieve an estimate of the total number of triples matching a pattern in a certain version with countTriplesVersionMaterialized, which takes subject, predicate, object, version (optional), and callback arguments.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { cardinality } = await ostrichStore
    .countTriplesVersionMaterialized('http://example.org/s1', null, null, { version: 1, offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern in the given version.');

await ostrichStore.close();

Searching for triple differences matching a pattern between two versions (DM)

Similar to searchTriplesVersionMaterialized, searchTriplesDeltaMaterialized allows you to search triples matching a pattern that are changed between two given versions. Each triple is annotated with an addition field, indicating whether or not it has been added relative to the two versions.

The options object now takes the mandatory versionStart and versionEnd parameters.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { triples, cardinality } = await ostrichStore
    .searchTriplesDeltaMaterialized('http://example.org/s1', null, null, { versionStart: 0, versionEnd: 2, offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern between the two given versions.');
console.log(triples);

await ostrichStore.close();

Counting triples matching a pattern between two versions (DM)

Retrieve an estimate of the total number of triples matching a pattern in a certain version with countTriplesDeltaMaterialized, which takes subject, predicate, object, versionStart, versionEnd, and callback arguments.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { cardinality } = await ostrichStore
    .countTriplesDeltaMaterialized('http://example.org/s1', null, null, { versionStart: 0, versionEnd: 2, offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern between the two given versions.');

await ostrichStore.close();

Searching for triples matching a pattern with version annotations (VQ)

Finally, searchTriplesVersion allows you to search triples matching a pattern over all versions. Each triple is annotated with a list versions for all the versions it is present it.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { triples, cardinality } = await ostrichStore
    .searchTriplesVersion('http://example.org/s1', null, null, { offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern in all versions.');
console.log(triples);

await ostrichStore.close();

Counting triples matching a pattern (VQ)

Retrieve an estimate of the total number of triples matching a pattern over all version in a certain version with countTriplesVersion, which takes subject, predicate, object, and callback arguments.

import { fromPath } from 'ostrich-bindings';

const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { cardinality } = await ostrichStore
    .countTriplesVersion('http://example.org/s1', null, null, { offset: 0, limit: 10 });
console.log('Approximately ' + cardinality + ' triples match the pattern in all versions.');

await ostrichStore.close();

Appending a new version

Inserts a new version into the store, with the given optional version id and an array of triples, annotated with addition: true or addition: false. In the first version (0), all triples MUST be additions.

The triples that are appended can be created using the utility function quadDelta, which accepts an RDF/JS quad, and a flag indicating if it's an addition or not.

import { fromPath, quadDelta } from 'ostrich-bindings';
import { DataFactory } from 'rdf-data-factory';

const DF: RDF.DataFactory = new DataFactory();
const store = await fromPath('./test/test.ostrich', { readOnly: false });

const { insertedCount } = await ostrichStore.append([
    quadDelta(DF.quad(DF.namedNode('a'), DF.namedNode('b'), DF.namedNode('c')), true),
    quadDelta(DF.quad(DF.namedNode('a'), DF.namedNode('d'), DF.namedNode('c')), true),
]);
console.log('Inserted ' + insertedCount + ' triples in version ' + store.maxVersion);

await ostrichStore.close();

Note: if the array of triples is already sorted in SPO-order, appendSorted can be called which will result in better performance. Behaviour is undefined if this is called with an array that is not sorted.

Standalone utility

The command-line utility ostrich allows you to query OSTRICH dataset from the command line.

To install system-wide, execute:

npm install -g ostrich-bindings

Specify queries as follows:

ostrich vm dataset.ostrich '?s ?p ?o' --offset 200 --limit 100 --version 1 --format turtle
ostrich dm dataset.ostrich '?s ?p ?o' --offset 200 --limit 100 --versionStart 0 --versionEnd 2
ostrich vq dataset.ostrich '?s ?p ?o' --offset 200 --limit 100

Replace any of the query variables by an IRI or literal to match specific patterns.

Or with less verbose parameters:

ostrich vm dataset.ostrich '?s ?p ?o' -o 200 -l 100 -v 1 -f turtle
ostrich dm dataset.ostrich '?s ?p ?o' -o 200 -l 100 -s 0 -e 2
ostrich vq dataset.ostrich '?s ?p ?o' -o 200 -l 100

Build manually

To build the module from source, follow these instructions:

git clone --recurse-submodules [email protected]:rdfostrich/ostrich-node.git
cd ostrich-node
yarn install
yarn run test

If you make changes to the source, do the following to rebuild:

yarn install

License

This software is written by Ruben Taelman, Miel Vander Sande, and Olivier Pelgrin.

This code is copyrighted by Ghent University – imec and released under the MIT license.