@zazuko/cube-hierarchy-query !esm

Use it to work with hierarchies defined using the RDF Cube Schema

Usage

The examples below assume dataset is an RDF/JS graph of Swiss cantons:

``turtle
PREFIX schema:
PREFIX meta:
PREFIX sh:


a meta:Hierarchy ;
meta:hierarchyRoot ;
meta:nextInHierarchy .


schema:name "Canton" ;
sh:path schema:containsPlace ;
meta:nextInHierarchy .


schema:name "Districts" ;
sh:path [ sh:inversePath schema:containedInPlace ] ;
meta:nextInHierarchy .


schema:name "Municipalities" ;
sh:path [ sh:inversePath schema:containedInPlace ] .
`

$3

The simplest usage is to retrieve entire hierarchy. It generates a CONSTRUCT SPARQL query which will retrieve triples of the root resources and all resources on all hierarchy levels.

* sh:targetClass, if present is added as a restriction on each applicable level

`typescript
import { getHierarchy } from '@zazuko/cube-hierarchy-query'
import $rdf from '@zazuko/env'
import StreamClient from 'sparql-http-builder'

let dataset: DatasetCore
const client = new StreamClient()

const myHierarchy = clownface({ dataset }).namedNode('my-hierarchy')
const results = await getHierarchy(myHierarchy).execute(client, $rdf)

results.forEach(print(0))

function print(indent: number) {
return (hierarchyLevel: HierarchyNode) => {
const { value } = hierarchyLevel.resource
console.log(value.padStart(value.length + indent))
hierarchyLevel.nextInHierarchy.forEach(print(indent + 2))
}
}
`

By default, all properties of every hierarchy level are retrieved. That may prove very verbose and in such
cases, the caller can explicitly request specific properties to be returned by passing a second argument to
the getHierarchy function.

`ts
import rdf from '@zazuko/env'

getHierarchy(myHierarchy, {
properties: [
rdf.ns.schema.identifier,
[rdf.ns.schema.name, { language: 'de' }]
]
})
`

The above will fetch only schema:identifier and schema:name of all levels, additionally filtering
names only in German.

$3

Given a hierarchy level (GraphPointer) and the URI of a resource from that hierarchy,
finds children of that resource

`typescript
import { children } from '@zazuko/cube-hierarchy-query/resources'
import $rdf from '@zazuko/env'
import StreamClient from 'sparql-http-builder'
import { schema } from '@tpluscode/rdf-ns-builders'

let dataset: DatasetCore
let municipality: NamedNode

const districtLevel = clownface({ dataset }).namedNode('hierarchy/Switzerland/districts')
const client = new StreamClient()

const query = children(districtLevel, municipality, {
limit: 10, // optional (default 1)
offset: 10, // optional (default 0)
orderBy: schema.name, // optional (default undefined)
})

// will return array of graph pointers to children on the given municipality
const pointers: GraphPointer[] = await query.execute(client, $rdf)
`

$3

Given a hierarchy level (GraphPointer),
finds properties which connect resources from that level with the next.

Return a graph of ?property rdfs:label ?label quads of found properties

`typescript
import { properties } from '@zazuko/cube-hierarchy-query/introspect'
import StreamClient from 'sparql-http-builder'

const districtLevel = clownface({ dataset }).namedNode('hierarchy/Switzerland/cantons')
const client = new StreamClient()

const stream = await properties(cantonLevel).execute(client.query)
`

$3

Given a hierarchy level (GraphPointer),
finds types of resources at the given level

Return a graph of ?type rdfs:label ?label quads of found properties

`typescript
import { types } from '@zazuko/cube-hierarchy-query/introspect'
import StreamClient from 'sparql-http-builder'

const districtLevel = clownface({ dataset }).namedNode('hierarchy/Switzerland/cantons')
const client = new StreamClient()

const stream = await types(cantonLevel).execute(client.query)
`

Examples

The examples directory contains snippets showing the usage on real cubes & hierarchies.

To run call from example NPM script and pass the example file's path as argument. For example

`
yarn example ./examples/children.ts
`

To have the executed queries printed in the console, set a command flag:

`diff
yarn example ./examples/children.ts --print-query
``