Merge pull request #34 from neo4j-labs/develop

Release 1.1

docs/modules/ROOT/nav.adoc

@@ -1 +1,6 @@
-* xref:index.adoc[Introduction]
+* xref:index.adoc[Introduction]
+* xref:gettingstarted.adoc[Getting Started]
+* xref:neo4jstore.adoc[Neo4j Store]
+* xref:neo4jstoreconfig.adoc[Store Configuration]
+* xref:examples.adoc[Examples]
+* xref:contributing.adoc[Contributing]

docs/modules/ROOT/pages/contributing.adoc

@@ -0,0 +1,17 @@
+# Contributing
+
+Contributions to the project are highly welcomed.
+If you extend the library with custom functionality, consider creating a Pull Request on our GitHub repository.
+
+
+We highly recommend to familiarize yourself with the RDFLib core library. You can https://github.com/RDFLib/rdflib/#getting-started[learn more here].
+
+
+Contribution checklist:
+
+- Find or create an https://github.com/neo4j-labs/rdflib-neo4j/issues[issue] on GitHub.
+- Fork the repository, create your own feature branch starting from the `develop` branch.
+- Document your code with docstrings or in the documentation (`docs` folder), if applicable.
+
+## Feature Requests / Bugs
+If you have a request for a feature, or have found a bug, creating an https://github.com/neo4j-labs/rdflib-neo4j/issues[issue on GitHub] is the best way to reach out.

docs/modules/ROOT/pages/examples.adoc

@@ -0,0 +1,149 @@
+= Examples
+
+This page contains some code snippets with examples on using the library.
+
+== Importing a TTL file
+This a basic example for importing a single TTL file.
+Insert your own database credentials for `AURA_DB_URI`, `AURA_DB_USERNAME`, `AURA_DB_PWD` to use this template.
+
+[source,python]
+----
+from rdflib_neo4j import Neo4jStoreConfig
+from rdflib_neo4j import HANDLE_VOCAB_URI_STRATEGY
+
+# Get your Aura Db free instance here: https://neo4j.com/cloud/aura-free/#test-drive-section
+AURA_DB_URI="your_db_uri"
+AURA_DB_USERNAME="neo4j"
+AURA_DB_PWD="your_db_pwd"
+
+auth_data = {'uri': AURA_DB_URI,
+             'database': "neo4j",
+             'user': AURA_DB_USERNAME,
+             'pwd': AURA_DB_PWD}
+from rdflib import Namespace
+
+# Define your prefixes
+prefixes = {
+    'neo4ind': Namespace('http://neo4j.org/ind#'),
+    'neo4voc': Namespace('http://neo4j.org/vocab/sw#'),
+    'nsmntx': Namespace('http://neo4j.org/vocab/NSMNTX#'),
+    'apoc': Namespace('http://neo4j.org/vocab/APOC#'),
+    'graphql': Namespace('http://neo4j.org/vocab/GraphQL#')
+}
+# Define your custom mappings
+config = Neo4jStoreConfig(auth_data=auth_data,
+                          custom_prefixes=prefixes,
+                          handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+                          batching=True)
+from rdflib_neo4j import Neo4jStore
+from rdflib import Graph
+file_path = 'https://raw.githubusercontent.com/neo4j-labs/neosemantics/3.5/docs/rdf/nsmntx.ttl'
+
+graph_store = Graph(store=Neo4jStore(config=config))
+graph_store.parse(file_path,format="ttl")
+graph_store.close(True)
+----
+
+== Advanced Examples
+
+=== Initialize Neo4jStore
+
+[source,python]
+----
+from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
+from rdflib import Namespace, Graph, URIRef, RDF, SKOS, Literal
+     
+
+# Define your custom prefixes
+prefixes = {
+    'neo4ind': Namespace('http://neo4j.org/ind#'),
+    'neo4voc': Namespace('http://neo4j.org/vocab/sw#'),
+}
+
+# Neo4j connection credentials
+auth_data = {'uri': 'your_neo4j_uri',
+                     'database': 'neo4j',
+                     'user': "neo4j",
+                     'pwd': 'your_password'}
+
+# Define your Neo4jStoreConfig
+config = Neo4jStoreConfig(auth_data=auth_data,
+                          custom_prefixes=prefixes,
+                          handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+                          batching=False)
+
+neo4j_store = Neo4jStore(config=config)
+graph_store = Graph(store=neo4j_store)
+
+----
+
+=== Import by Reference URL
+
+[source,python]
+----
+file_path = 'https://raw.githubusercontent.com/neo4j-labs/neosemantics/3.5/docs/rdf/nsmntx.ttl'
+graph_store.parse(file_path,format="ttl")
+----
+
+=== Write Individual Triples
+
+[source,python]
+----
+aura = URIRef("http://neo4j.com/voc/tech#AuraDB")
+
+graph_store.add((aura, RDF.type, SKOS.Concept))
+graph_store.add((aura, SKOS.prefLabel, Literal("AuraDB")))
+graph_store.add((aura, SKOS.broader, URIRef("http://neo4j.org/ind#neo4j355")))
+     
+----
+
+=== SPARQL Query with Batching
+
+[source,python]
+----
+import requests
+import urllib.parse
+
+endpoint = "https://id.nlm.nih.gov/mesh/sparql"
+sparql = """
+PREFIX rdfs: 
+PREFIX meshv: 
+PREFIX mesh: 
+PREFIX rdf: 
+
+CONSTRUCT { ?s ?p ?o }
+FROM 
+WHERE {
+  {
+    ?s ?p ?o
+    filter(?s = mesh:D000086402 || ?o = mesh:D000086402)
+   }
+   union
+  {
+    mesh:D000086402 ?x ?s  .
+    ?s ?p ?o .
+    filter(?x != rdf:type && (isLiteral(?o) || ?p = rdf:type))
+  }
+   union
+  {
+    ?s ?x mesh:D000086402 .
+    ?s ?p ?o .
+    filter(isLiteral(?o|| ?p = rdf:type))
+  }
+}
+"""
+
+# Define your Neo4jStoreConfig
+config = Neo4jStoreConfig(auth_data=auth_data,
+                          custom_prefixes=prefixes,
+                          handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+                          batching=True)
+
+neo4j_store = Neo4jStore(config=config)
+graph_store = Graph(store=neo4j_store)
+
+query_response = requests.get(endpoint, params = {"query": sparql , "format" : "TURTLE"})
+graph_store.parse(data=query_response.text,format='ttl')
+graph_store.close(commit_pending_transaction=True)
+
+----

docs/modules/ROOT/pages/gettingstarted.adoc

@@ -0,0 +1,88 @@
+= Getting Started
+
+This page describes how to get started with this library, and set up your first RDF import.
+
+== Set up Neo4j
+To configure your Neo4j Graph DB, the process is simplified: initialize the database by establishing a uniqueness constraint on Resources' URIs. You can achieve this by executing the following Cypher fragment: 
+
+[source,cypher]
+----
+CREATE CONSTRAINT n10s_unique_uri FOR (r:Resource) REQUIRE r.uri IS UNIQUE;
+----
+This constraint ensures the uniqueness of URIs for Resource nodes, streamlining the integration process. Alternatively, you can simply set `create=True` when attempting to open the store in your Python code, and it will create the constraint for you.
+
+== Set up Python environment
+`rdflib-neo4j` can be installed with Python's package management tool `pip`:
+
+[source,shell]
+----
+$ pip install rdflib-neo4j
+----
+
+== Loading data
+Now, seamlessly import RDF data into your Neo4j On-premise or Aura instance by establishing an RDFLib graph and employing it to parse your RDF data. Each individual triple undergoes transparent persistence within your Neo4j database(whether it is on Aura or on-premise). Here's a step-by-step guide to achieve this integration:
+
+You can import the data from an RDF document (for example link:https://github.com/jbarrasa/datasets/blob/master/rdf/music.nt[this one serialised using N-Triples]):
+
+[source,python]
+----
+from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
+from rdflib import Graph
+
+# set the configuration to connect to your Aura DB
+AURA_DB_URI="your_db_uri"
+AURA_DB_USERNAME="neo4j"
+AURA_DB_PWD="your_db_pwd"
+
+auth_data = {'uri': AURA_DB_URI,
+             'database': "neo4j",
+             'user': AURA_DB_USERNAME,
+             'pwd': AURA_DB_PWD}
+
+# Define your custom mappings & store config
+config = Neo4jStoreConfig(auth_data=auth_data,
+                          custom_prefixes=prefixes,
+                          handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+                          batching=True)
+
+file_path = 'https://github.com/jbarrasa/gc-2022/raw/main/search/onto/concept-scheme-skos.ttl'
+
+# Create the RDF Graph, parse & ingest the data to Neo4j, and close the store(If the field batching is set to True in the Neo4jStoreConfig, remember to close the store to prevent the loss of any uncommitted records.)
+neo4j_aura = Graph(store=Neo4jStore(config=config))
+# Calling the parse method will implictly open the store
+neo4j_aura.parse(file_path, format="ttl")
+neo4j_aura.close(True)
+----
+
+The imported file contains a taxonomy of technologies extracted from Wikidata and serialised using SKOS.
+After running the previous code fragment, your Aura DB/Neo4j DB should be populated with a graph like this one:
+
+image::https://raw.githubusercontent.com/neo4j-labs/rdflib-neo4j/master/img/graph-view-aura.png[height="400"]
+
+You can also write to the graph triple by triple like this:
+
+[source,python]
+----
+import rdflib
+from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
+from rdflib import Graph, RDF, SKOS
+
+# Set up your store config
+config = Neo4jStoreConfig(auth_data=auth_data,
+                          handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
+                          batching=False)
+
+# Create the graph and open the store
+neo4j_aura = Graph(store=Neo4jStore(config=config))
+neo4j_aura.open(config)
+
+aura = rdflib.URIRef("http://neo4j.com/voc/tech#AuraDB")
+
+neo4j_aura.add((aura, RDF.type, SKOS.Concept))
+neo4j_aura.add((aura, SKOS.prefLabel, rdflib.Literal("AuraDB")))
+neo4j_aura.add((aura, SKOS.broader, rdflib.URIRef("http://www.wikidata.org/entity/Q1628290")))
+----
+
+The previous fragment would add another node to the graph representing AuraDB as a concept related to Neo4j via `skos:narrower`, which in your AuraDB graph would look as follows:
+
+image::https://raw.githubusercontent.com/neo4j-labs/rdflib-neo4j/master/img/graph-view-aura-detail.png[height="150"]

docs/modules/ROOT/pages/index.adoc

@@ -1 +1,13 @@
-jsdhdfvjfdvfv
+# RDFLib-Neo4j
+
+The **rdflib-neo4j** project is a Python-based https://rdflib.readthedocs.io/en/stable/[RDFLib Store] backed by Neo4j.
+You can use this library for high-performance RDF data ingestion into the Neo4j database.
+
+This library works with all types of Neo4j deployments, whether on-premise or cloud-hosted (Neo4j Aura).
+
+## Documentation
+
+- To get started, see the link:quickstart[Quickstart] page.
+- For details on the available Python classes, see the link:neo4jstore[Neo4j Store] page.
+- Example code fragments are available under link:examples[Examples].
+- If you want to contribute to this project, see link:contributing[Contributing].

docs/documentation/Neo4jStore-0.1.adoc → docs/modules/ROOT/pages/neo4jstore.adoc

@@ -1,12 +1,13 @@
-== Neo4j Store
+= Neo4j Store
 [.procedures, opts=header]
 
 This class is an implementation of the rdflib link:https://rdflib.readthedocs.io/en/stable/_modules/rdflib/store.html[Store class] that uses Neo4j as a backend. In this way it is possible to persist you RDF data directly in Neo4j, with the power of rdflib to process your data.
 
-=== Object Initialization
+== Constructor
 |===
 | Name | Type | Required | Default | Description
-|config|Neo4jStoreConfig|True||Neo4jStoreConfig object that contains all the useful informations to initialize the store.
+|config|Neo4jStoreConfig|True||Neo4jStoreConfig object that contains all the useful information to initialize the store.
+|driver|Neo4jStoreConfig|False|None|A pre-built Neo4j driver object to use to connect to the database. You cannot specify both a driver and credentials in the Neo4jStoreConfig.
 |===
 
 == Functions