@zazuko/cube-hierarchy-query

@zazuko/cube-hierarchy-query

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:

PREFIX schema: <http://schema.org/>
PREFIX meta: <https://cube.link/meta/>
PREFIX sh: <http://www.w3.org/ns/shacl#>

<hierarchy/Switzerland>
  a meta:Hierarchy ;
  meta:hierarchyRoot <country/CHE> ;
  meta:nextInHierarchy <hierarchy/Switzerland/cantons> .
  
<hierarchy/Switzerland/cantons>
  schema:name "Canton" ;
  sh:path schema:containsPlace ;
  meta:nextInHierarchy <hierarchy/Switzerland/municipalities> .
  
<hierarchy/Switzerland/municipalities>
  schema:name "Municipalities" ;
  sh:path [ sh:inversePath schema:containedInPlace ] ;
  meta:nextInHierarchy <hierarchy/Switzerland/districts> .
    
<hierarchy/Switzerland/districts>
  schema:name "Districts" ;
  sh:path [ sh:inversePath schema:containedInPlace ] .

Get entire hierarchy

The simplest usage is to retrieve entire hierarchy. It generates a DESCRIBE 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

import { getHierarchy } from '@zazuko/cube-hierarchy-query'
import $rdf from 'rdf-ext'
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))
  }
}

Find resources

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

import { children } from '@zazuko/cube-hierarchy-query/resources'
import $rdf from 'rdf-ext'
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)

Introspect properties

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

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)

Introspect types

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

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 DEBUG environment variable:

-yarn example ./examples/children.ts
+DEBUG=SPARQL yarn example ./examples/children.ts

Changelog

1.0.0

Major Changes

• 29db201: The children() method result now returns the children (still as an array of GraphPointer) and the parent (as a GraphPointer).

  - const childrenResult = await children(...)
  + const { children: childrenResult } = await children(...)
  

• 1d4ac7e: First version

Minor Changes

• f946c50: Getting entire hierarchy. See example in examples/hierarchy.ts. Run it like

  yarn run example examples/hierarchy.ts \
    --cube https://environment.ld.admin.ch/foen/fab_Offentliche_Ausgaben_test3/7
  

Patch Changes

• 6340c7f: Add @zazuko/vocabulary-extras as dependency
• 6340c7f: Update @tpluscode/rdf-ns-builders to v2
• ac1db59: Missing type declarations in package
• b180146: Improve the query for example resources. Paging is now done in a SELECT subquery
• b180146: Update dependencies on @rdfjs/* and rdf-ext packages to use the ESM versions