[Suggestion] Better Documentation and Examples

[faciolihenrique]

I've been trying to use this module, it's very great, but the code is missing some good examples on how to use and some 101 documentation for beginners. It would be nice to add it to rdflib documentation.

[mwatts15]

Hi, @faciolihenrique . Can you give some suggestions of examples you are looking for beyond what's in the README?

[faciolihenrique]

Sure! I would like a real example on how initialising a store using this library using one of the available options (sqlite/postgress etc) and showing a add operation over this graph and, after that, loading a graph stored on the database. I'm struggling on doing exactly that with sqlite.

The README has a basic example and the graph_case tests perform basic operations on the graph.

[faciolihenrique]

Using this documentation I've been trying to use it with SQLite in the follwing way:

SQLALCHEMY_PATH = "sqlite:///%(path)s/development.sqlite" % {"path": os.getcwd()}
store = plugin.get("SQLAlchemy", Store)()

graph = Graph(store)
graph.open(SQLALCHEMY_URL, create=True)

# (...) add some triples with graph.add(triple_or_quad)

graph.close()

With this, i'm able to add the triple and query the graph. The problem is that i'm not able to load it following the same code

[faciolihenrique]

I'll try follwing the example on the test. Thank you for your help!

Just for clarity ...

Just for clarity, create needs to be False when loading a populated graph:
graph.open(SQLALCHEMY_URL, create=False)

[rokroskar]

Looking at the above example (with a graph.commit() added before `graph.close()), it's also not clear to me how to load the triples. Should this work?

graph.open(SQLALCHEMY_URL, create=False)

graph.all_nodes() returns an empty set.

[faciolihenrique]

Well, I tried a lot of ways of doing it. You can check my college repo code where I used it if it is clearer: https://github.com/knowlattesgraph/knowlattes/blob/737eeba7bb639e457f9b6387f85b6fe918ade4b3/src/knowlattes/graph.py#L208

I'm not proud of this code but it works

[rokroskar]

Thanks @faciolihenrique I've finally got it working. I believe the problem was that the db seems to get written to only on the add() method call - I was merging two graphs together with

g = g + g1

and although g had the correct data, it was not getting written to the db.

[bollwyvl]

Semi-related to #99: it's possible to import and use rdflib-sqlalchemy with sqlite inside JupyterLite in the browser, powered by pyodide. This approach is already in use for numpy, pandas, sympy and a number of other packages, either with the full lab UI (multiple documents), the single-document retro UI or the minimal repl UI. Each UI offers rich output, completion and docstring viewing for classes and functions.

This can be easily deployed inside, for example, ReadTheDocs.

In-memory sqlite works great, but persistent databases need a little bit of care, due to some special filesystem work that needs to be done (e.g. sqlite:///../test.sqlite).

[dmoore247]

I came here (the documents) looking for the schema requirements and the theory.
I did find the table schemas in code tables.py

[richardscholtens]

@dmoore247
You can also try the example code and use this to create an SQLite database. Then you can export a database dump that will contain all SQL statements needed to create the tables necessary to read a database as a graph/triplestore. Doing so will also provide enough flexibility to add the needed tables to an existing (production) database. If you then map existing data within the other database tables to these rdflib-sqlalchemy tables one can also retrieve this information as a graph. Not sure if you can use database views for this, but as soon as I find out I'll let you know.