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.
$ 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.
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
;
The number of versions available in a store can be read as follows:
console.log(store.maxVersion);
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();
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();
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();
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();
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();
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();
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.
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
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
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.