professionalwiki / sparql Goto Github PK

View Code? Open in Web Editor NEW

4.0 4.0 1.0 50 KB

MediaWiki extension to run SPARQL queries and template their results via Lua

License: GNU General Public License v2.0

Makefile 7.79% PHP 56.95% Lua 35.26%

mediawiki mediawiki-extension scribunto lua sparql sparql-query

sparql's Introduction

SPARQL

MediaWiki extension for executing SPARQL queries and templating their results via Lua.

Professional.Wiki created and maintains SPARQL. We provide Wikibase hosting, Wikibase development, MediaWiki development, and Wikibase consulting.

Table of Contents

Usage
Installation
PHP Configuration
Development
Release notes

Usage Documentation

Define a lua module that requires the SPARQL binding and uses its runQuery method.

Example: create page Module:MySPARQL:

local sparql = require('SPARQL') -- Load the SPARQL binding

local p = {}

function p.showFirstValue(frame)
  local sparqlQuery = frame.args[1]
  local queryResults = sparql.runQuery(sparqlQuery) -- Use the runQuery method

  local firstColName = queryResults['head']['vars'][0]
  return queryResults['results']['bindings'][0][firstColName]['value']

end

return p

Which can then be invoked via Scribunto's normal mechanisms from within wikitext. Example:

{{#invoke:MySPARQL|showFirstValue|your SPARQL query here}}

Lua module examples:

Installation

Platform requirements:

PHP 8.1 or later (tested up to 8.2)
MediaWiki 1.39 or later (tested up to 1.42-dev)
Scribunto and lua

We also recommend installing the CodeEditor extension for a better editing experience of Lua modules.

Installing The SPARQL Extension

The recommended way to install the SPARQL extension is using Composer with MediaWiki's built-in support for Composer.

On the commandline, go to your wikis root directory. Then run these two commands:

COMPOSER=composer.local.json composer require --no-update professional-wiki/sparql:~1.0

composer update professional-wiki/sparql --no-dev -o

Then enable the extension by adding the following to the bottom of your wikis LocalSettings.php file:

wfLoadExtension( 'SPARQL' );

You can verify the extension was enabled successfully by opening your wikis Special:Version page.

PHP Configuration

Configuration can be changed via LocalSettings.php.

SPARQL Endpoint URL

Variable: $wgSPARQLEndpoint

Required for the extension to function. You can enable the extension without setting this variable without breaking your wiki, but the extension will not work.

Example:

$wgSPARQLEndpoint = 'https://query.portal.mardi4nfdi.de/proxy/wdqs/bigdata/namespace/wdq/sparql';

Development

Run composer install in extensions/SPARQL/ to make the code quality tools available.

Running Tests and CI Checks

You can use the Makefile by running make commands in the SPARQL directory.

make ci: Run everything
make test: Run all tests
make phpunit --filter FooBar: run only PHPUnit tests with FooBar in their name
make phpcs: Run all style checks
make cs: Run all style checks and static analysis

Updating Baseline Files

Sometimes Psalm and PHPStan generate errors or warnings we do not wish to fix. These can be ignored by adding them to the respective baseline file. You can update these files with make stan-baseline and make psalm-baseline.

Release Notes

Version 1.0.0 - 2023-11-24

Lua binding SPARQL.runQuery to execute SPARQL queries and return the results as a Lua table
Compatibility with MediaWiki 1.39, 1.40 and 1.41
Compatibility with PHP 8.1 and 8.2

sparql's People

Contributors

Stargazers

Watchers

Forkers

physikerwelt

sparql's Issues

Set up SPARQL endpoint on GitHub Actions

AC:

Endpoint is available
Tests using the endpoint locally also use it on GH Actions

Follows up to

#4
and potentially to #5

Add parser tests

AC: we have a passing parser test that tests our lua integration

This parser test will need to create a Module:Whatever page in its setup and then invoke that lua module.

The test could use the real SPARQL endpoint, in which case it's fine if it only works locally, and is skipped on GitHub Actions. OR, the SPARQL request can be intercepted by a test double, since that part is already tested via #4. We do not have a good example of such mocking available and also ran into this challenge at ProfessionalWiki/ExternalContent#52. We'd need to override some MediaWiki services, presumably via the MediaWikiServices class, and only do so during tests. The ParserTestGlobals hook might be a good place to do so (see also https://github.com/ProfessionalWiki/ExternalContent/blob/master/src/EntryPoints/MediaWikiHooks.php#L54).

Create functioning lua module example

AC:

the README contains a functioning lua module
the module formats a specific SPARQL result into a sensible HTML table
at least one column combines two values. For instance a label and a URL being turned into a hyperlink

Ideally, we have the exact same lua in a/the parser test, to verify that is what in the README actually works. See #5

Something that executes a SPARQL query and returns the result (takes SPARQL string, returns ... associative array?)
- The location of the SPARQL endpoint should be configurable (via LocalSettings.php, so also needs an entry in extension.json)
- We need a service to make the HTTP request. MediaWiki has HttpRequestFactory. We could use my FileFetcher abstraction to get free test doubles and create a MediaWiki-specific implementation like done in MediaWikiFileFetcher from the External Content extension.
- Can we make a POST request to the SPARQL endpoint with the SPARQL as payload?? If not, we need something that turns the user-provided SPARQL and turns it into the request URL to the SPARQL endpoint

This should all be tested. We can create integration and unit tests already, even without having a development environment with SPARQL endpoint ready.

The SPARQL endpoint that is available will be equivalent to https://query.wikidata.org/#%23Cats%0ASELECT%20%3Fitem%20%3FitemLabel%20%0AWHERE%20%0A%7B%0A%20%20%3Fitem%20wdt%3AP31%20wd%3AQ146.%20%23%20Must%20be%20of%20a%20cat%0A%20%20SERVICE%20wikibase%3Alabel%20%7B%20bd%3AserviceParam%20wikibase%3Alanguage%20%22%5BAUTO_LANGUAGE%5D%2Cen%22.%20%7D%20%23%20Helps%20get%20the%20label%20in%20your%20language%2C%20if%20not%2C%20then%20en%20language%0A%7D, so you can run example queries there to get an idea of the result structure that you will dead with.

Some perhaps related and useful links: