# QLever
This repository provides a self-documenting and easy-to-use command-line tool
for QLever (pronounced "Clever"), a graph database implementing the
[RDF](https://www.w3.org/TR/rdf11-concepts/) and
[SPARQL](https://www.w3.org/TR/sparql11-overview/) standards.
For a detailed description of what QLever is and what it can do, see
[here](https://github.com/ad-freiburg/qlever).
# Installation
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`.
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 <command> --help` for help on a specific command, or just use the
autocompletion.
# Use on macOS and Windows
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.
For optimal performance, compile QLever from source on your machine. For Linux,
this 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).
# 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`.
# For developers
The (Python) code for the script is in the `*.py` files in `src/qlever`. The
preconfigured Qleverfiles are in `src/qlever/Qleverfiles`.
If you want to make changes to the script, or add new commands, do as follows:
```
git clone https://github.com/ad-freiburg/qlever-control
cd qlever-control
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
to the files in your working copy.
If you have bug fixes or new useful features or commands, please open a pull
request. If you have questions or suggestions, please open an issue.
Raw data
{
"_id": null,
"home_page": null,
"name": "qlever",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Graph database, Triplestore, Knowledge graphs, SPARQL, RDF",
"author": null,
"author_email": "Hannah Bast <bast@cs.uni-freiburg.de>",
"download_url": "https://files.pythonhosted.org/packages/8c/7c/18f6e4ee4feaa46776aad716207845f1e1b9583ef88d0f9d4214549ea94c/qlever-0.5.33.tar.gz",
"platform": null,
"description": "# QLever\n\nThis repository provides a self-documenting and easy-to-use command-line tool\nfor QLever (pronounced \"Clever\"), a graph database implementing the\n[RDF](https://www.w3.org/TR/rdf11-concepts/) and\n[SPARQL](https://www.w3.org/TR/sparql11-overview/) standards. \nFor a detailed description of what QLever is and what it can do, see \n[here](https://github.com/ad-freiburg/qlever).\n\n# Installation\n\nSimply do `pip install qlever` and make sure that the directory where `pip`\ninstalls the package is in your `PATH`. Typically, `pip` will warn you when\nthat is not the case and tell you what to do. If you encounter an \"Externally\nmanaged Environment\" error, try `pipx` instead of `pip`.\n\nType `qlever` without arguments to check that the installation worked. When\nusing it for the first time, you will see a warning at the top with\ninstructions on how to enable autocompletion. Do it, it makes using `qlever`\nso much easier (`pip` cannot do that for you automatically, sorry).\n\n# Usage\n\nCreate an empty directory, with a name corresponding to the dataset you want to\nwork with. For the following example, take `olympics`. Go to that directory\nand do the following.\n\n```\nqlever setup-config olympics # Get Qleverfile (config file) for this dataset\nqlever get-data # Download the dataset\nqlever index # Build index data structures for this dataset\nqlever start # Start a QLever server using that index\nqlever query # Launch an example query\nqlever ui # Launch the QLever UI\n```\n\nThis will create a SPARQL endpoint for the [120 Years of\nOlympics](https://github.com/wallscope/olympics-rdf) dataset. It is a great\ndataset for getting started because it is small, but not trivial (around 2\nmillion triples), and the downloading and indexing should only take a few\nseconds.\n\nEach command will also show you the command line it uses. That way you can\nlearn, on the side, how QLever works internally. If you just want to know the\ncommand line for a particular command, without executing it, you can append\n`--show` like this:\n\n```\nqlever index --show\n```\n\nThere are many more commands and options, see `qlever --help` for general help,\n`qlever <command> --help` for help on a specific command, or just use the\nautocompletion.\n\n# Use on macOS and Windows\n\nBy default, `qlever` uses [QLever's official Docker\nimage](https://hub.docker.com/r/adfreiburg/qlever). In principle, that image\nruns on Linux, macOS, and Windows. On Linux, Docker runs natively\nand incurs only a relatively small overhead regarding performance and RAM\nconsumption. On macOS and Windows, Docker runs in a virtual machine, which\nincurs a significant and sometimes unpredictable overhead. For example, `qlever\nindex` might abort prematurely (without a proper error message) because the\nvirtual machine runs out of RAM.\n\nFor optimal performance, compile QLever from source on your machine. For Linux,\nthis is relatively straightforward: just follow the `RUN` instructions in the\n[Dockerfile](https://github.com/ad-freiburg/qlever/blob/master/Dockerfile). For\nmacOS, this is more complicated, see [this\nworkflow](https://github.com/ad-freiburg/qlever/blob/master/.github/workflows/macos.yml).\n\n# Use with your own dataset\n\nTo use QLever with your own dataset, you need a `Qleverfile`, like in the\nexample above. The easiest way to write a `Qleverfile` is to get one of the\nexisting ones (using `qlever setup-config ...` as explained above) and then\nchange it according to your needs (the variable names should be\nself-explanatory). Pick one for a dataset that is similar to yours and when in\ndoubt, pick `olympics`.\n\n# For developers\n\nThe (Python) code for the script is in the `*.py` files in `src/qlever`. The\npreconfigured Qleverfiles are in `src/qlever/Qleverfiles`.\n\nIf you want to make changes to the script, or add new commands, do as follows:\n\n```\ngit clone https://github.com/ad-freiburg/qlever-control\ncd qlever-control\npip install -e .\n```\n\nThen you can use `qlever` just as if you had installed it via `pip install\nqlever`. Note that you don't have to rerun `pip install -e .` when you modify\nany of the `*.py` files and not even when you add new commands in\n`src/qlever/commands`. The exceutable created by `pip` simply links and refers\nto the files in your working copy.\n\nIf you have bug fixes or new useful features or commands, please open a pull\nrequest. If you have questions or suggestions, please open an issue.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Command-line tool for using the QLever graph database",
"version": "0.5.33",
"project_urls": {
"Github": "https://github.com/ad-freiburg/qlever"
},
"split_keywords": [
"graph database",
" triplestore",
" knowledge graphs",
" sparql",
" rdf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92a50ba14340e94e8556243c0ba4822e02970ba74abbfb3c7f638d3086273a42",
"md5": "a08906625a3ffacf165d6f209137795c",
"sha256": "86983b666270ca577f2bcbbff1c736e837b0cfec8bb97d9bf511918e904c7250"
},
"downloads": -1,
"filename": "qlever-0.5.33-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a08906625a3ffacf165d6f209137795c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 95235,
"upload_time": "2025-10-31T00:39:35",
"upload_time_iso_8601": "2025-10-31T00:39:35.361942Z",
"url": "https://files.pythonhosted.org/packages/92/a5/0ba14340e94e8556243c0ba4822e02970ba74abbfb3c7f638d3086273a42/qlever-0.5.33-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8c7c18f6e4ee4feaa46776aad716207845f1e1b9583ef88d0f9d4214549ea94c",
"md5": "42349051c706d1aee4a2da1fc9ceb418",
"sha256": "a6336c7177d6b025884035c7849f8a766208f4c7621d42f773fa4d4fe096b8ba"
},
"downloads": -1,
"filename": "qlever-0.5.33.tar.gz",
"has_sig": false,
"md5_digest": "42349051c706d1aee4a2da1fc9ceb418",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70504,
"upload_time": "2025-10-31T00:39:36",
"upload_time_iso_8601": "2025-10-31T00:39:36.845775Z",
"url": "https://files.pythonhosted.org/packages/8c/7c/18f6e4ee4feaa46776aad716207845f1e1b9583ef88d0f9d4214549ea94c/qlever-0.5.33.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-31 00:39:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ad-freiburg",
"github_project": "qlever",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "qlever"
}
JSON
