From 787c96117dc8ff967e3b501416cead7fd2bd2234 Mon Sep 17 00:00:00 2001 From: qup42 Date: Sat, 24 Jan 2026 14:31:26 +0100 Subject: [PATCH 1/3] update README.md --- README.md | 63 ++++++++++++------------------------------------------- 1 file changed, 13 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 5df95454..d9d614c5 100644 --- a/README.md +++ b/README.md @@ -7,53 +7,16 @@ for QLever (pronounced "Clever"), a graph database implementing the For a detailed description of what QLever is and what it can do, see [here](https://github.com/ad-freiburg/qlever). -# Installation +# Installation and Usage -Simply do `pip install qlever` and make sure that the directory where `pip` -installs the package is in your `PATH`. Typically, `pip` will warn you when -that is not the case and tell you what to do. If you encounter an "Externally -managed Environment" error, try `pipx` instead of `pip`. +See the [official documentation](https://docs.qlever.dev/quickstart/) for +installation and usage instructions. There are native packages available for +[Debian and Ubuntu](https://docs.qlever.dev/quickstart/#debian-and-ubuntu) as +well as [macOS](https://docs.qlever.dev/quickstart/#macos-apple-silicon). On +other platforms QLever is only available via Docker and the `qlever` command-line +tool has to be [installed with `pipx`/`uv`](https://docs.qlever.dev/quickstart/#others). -Type `qlever` without arguments to check that the installation worked. When -using it for the first time, you will see a warning at the top with -instructions on how to enable autocompletion. Do it, it makes using `qlever` -so much easier (`pip` cannot do that for you automatically, sorry). - -# Usage - -Create an empty directory, with a name corresponding to the dataset you want to -work with. For the following example, take `olympics`. Go to that directory -and do the following. - -``` -qlever setup-config olympics # Get Qleverfile (config file) for this dataset -qlever get-data # Download the dataset -qlever index # Build index data structures for this dataset -qlever start # Start a QLever server using that index -qlever query # Launch an example query -qlever ui # Launch the QLever UI -``` - -This will create a SPARQL endpoint for the [120 Years of -Olympics](https://github.com/wallscope/olympics-rdf) dataset. It is a great -dataset for getting started because it is small, but not trivial (around 2 -million triples), and the downloading and indexing should only take a few -seconds. - -Each command will also show you the command line it uses. That way you can -learn, on the side, how QLever works internally. If you just want to know the -command line for a particular command, without executing it, you can append -`--show` like this: - -``` -qlever index --show -``` - -There are many more commands and options, see `qlever --help` for general help, -`qlever --help` for help on a specific command, or just use the -autocompletion. - -# Use on macOS and Windows +# Use on Windows By default, `qlever` uses [QLever's official Docker image](https://hub.docker.com/r/adfreiburg/qlever). In principle, that image @@ -64,11 +27,11 @@ incurs a significant and sometimes unpredictable overhead. For example, `qlever index` might abort prematurely (without a proper error message) because the virtual machine runs out of RAM. -For optimal performance, compile QLever from source on your machine. For Linux, -this is relatively straightforward: just follow the `RUN` instructions in the +For optimal performance, use the [native packages](https://docs.qlever.dev/quickstart/#installing-qlever) +or compile QLever from source on your machine. For Linux, compiling is relatively +straightforward: just follow the `RUN` instructions in the [Dockerfile](https://github.com/ad-freiburg/qlever/blob/master/Dockerfile). For -macOS, this is more complicated, see [this -workflow](https://github.com/ad-freiburg/qlever/blob/master/.github/workflows/macos.yml). +macOS, this is more complicated, see [this workflow](https://github.com/ad-freiburg/qlever/blob/master/.github/workflows/macos.yml). # Use with your own dataset @@ -95,7 +58,7 @@ pip install -e . Then you can use `qlever` just as if you had installed it via `pip install qlever`. Note that you don't have to rerun `pip install -e .` when you modify any of the `*.py` files and not even when you add new commands in -`src/qlever/commands`. The exceutable created by `pip` simply links and refers +`src/qlever/commands`. The executable created by `pip` simply links and refers to the files in your working copy. If you have bug fixes or new useful features or commands, please open a pull From 7a6c241b202677beb0eb7bd005e7ab41a030c6d3 Mon Sep 17 00:00:00 2001 From: qup42 Date: Sat, 24 Jan 2026 14:46:58 +0100 Subject: [PATCH 2/3] update README.md --- README.md | 38 +++++++++++++------------------------- 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index d9d614c5..38c1ae4e 100644 --- a/README.md +++ b/README.md @@ -7,40 +7,28 @@ for QLever (pronounced "Clever"), a graph database implementing the For a detailed description of what QLever is and what it can do, see [here](https://github.com/ad-freiburg/qlever). -# Installation and Usage +# Documentation -See the [official documentation](https://docs.qlever.dev/quickstart/) for -installation and usage instructions. There are native packages available for -[Debian and Ubuntu](https://docs.qlever.dev/quickstart/#debian-and-ubuntu) as -well as [macOS](https://docs.qlever.dev/quickstart/#macos-apple-silicon). On -other platforms QLever is only available via Docker and the `qlever` command-line -tool has to be [installed with `pipx`/`uv`](https://docs.qlever.dev/quickstart/#others). +View the latest documentation at . -# Use on Windows +# Installation -By default, `qlever` uses [QLever's official Docker -image](https://hub.docker.com/r/adfreiburg/qlever). In principle, that image -runs on Linux, macOS, and Windows. On Linux, Docker runs natively -and incurs only a relatively small overhead regarding performance and RAM -consumption. On macOS and Windows, Docker runs in a virtual machine, which -incurs a significant and sometimes unpredictable overhead. For example, `qlever -index` might abort prematurely (without a proper error message) because the -virtual machine runs out of RAM. +There are native packages available for +- [Debian and Ubuntu](https://docs.qlever.dev/quickstart/#debian-and-ubuntu) +- [macOS](https://docs.qlever.dev/quickstart/#macos-apple-silicon) -For optimal performance, use the [native packages](https://docs.qlever.dev/quickstart/#installing-qlever) -or compile QLever from source on your machine. For Linux, compiling is relatively -straightforward: just follow the `RUN` instructions in the -[Dockerfile](https://github.com/ad-freiburg/qlever/blob/master/Dockerfile). For -macOS, this is more complicated, see [this workflow](https://github.com/ad-freiburg/qlever/blob/master/.github/workflows/macos.yml). +On other platforms QLever can be run in Docker and the `qlever` command-line +tool can be [installed with `pipx`/`uv`](https://docs.qlever.dev/quickstart/#others). +Note: QLever will be executed in a container which will come with a performance penalty. # Use with your own dataset To use QLever with your own dataset, you need a `Qleverfile`, like in the example above. The easiest way to write a `Qleverfile` is to get one of the -existing ones (using `qlever setup-config ...` as explained above) and then -change it according to your needs (the variable names should be -self-explanatory). Pick one for a dataset that is similar to yours and when in -doubt, pick `olympics`. +existing ones (using `qlever setup-config ...`) and then +change it according to your needs. Pick one for a dataset that is similar to +yours and when in doubt, pick `olympics`. A +[reference of all options](https://docs.qlever.dev/qleverfile/) is available. # For developers From a134ca6c1e74c4aed9e68e5a3db5bf5528888c95 Mon Sep 17 00:00:00 2001 From: qup42 Date: Sat, 24 Jan 2026 14:48:40 +0100 Subject: [PATCH 3/3] update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 38c1ae4e..0ef5bac9 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,8 @@ There are native packages available for - [Debian and Ubuntu](https://docs.qlever.dev/quickstart/#debian-and-ubuntu) - [macOS](https://docs.qlever.dev/quickstart/#macos-apple-silicon) -On other platforms QLever can be run in Docker and the `qlever` command-line -tool can be [installed with `pipx`/`uv`](https://docs.qlever.dev/quickstart/#others). +On other platforms simply install the `qlever` command-line +[python package using `pipx`/`uv`](https://docs.qlever.dev/quickstart/#others). Note: QLever will be executed in a container which will come with a performance penalty. # Use with your own dataset