diff --git a/manual/_quarto.yml b/manual/_quarto.yml index 314cc1a..9bd8bb1 100644 --- a/manual/_quarto.yml +++ b/manual/_quarto.yml @@ -2,7 +2,7 @@ project: type: book output-dir: ../docs pre-render: - - ../neo4j.sh status neo4j.json + # - ../neo4j.sh status neo4j.json - make images render: - "!*.md" @@ -10,8 +10,8 @@ project: filters: - include-code-files -metadata-files: - - neo4j.json +#metadata-files: +# - neo4j.json book: title: "NFDI4Objects Knowledge Graph (TA5)" @@ -29,10 +29,10 @@ book: - schema.qmd - vocabularies.qmd - usage.qmd - - cypher.qmd - sparql.qmd - architecture.qmd - mappings.qmd + - cypher.qmd - status.qmd page-footer: right: diff --git a/manual/basics.qmd b/manual/basics.qmd index 5013c08..1fd3adb 100644 --- a/manual/basics.qmd +++ b/manual/basics.qmd @@ -40,6 +40,10 @@ Einzelne "Datensätze" gibt es aufgrund der Graphstruktur nicht. ## Datenbankmodelle +### Triple Store + +Ein Triple Store ist eine [Graphendatenbank](https://de.wikipedia.org/wiki/Graphdatenbank) in der Daten dem [RDF-Modell](#rdf) nach in Form von so genannten Triplen gespeichert werden. Jedes **Tripel** entspricht in der Regel einer Kante im Graphen und besteht aus Subjekt, Prädikat und Objekt. Als Abfragesprache für RDF-Daten in Triple Stores dient [SPARQL](sparql.qmd). + ### Property Graph Property-Graphen dienen der Strukturierung, Speicherung und Auswertung @@ -55,10 +59,6 @@ versehen sein. Zur Abfrage von Property-Graphen dient die Sprache Beispiele von Property-Graphen werden in diesem Handbuch im [Property Graph Exchange Format (PG)](https://pg-format.github.io/) dargestellt. ::: -### Triple Store - -Ein Triple Store ist eine [Graphendatenbank](https://de.wikipedia.org/wiki/Graphdatenbank) in der Daten dem [RDF-Modell](#rdf) nach in Form von so genannten Triplen gespeichert werden. Jedes **Tripel** entspricht in der Regel einer Kante im Graphen und besteht aus Subjekt, Prädikat und Objekt. Als Abfragesprache für RDF-Daten in Triple Stores dient [SPARQL](sparql.qmd). - ## Datenbankinhalt ### Schema diff --git a/manual/cypher.qmd b/manual/cypher.qmd index 880201c..f17ab53 100644 --- a/manual/cypher.qmd +++ b/manual/cypher.qmd @@ -6,7 +6,12 @@ execute: echo: false --- -Vorausgesetzt wird ein Grundverständnis der [Abfragesprache Cypher](#cypher-grundlagen) und des [Datenbankschemas](schema.qmd). +::: {.callout-warning appearance="simple"} +Der Property Graph und die Cypher-API sind experimentell. +::: + + +Vorausgesetzt wird ein Grundverständnis der Abfragesprache Cypher und des [Datenbankschemas](schema.qmd). ### Abfrage-Editor @@ -120,82 +125,3 @@ auch `null`, `boolean`, `number` und `string` sein können. Die Kodierung von `P PG-JSON](https://pg-format.github.io/specification/#pg-jsonl) mit der gleichen Erweiterung von Property-Werten. [WKT]: http://giswiki.org/wiki/Well_Known_Text - - -## Kurzeinführung in Cypher {#cypher-grundlagen} - -Eine vollständige Einführung in die Abfragesprache Cypher liefert [das -englische Cypher Handbuch](https://neo4j.com/docs/cypher-manual/current/). - -::: {.callout-warning appearance="simple"} -Die folgende Kurzeinführung bezieht sich noch nicht auf das [Schema](schema.qmd) des Property Graphen sondern verwendet ein ausgedachtes Beispiel mit Personendaten. -::: - -### Nodes - -Knoten heißen Nodes und werden in runden Klammern definiert. -```cypher -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. - -```cypher -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 - -```cypher -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. - - -```cypher -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. - -```cypher -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 -``` - -```{python} -from neo4j import GraphDatabase -import json -with open('neo4j.json', 'r') as file: - neo4j_login = json.loads(file.read()) - uri = neo4j_login.get("uri") - user = neo4j_login.get("user") - password = neo4j_login.get("password") -cmd = "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;" -driver = GraphDatabase.driver(uri, auth=(user, password)) -with driver.session() as session: - for x in session.run(cmd): - print(','.join((str(x) for x in x.values()))) -``` - diff --git a/manual/index.qmd b/manual/index.qmd index bb556d2..c86c310 100644 --- a/manual/index.qmd +++ b/manual/index.qmd @@ -3,18 +3,13 @@ title: Einleitung lang: de --- -::: {.callout-tip appearance="simple"} -Eine erste Version der [Cypher-API des Property-Graphen](cypher.qmd) ist jetzt verfügbar! -::: - An dieser Stelle entsteht ein Handbuch für die Verwaltung und Nutzung des **Knowledge Graphen von NFDI4Objects** (TA5). Der Zugriff auf die Inhalte des Knowledge Graphen ist [Kapitel Benutzung](usage.qmd) beschrieben. Hintergründe und Details finden sich im [Grundlagen-Kapitel](basics.qmd) und in der Beschreibung der [Systemarchitektur](architecture.qmd). -Der Knowledge Graph besteht im Wesentlichen aus zwei Datenbanken, in denen Daten aus [verschiedenene Quellen](sources.qmd) zusammengeführt werden: - -- ein **[Property-Graph](#property-graph)** mit aufbereiteten Daten und Abfragemöglichkeit in [Cypher](cypher.qmd) - -- ein **[Triple-Store](#triple-store)** mit Rohdaten in RDF und Abfragemöglichkeit in [SPARQL](sparql.qmd) - -Darüber sind eine browserbasierte Oberfläche ("Rich Metadata Discovery") mit Möglichkeiten zur interaktiven Abfrage und Datenvisualisierung sowie die Integration in ein Learning Management System (LMS) geplant. Langfristig soll der Knowledge Graph außerdem mit anderen Knowledge Graphen im Rahmen der NFDI verknüpft werden. +Der Knowledge Graph besteht im Kern aus einem **[Triple-Store](#triple-store)**, +in denen Daten aus [verschiedenene Quellen](sources.qmd) zusammengeführt werden +und per [SPARQL](sparql.qmd)-Schnittstelle abgefragt werden können. Darüber hinaus +sind weitere Schnittstellen geplant, darunter ein Query-Builder und einen Graph-Browser. +Forschungsdaten-Anwendungen können auf den Knowledge Graphen zugreifen und zusätzliche +Recherche- und Analysemöglichkeiten bieten. -Der aktuelle Stand des Property Graphen ist [über ein Dashboard](status.qmd) einsehbar. + diff --git a/manual/status.qmd b/manual/status.qmd index 152bad0..04c977e 100644 --- a/manual/status.qmd +++ b/manual/status.qmd @@ -4,6 +4,10 @@ subtitle: Dashboard zum Stand der Property Graphen format: dashboard --- +## Triple Store + +- Anzahl von Tripel: `{ojs} sparqlTriplesCount[0]?.count?.toLocaleString()` + ## Property Graph Folgende Übersicht wird live per [Cypher API](cypher.qmd) erstellt. @@ -18,9 +22,6 @@ cypherEdgesCount = await cypherQuery("MATCH ()-[]->() RETURN count(*) as count") sparqlTripleCount = await sparqlQuery("SELECT (COUNT(*) as ?count) { GRAPH ?graph { ?s ?p ?o } }") ``` -## Triple Store - -- Anzahl von Tripel: `{ojs} sparqlTriplesCount[0]?.count?.toLocaleString()` ## Datenquellen diff --git a/manual/usage.qmd b/manual/usage.qmd index 6ac6499..d58b88e 100644 --- a/manual/usage.qmd +++ b/manual/usage.qmd @@ -6,10 +6,6 @@ lang: de Der Zugriff auf den Knowledge Graphen ist bislang nur über technische Schnittstellen (APIs) möglich. Darüber hinaus sind eine browserbasierte Suchoberfläche, Datenbankdumps und die Integration in andere Anwendungen geplant. -## Cypher-API - -Eine öffentliche Entwicklungsversion des Property Graphen kann mit der Abfragesprache Cypher über die API-URL abgefragt werden (siehe [API-Dokumentation](https://github.com/nfdi4objects/n4o-graph-apis?tab=readme-ov-file#property-graph-api)). Unter gibt es eine einfache Weboberfläche zur Formulierung von Abfragen. Eine weitere Einführung mit Beispielen gibt es im Kapitel [Cypher-Abfragen](cypher.qmd). - ## SPARQL-API Eine öffentliche Entwicklungsversion des Triple-Store kann mit der Abfragesprache SPARQL über die API-URL abgefragt werden (siehe [API-Dokumentation](https://github.com/nfdi4objects/n4o-graph-apis?tab=readme-ov-file#sparql-api)). Unter gibt es eine einfache Weboberfläche zur Formulierung von Abfragen. Eine weitere Einführung mit Beispielen gibt es im Kapitel [SPARQL-Abfragen](sparql.qmd). @@ -25,3 +21,8 @@ Die Bereitstellung von Datenbankdumps zur lokalen Nutzung von Teilen des Knowled ::: {.callout-warning appearance="simple"} Eine browserbasierte Suchoberfläche (“Rich Metadata Discovery”) mit Möglichkeiten zur interaktiven Abfrage und Datenvisualisierung ist noch nicht umgesetzt. ::: + +## Cypher-API + +Neben dem Triple-Store experimentieren wir mir einer Abbildung der Forschungsdaten in einem Property Graphen. Dieser Graph kann mit der Abfragesprache Cypher über die API-URL abgefragt werden. Unter gibt es eine einfache Weboberfläche zur Formulierung von Abfragen. Die Datenbankinhalte entsprechen allerdings nicht dem Triple-Store! +