Skip to content

Commit e1f42c6

Browse files
nielsdejongnielsdejong
authored
Merge pull request #22 from neo4j-labs/feature/docs
Migrated & Improved documentation with examples, getting started guide, and contribution guidelines
2 parents dcc8c87 + cec2154 commit e1f42c6

9 files changed

+284
-39
lines changed

‎docs/getting_started.adoc

-3
This file was deleted.

‎docs/introduction.adoc

-16
This file was deleted.

‎docs/modules/ROOT/nav.adoc

+6-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1-
* xref:index.adoc[Introduction]
1+
* xref:index.adoc[Introduction]
2+
* xref:gettingstarted.adoc[Getting Started]
3+
* xref:neo4jstore.adoc[Neo4j Store]
4+
* xref:neo4jstoreconfig.adoc[Store Configuration]
5+
* xref:examples.adoc[Examples]
6+
* xref:contributing.adoc[Contributing]

‎docs/modules/ROOT/pages/contributing.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Contributing
2+
3+
Contributions to the project are highly welcomed.
4+
If you extend the library with custom functionality, consider creating a Pull Request on our GitHub repository.
5+
6+
7+
We highly recommend to familiarize yourself with the RDFLib core library. You can https://github.com/RDFLib/rdflib/#getting-started[learn more here].
8+
9+
10+
Contribution checklist:
11+
12+
- Find or create an https://github.com/neo4j-labs/rdflib-neo4j/issues[issue] on GitHub.
13+
- Fork the repository, create your own feature branch starting from the `develop` branch.
14+
- Document your code with docstrings or in the documentation (`docs` folder), if applicable.
15+
16+
## Feature Requests / Bugs
17+
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

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
= Examples
2+
3+
This page contains some code snippets with examples on using the library.
4+
5+
== Importing a TTL file
6+
This a basic example for importing a single TTL file.
7+
Insert your own database credentials for `AURA_DB_URI`, `AURA_DB_USERNAME`, `AURA_DB_PWD` to use this template.
8+
9+
[source,python]
10+
----
11+
from rdflib_neo4j import Neo4jStoreConfig
12+
from rdflib_neo4j import HANDLE_VOCAB_URI_STRATEGY
13+
14+
# Get your Aura Db free instance here: https://neo4j.com/cloud/aura-free/#test-drive-section
15+
AURA_DB_URI="your_db_uri"
16+
AURA_DB_USERNAME="neo4j"
17+
AURA_DB_PWD="your_db_pwd"
18+
19+
auth_data = {'uri': AURA_DB_URI,
20+
'database': "neo4j",
21+
'user': AURA_DB_USERNAME,
22+
'pwd': AURA_DB_PWD}
23+
from rdflib import Namespace
24+
25+
# Define your prefixes
26+
prefixes = {
27+
'neo4ind': Namespace('http://neo4j.org/ind#'),
28+
'neo4voc': Namespace('http://neo4j.org/vocab/sw#'),
29+
'nsmntx': Namespace('http://neo4j.org/vocab/NSMNTX#'),
30+
'apoc': Namespace('http://neo4j.org/vocab/APOC#'),
31+
'graphql': Namespace('http://neo4j.org/vocab/GraphQL#')
32+
}
33+
# Define your custom mappings
34+
config = Neo4jStoreConfig(auth_data=auth_data,
35+
custom_prefixes=prefixes,
36+
handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
37+
batching=True)
38+
from rdflib_neo4j import Neo4jStore
39+
from rdflib import Graph
40+
file_path = 'https://raw.githubusercontent.com/neo4j-labs/neosemantics/3.5/docs/rdf/nsmntx.ttl'
41+
42+
graph_store = Graph(store=Neo4jStore(config=config))
43+
graph_store.parse(file_path,format="ttl")
44+
graph_store.close(True)
45+
----
46+
47+
== Advanced Examples
48+
49+
=== Initialize Neo4jStore
50+
51+
[source,python]
52+
----
53+
from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
54+
from rdflib import Namespace, Graph, URIRef, RDF, SKOS, Literal
55+
56+
57+
# Define your custom prefixes
58+
prefixes = {
59+
'neo4ind': Namespace('http://neo4j.org/ind#'),
60+
'neo4voc': Namespace('http://neo4j.org/vocab/sw#'),
61+
}
62+
63+
# Neo4j connection credentials
64+
auth_data = {'uri': 'your_neo4j_uri',
65+
'database': 'neo4j',
66+
'user': "neo4j",
67+
'pwd': 'your_password'}
68+
69+
# Define your Neo4jStoreConfig
70+
config = Neo4jStoreConfig(auth_data=auth_data,
71+
custom_prefixes=prefixes,
72+
handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
73+
batching=False)
74+
75+
neo4j_store = Neo4jStore(config=config)
76+
graph_store = Graph(store=neo4j_store)
77+
78+
----
79+
80+
=== Import by Reference URL
81+
82+
[source,python]
83+
----
84+
file_path = 'https://raw.githubusercontent.com/neo4j-labs/neosemantics/3.5/docs/rdf/nsmntx.ttl'
85+
graph_store.parse(file_path,format="ttl")
86+
----
87+
88+
=== Write Individual Triples
89+
90+
[source,python]
91+
----
92+
aura = URIRef("http://neo4j.com/voc/tech#AuraDB")
93+
94+
graph_store.add((aura, RDF.type, SKOS.Concept))
95+
graph_store.add((aura, SKOS.prefLabel, Literal("AuraDB")))
96+
graph_store.add((aura, SKOS.broader, URIRef("http://neo4j.org/ind#neo4j355")))
97+
98+
----
99+
100+
=== SPARQL Query with Batching
101+
102+
[source,python]
103+
----
104+
import requests
105+
import urllib.parse
106+
107+
endpoint = "https://id.nlm.nih.gov/mesh/sparql"
108+
sparql = """
109+
PREFIX rdfs:
110+
PREFIX meshv:
111+
PREFIX mesh:
112+
PREFIX rdf:
113+
114+
CONSTRUCT { ?s ?p ?o }
115+
FROM
116+
WHERE {
117+
{
118+
?s ?p ?o
119+
filter(?s = mesh:D000086402 || ?o = mesh:D000086402)
120+
}
121+
union
122+
{
123+
mesh:D000086402 ?x ?s .
124+
?s ?p ?o .
125+
filter(?x != rdf:type && (isLiteral(?o) || ?p = rdf:type))
126+
}
127+
union
128+
{
129+
?s ?x mesh:D000086402 .
130+
?s ?p ?o .
131+
filter(isLiteral(?o|| ?p = rdf:type))
132+
}
133+
}
134+
"""
135+
136+
# Define your Neo4jStoreConfig
137+
config = Neo4jStoreConfig(auth_data=auth_data,
138+
custom_prefixes=prefixes,
139+
handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
140+
batching=True)
141+
142+
neo4j_store = Neo4jStore(config=config)
143+
graph_store = Graph(store=neo4j_store)
144+
145+
query_response = requests.get(endpoint, params = {"query": sparql , "format" : "TURTLE"})
146+
graph_store.parse(data=query_response.text,format='ttl')
147+
graph_store.close(commit_pending_transaction=True)
148+
149+
----

‎docs/modules/ROOT/pages/gettingstarted.adoc

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
= Getting Started
2+
3+
This page describes how to get started with this library, and set up your first RDF import.
4+
5+
== Set up Neo4j
6+
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:
7+
8+
[source,cypher]
9+
----
10+
CREATE CONSTRAINT n10s_unique_uri FOR (r:Resource) REQUIRE r.uri IS UNIQUE;
11+
----
12+
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.
13+
14+
== Set up Python environment
15+
`rdflib-neo4j` can be installed with Python's package management tool `pip`:
16+
17+
[source,shell]
18+
----
19+
$ pip install rdflib-neo4j
20+
----
21+
22+
== Loading data
23+
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:
24+
25+
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]):
26+
27+
[source,python]
28+
----
29+
from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
30+
from rdflib import Graph
31+
32+
# set the configuration to connect to your Aura DB
33+
AURA_DB_URI="your_db_uri"
34+
AURA_DB_USERNAME="neo4j"
35+
AURA_DB_PWD="your_db_pwd"
36+
37+
auth_data = {'uri': AURA_DB_URI,
38+
'database': "neo4j",
39+
'user': AURA_DB_USERNAME,
40+
'pwd': AURA_DB_PWD}
41+
42+
# Define your custom mappings & store config
43+
config = Neo4jStoreConfig(auth_data=auth_data,
44+
custom_prefixes=prefixes,
45+
handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
46+
batching=True)
47+
48+
file_path = 'https://github.com/jbarrasa/gc-2022/raw/main/search/onto/concept-scheme-skos.ttl'
49+
50+
# 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.)
51+
neo4j_aura = Graph(store=Neo4jStore(config=config))
52+
# Calling the parse method will implictly open the store
53+
neo4j_aura.parse(file_path, format="ttl")
54+
neo4j_aura.close(True)
55+
----
56+
57+
The imported file contains a taxonomy of technologies extracted from Wikidata and serialised using SKOS.
58+
After running the previous code fragment, your Aura DB/Neo4j DB should be populated with a graph like this one:
59+
60+
image::https://raw.githubusercontent.com/neo4j-labs/rdflib-neo4j/master/img/graph-view-aura.png[height="400"]
61+
62+
You can also write to the graph triple by triple like this:
63+
64+
[source,python]
65+
----
66+
import rdflib
67+
from rdflib_neo4j import Neo4jStoreConfig, Neo4jStore, HANDLE_VOCAB_URI_STRATEGY
68+
from rdflib import Graph, RDF, SKOS
69+
70+
# Set up your store config
71+
config = Neo4jStoreConfig(auth_data=auth_data,
72+
handle_vocab_uri_strategy=HANDLE_VOCAB_URI_STRATEGY.IGNORE,
73+
batching=False)
74+
75+
# Create the graph and open the store
76+
neo4j_aura = Graph(store=Neo4jStore(config=config))
77+
neo4j_aura.open(config)
78+
79+
aura = rdflib.URIRef("http://neo4j.com/voc/tech#AuraDB")
80+
81+
neo4j_aura.add((aura, RDF.type, SKOS.Concept))
82+
neo4j_aura.add((aura, SKOS.prefLabel, rdflib.Literal("AuraDB")))
83+
neo4j_aura.add((aura, SKOS.broader, rdflib.URIRef("http://www.wikidata.org/entity/Q1628290")))
84+
----
85+
86+
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:
87+
88+
image::https://raw.githubusercontent.com/neo4j-labs/rdflib-neo4j/master/img/graph-view-aura-detail.png[height="150"]

‎docs/modules/ROOT/pages/index.adoc

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

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
== Neo4j Store
1+
= Neo4j Store
22
[.procedures, opts=header]
33

44
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.
55

6-
=== Object Initialization
6+
== Constructor
77
|===
88
| Name | Type | Required | Default | Description
99
|config|Neo4jStoreConfig|True||Neo4jStoreConfig object that contains all the useful informations to initialize the store.

‎docs/documentation/Neo4jStoreConfig-0.1.adoc ‎docs/modules/ROOT/pages/neo4jstoreconfig.adoc

+9-16
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
== Neo4j Store Config
1+
= Neo4j Store Config
22
[.procedures, opts=header]
33

44
This object is used to configure the Neo4j Store to connect to your Neo4j Instance and to manage the parsing of a Triple Store.
55

6-
=== Object Initialization
6+
== Constructor
77
|===
88
| Name | Type | Required | Values(Default) | Description
99
| auth_data | Dictionary | True | ("uri", "database", "user", "pwd") | A dictionary containing authentication data. The required keys are: ["uri", "database", "user", "pwd"].
1010
| batching | Boolean | False | boolean (True) | A boolean indicating whether batching is enabled.
1111
| batch_size | Integer | False | (5000) | An integer representing the batch size (The batch size is intended as number of entities to store inside the database (nodes/relationships) and not triples.
1212
| custom_mappings | List[Tuple[Str,Str,Str]] | False | Empty list | A list of tuples containing custom mappings for prefixes in the form (prefix, object_to_replace, new_object).
13-
| custom_prefixes | Dictionary | True if handle_vocab_uri_strategy == HANDLE_VOCAB_URI_STRATEGY.SHORTEN | ({}) | A dictionary containing custom prefixes.
14-
| handle_vocab_uri_strategy | HANDLE_VOCAB_URI_STRATEGY | False |HANDLE_VOCAB_URI_STRATEGY.IGNORE, HANDLE_VOCAB_URI_STRATEGY.KEEP, HANDLE_VOCAB_URI_STRATEGY.MAP(HANDLE_VOCAB_URI_STRATEGY.SHORTEN) |
13+
| custom_prefixes | Dictionary | True ① | ({}) | A dictionary containing custom prefixes.
14+
| handle_vocab_uri_strategy | HANDLE_VOCAB_URI_STRATEGY | False |IGNORE, KEEP, MAP, (SHORTEN) |
1515

1616
* 'SHORTEN', full uris are shortened using prefixes for property names, relationship names and labels. Fails if a prefix is not predefined for a namespace in the imported RDF.
1717

@@ -21,13 +21,15 @@ This object is used to configure the Neo4j Store to connect to your Neo4j Instan
2121

2222
* 'KEEP' uris are kept unchanged
2323

24-
| handle_multival_strategy | HANDLE_MULTIVAL_STRATEGY | False | HANDLE_MULTIVAL_STRATEGY.ARRAY (HANDLE_MULTIVAL_STRATEGY.OVERWRITE)|
24+
| handle_multival_strategy | HANDLE_MULTIVAL_STRATEGY | False | ARRAY (OVERWRITE)|
2525
* 'OVERWRITE' property values are kept single valued. Multiple values in the imported RDF are overwriten (only the last one is kept)
2626

2727
* 'ARRAY' properties are stored in an array enabling storage of multiple values. All of them unless multivalPropList is set.
2828
| multival_props_names | List[Tuple[Str,Str]] | False | ([]) | A list of tuples containing the prefix and property names to be treated as multivalued in the form (prefix, property_name).
2929
|===
3030

31+
① if handle_vocab_uri_strategy == HANDLE_VOCAB_URI_STRATEGY.SHORTEN
32+
3133
== Functions
3234

3335
=== set_handle_vocab_uri_strategy
@@ -188,7 +190,7 @@ No arguments
188190
| Dictionary | A dictionary containing all prefixes.
189191
|===
190192

191-
== Enumerators
193+
== Enumerated Values
192194

193195
=== HANDLE_VOCAB_URI_STRATEGY
194196

@@ -204,12 +206,6 @@ Enum class defining different strategies for handling vocabulary URIs.
204206
| IGNORE | Strategy to ignore the Namespace and get only the local part
205207
|===
206208

207-
=== Examples
208-
209-
Here a series of examples of the application of a strategy on a certain triplet.
210-
211-
#TODO: Fill the examples#
212-
213209
=== Shorten
214210

215211
This strategy will shorten the URIs, replacing the prefix with its shorted version. If the Store find a prefix not defined inside its Neo4jStoreConfig object, the parsing will stop, raising a ShortenStrictException error.
@@ -229,7 +225,7 @@ This strategy will remove the entire prefix from the predicate.
229225

230226
Enum class defining different strategies for handling multiple values.
231227

232-
TO NOTICE: If the strategy is ARRAY and the Neo4jStoreConfig doesn't contain any predicate marked as multivalued, EVERY field will be treated as multivalued.
228+
> If the strategy is ARRAY and the Neo4jStoreConfig doesn't contain any predicate marked as multivalued, EVERY field will be treated as multivalued.
233229

234230
==== Possible Values
235231

@@ -239,9 +235,6 @@ TO NOTICE: If the strategy is ARRAY and the Neo4jStoreConfig doesn't contain any
239235
| ARRAY | Strategy to treat multiple values as an array
240236
|===
241237

242-
=== Examples
243-
244-
Here a series of examples of the application of a strategy on a certain triplet.
245238

246239
=== Overwrite
247240

0 commit comments

Comments
 (0)