Qonsole - a simple console for running SPARQL queries

Warning: While this project has not yet been replaced and should continue to receive required bug fixes and any minor feature requests, future development of qonsole will be done as part of the qonsole-sfc project. (2022-07-04)

Concept

Suppose you have a linked-data dataset that you've published on the web, and that you'd like to provide your users with the means to run SPARQL queries to explore your data. Most SPARQL end-points allow you to use HTTP get and post commands to send a query and get back results, so it's easy enough to put up an HTML form for your users to type in a query and get back some results. But that's not necessarily that helpful for your users, because:

• in some browsers, hitting the 'back' button after posting a query means that the text input control is emptied. So your users will lose the query that they have typed, which makes iterative development of the query hard.
• you can provide at most one sample query to get your users started with suggestions and ideas.
• you don't have any to manage prefixes, which can make a huge difference to the readability of a query (compare <http://www.w3.org/2000/01/rdf-schema#comment> to rdfs:comment, for example).
• the returned values from a SPARQL form are generally represented as a text format, or using a MIME type (e.g. text/csv that makes your user's computer open the returning file in another program (e.g. a spreadsheet). Plain text can be hard to explore, while opening a different application takes your user's focus away from the task of editing the query and exploring your data.

See a demo of qonsole, using the UK bathing water quality dataset.

Qonsole provides the following features:

• An edit control with SPARQL syntax highlighting, undo, and other familiar code editing features (courtesy of CodeMirror).
• Display of the query and the return result on one page
• A configurable set of example queries your users can select with one click
• A configurable set of pre-declared prefixes, and the ability to add new prefixes dynamically, including looking a well-know prefix up on prefix.cc. Users can add or remove prefix declarations from the edit window with one click.
  • A choice of return formats, including XML, JSON and plain text. XML and JSON results display in a structured editor window for easier browsing. By default, results are returned in a table control, with sortable columns, paging and search.

Qonsole is free open-source software under an Apache license, and was developed by
Epimorphics Ltd.

Adding qonsole to your page

Clone the git repository (epimorphics/qonsole), or download the files individually from GitHub. The demo- pages show a few variants on laying out the elements of the page body that Qonsole needs, and the JavaScript and CSS files you'll need to include.

Qonsole is configured by passing a JSON data structure to the qonsole.init() call. Currently, this config object allows you to specify:

elements – available SPARQL end-points

The value of this config element is a JSON object, whose keys are short references to available endpoints and whose values are URLs. One default end-point should always be provided. The goal here is to allow different example queries potentially to be run against different specific SPARQL endpoints. Example:

    endpoints: {
      "default":  "http://environment.data.gov.uk/sparql/bwq/query",
    }

prefixes – shared list of pre-defined prefixes

The prefixes listed in this element will be added to each query, and may be selected on or off by a single click. The value is a JSON object, whose keys are the prefix short-name, and whose values are URIs. Example:

    prefixes: {
      "bw":       "http://environment.data.gov.uk/def/bathing-water/",
      "bwq":      "http://environment.data.gov.uk/def/bathing-water-quality/",
      "ef-sp":    "http://location.data.gov.uk/def/ef/SamplingPoint/",
      "interval": "http://reference.data.gov.uk/def/intervals/",
      "stats":    "http://statistics.data.gov.uk/def/administrative-geography/",
      "sr":       "http://data.ordnancesurvey.co.uk/ontology/spatialrelations/",
      "rdf":      "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
      "rdfs":     "http://www.w3.org/2000/01/rdf-schema#",
      "owl":      "http://www.w3.org/2002/07/owl#",
      "xsd":      "http://www.w3.org/2001/XMLSchema#"
    },

queries – pre-defined example queries

This element defines the example queries that users can select run, or to base their own queries on. The value is a JSON array, each element of which is one example query. Note that prefixes do not need to be declared in the example queries. The query text can be declared in the config structure itself, with the query key, or accessed remotely from a different URL using the queryURL key:

    queries: [
      { "name": "Properties of a named bathing water",
        "query": "select ?predicate ?object\nwhere {\n" +
                 "  ?bw rdfs:label \"Spittal\"@en ;\n" +
                 "      ?predicate ?object\n}"
      },
      { "name": "all OWL classes",
        "query": "select ?class ?label ?description\nwhere {\n" +
                 "  ?class a owl:Class.\n" +
                 "  optional { ?class rdfs:label ?label}\n" +
                 "  optional { ?class rdfs:comment ?description}\n}"
      },
      { "name": "Properties of a named bathing water",
        "queryURL": "list-properties.rq"
      }
    ]

By default, each query gets all of the shared prefixes declared in the configuration object (see above). However this isn't always necessary. Simpler example queries may be easier to read if the prefixes shown are only those actually in use. There are two mechanisms you can use to control the prefixes used when displaying a query. Firstly, if the query itself includes prefix declarations, then only those prefixes will be shown. Alternatively, you can list the prefix keys that should be used with the query with a prefixes key in the configuration object:

  queries: [
    { "name": "Properties of a named bathing water",
      "query": "select ?predicate ?object\nwhere {\n" +
               "  ?bw rdfs:label \"Spittal\"@en ;\n" +
               "      ?predicate ?object\n}",
      "prefixes": [rdfs", "bw"]
    }]