Abfragen mit Cypher

Zugriff auf den Knowledge Graphen per Cypher-API

Vorausgesetzt wird ein Grundverständnis der Abfragesprache Cypher und des Datenbankschemas.

Abfrage-Editor

viewof cypherEditor = {
  const mainDiv = html`<div><div>`
  const editorDiv = html`<div style="border: 1px solid rgb(0, 0, 0);"></div>`
  const runButton = html`<button>Query</button>`
  const errorStatus = html`<span style="color: red; margin-left: 1em;"></span>`

  mainDiv.append(editorDiv)
  mainDiv.append(runButton)
  mainDiv.append(errorStatus)

  mainDiv.value = undefined
  yield mainDiv

  let editor = CodeMirror(editorDiv, { mode: "application/x-cypher-query" })

  editor.setValue("MATCH (m:E16_Measurement) RETURN m LIMIT 10")
  editor.setSize(width-20, 200)

  runButton.onclick = async (e) => {
    errorStatus.textContent = ""
    mainDiv.value = 
    cypherQuery(editor.getValue())
      .then(value => mainDiv.value = value)
      .catch(e => { 
        errorStatus.textContent = e
        mainDiv.value = undefined
      })

    mainDiv.dispatchEvent(new CustomEvent("input"))
  }

  return mainDiv
}

cypherEditor

Anfrageformat

Der vorläufige API-Endpunkt ist https://graph.nfdi4objects.net/api/cypher. Die Cypher-Abfrage wird mit einer HTTP GET Anfrage im Query-Parameter query übergeben (siehe API-Dokumentation).

Rückgabeformat

Das Rückgabeformat ist ein JSON-Array von Objekten, deren Felder den Abfragefeldern entsprechen. Die Feldwerte werden folgendermaßen von Cypher nach JSON gemappt:

Cypher Datentyp	JSON Datentyp	Beispiel
NULL	null	null
BOOLEAN	boolean	true
INTEGER	number	123
FLOAT	number	3.14
STRING	string	"äbć"
ByteArray	string	"A2+/" (Base64)
LIST	array	[0,8,15]
MAP	string	{"x":"?","y":42}
Temporal (DATE, LOCAL TIME, DURATION…)	string (ISO-8601)	"2015-03-26" "12:50:35.556" "P14DT16H12M"
POINT	string (WKT)	"SRID=7203;POINT(1.2 3.4)"
NODE	object	{ "type": "node", "id": "4b55-98f8", "labels": ["E22"], "properties": { "P3_has_note": "?!" } }
RELATIONSHIP	object	{ "type": "edge", "id": "37a9-72df", "labels": ["P40"], "properties": {"x": 1}, "from": "98f8-6888", "to": "164b-c83a" }
PATH	array	Array aus NODE und RELATIONSHIP Objekten.

Die Kodierung von NODE und RELATIONSHIP Objekten entspricht der Kodierung von Knoten und Kanten im Format PG-JSONL mit dem Unterschied, dass Property-Werte nicht zwingend vom Type array sind, sondern auch null, boolean, number und string sein können. Die Kodierung von PATH Objekten entspricht der Kodierung von Graphen im Format PG-JSON mit der gleichen Erweiterung von Property-Werten.

Kurzeinführung in Cypher

Eine vollständige Einführung in die Abfragesprache Cypher liefert das englische Cypher Handbuch.

Die folgende Kurzeinführung bezieht sich noch nicht auf das Schema des Property Graphen sondern verwendet ein ausgedachtes Beispiel mit Personendaten.

Nodes

Knoten heißen Nodes und werden in runden Klammern definiert.

MATCH (n:Person {name:'Anna'})
RETURN n.geboren AS geburtsjahr

Person ist ein Label. Labels sind wie Tags und werden genutzt um die Datenbank zu befragen. Eine Node Kann mehrere Labels haben.
Name ist eine Property von Anna. Properties werden in geschweiften Klammern definiert and geben nähere Informationen. Nach Properties kann auch gefragt werden.
N ist eine Variabel. Auf Variabeln kann weiter verwiesen werden.

In diesem Beispiel findet MATCH alle Person Nodes in dem Graph wo die Property name Anna ist und setzt die Variabel n zu dem Ergebnis. n wird dann an RETURN weitergegeben, welche den Wert von einer anderen Property (geboren) dieser Nodes wiedergibt.

Relationships

Nodes können mit Relationships verbunden werden. Eine Relationship braucht eine Start Node, eine Ende Node und genau einen Typ. Relationships haben in Cypher einen Pfeil um die Richting zu zeigen. Die Informationen über eine Relationship sind in eckigen Klammern eingeschlossen.
Während Nodes mehrere Labels haben können, können Relationships nur einen Typ haben.

MATCH (:Person {name: 'Anna'})-[r:KENNT WHERE r.seit < 2020]->(freund:Person)
RETURN count(r) As zahlAnFreunden

In dieser Anfrage findet Match Relationships des Typs KENNT wo die Property seit kleiner als 2020 ist. Außerdem müssen Relationships von einer Person Node mit der Property Anna zu einer anderen Personen Node gehen (wir nennen diese freund). count() wird genutzt um zu zählen wie viele Relationships an die Variabel r in MATCH gebunden wurden somit erhalten wir mit RETURN eine Zahl.

Pfade

MATCH (n:Person {name: 'Anna'})-[:KENNT]-{1,5}(freund:Person WHERE n.geboren < freund.geboren)
RETURN DISTINCT freund.name AS ältereFreunde

Dieses Beispiel nutzt eine quantifizierte Relationship um alle Pfade, die bis zu 5 Schritte entfernt sind, zu finden. Dabei werden nur Relationships des Typs KENNT verwendet. Die Start Node ist Anna und Ende Node sind Personen älter als Anna. Durch DISTINCT wird das gleiche Ergebnis nur einmal ausgegeben.

MATCH p=shortestPath((:Person {name: 'Anna'})-[:KENNT*1..10]-(:Person {nationalität: 'Kanadier'}))
RETURN p

Auch Pfade können einer Variable zugewiesen werden. Hier wird der vollständige Pfad ausgegeben.

Beispielabfragen

Finde Wert, Einheit und Notiz aller Messungen.

MATCH (n:E16_Measurement)-[:P40_observed_dimension]->(m:E54_Dimension)-[:P2_has_type]->(:E55_Type)-[:P48_has_preferred_identifier]->(l)
MATCH (m)-[:P91_has_unit]->(:E58_Measurement_Unit)-[:P48_has_preferred_identifier]->(o)
RETURN m.P90_has_value AS value, o.P3_has_note AS unit, l.P3_has_note AS note

2.8,cm,Höhe (Scan)