Stored Queries
This page discusses managing stored queries in Stardog - the capability to name and store SPARQL queries for future evaluation.
Page Contents
Overview
Stardog 4.2 added the capability to name and store SPARQL queries for future evaluation by referring to the query’s name.
Queries of any type can be stored in Stardog and executed directly by using the name of the stored query. Stored queries can be shared with other users, which gives those users the ability to run those queries provided that they have appropriate permissions for a database.
Stored queries can be managed via CLI, Java API, and HTTP API.
Storing Queries
Queries can be stored using the stored add
Stardog admin command and specifying a unique name for the stored query:
$ stardog-admin stored add -n types "select distinct ?type {?s a ?type}"
If a file is used to specify the query string without an explicit -n/--name
option then the name of the query file is used for the stored query:
$ stardog-admin stored add listProperties.sparql
By default, stored queries can be executed over any database, however, they can be scoped by providing a specific database name with the -d/--database
option. Also, by default, only the user who stored the query can access that stored query. Using the --shared
flag will allow other users to execute the stored query.
EXAMPLE
The following example stores a shared query with a custom name that can be executed over only the database myDb
:
$ stardog-admin stored add --shared -d myDb -n listProperties "select distinct ?p {?s ?p ?o}"
Prior to Stardog 7.9, the WRITE
permission on database METADATA
was required to store queries for a specific database and superuser privileges are required to store queries for all databases. The ability to change database metadata would allow those users to potentially change arbitrary database configuration options. For this reason, this behavior has been changed in the Stardog 7.9 release that introduces stored query specific permissions. See the Security for Stored Queries section for additional details on what each permission setting does.
Stored query names must be unique for a Stardog instance. Existing stored queries can be replaced using the --overwrite
option in the command.
The attributes of stored queries are listed in the table below along with some mentioned previously:
Attribute | Description |
---|---|
Name | The name of the stored query. |
Query | The query string to store. |
Database | The name of the database for this query, * is a special value to run the query over any database. |
Creator | The name of the user who stored the query. |
Shared | Boolean attribute if this query is shared by all the users. |
Reasoning | Boolean attribute if this query is going to be executed with reasoning enabled. |
Schema | The reasoning schema that will be used by this query, if reasoning is in use. |
Annotations | The additional annotations associated with the stored query. |
Description | The description field of the stored query. |
These attributes could be leveraged with the options pointed in stored add
Stardog admin command, followed by the argument of the query to be stored.
Updating Stored Queries
Queries can be updated using the --overwrite
option on the stored add
admin command and specifying an existing name for a stored query:
$ stardog-admin stored add --overwrite -n types "select distinct ?p {?s ?p ?o}"
Queries can also be updated with stored set
Stardog admin command, too:
$ stardog-admin stored set types -q "select ?p {?s ?p ?o}" -a urn:typeGroups="types"^^<http://www.w3.org/2001/XMLSchema#string> --reasoning on -d typesDb --
To retrieve attributes of queries stored, use stored get
, optionally filtering annotations with the -a/--annotation
option:
$ stardog-admin stored get types -a urn:typeGroups
results as:
+------------------------+-------------------------------------------------------------+
| Stored Query Attribute | Value |
+------------------------+-------------------------------------------------------------+
| Description | a stored query for unit test |
| Query String | select ?p {?s ?p ?o} |
| Reasoning | true |
| Database | typesDb |
| Creator | user |
| Shared | false |
| Name | types |
| Annotation | urn:typeGroups="types" |
+------------------------+-------------------------------------------------------------+
Renaming Stored Queries
Stored queries can be renamed using the stored rename
command:
$ stardog-admin stored rename oldStoredQueryName newStoredQueryName
Attaching Arbitrary Properties to Stored Queries
Arbitrary RDF properties can be attached to stored queries in addition to the built-in properties from the system
database. These properties could be supplied via options during or after creation of the stored queries. They can be specifically retrieved from the stored queries also. The value of these additional annotation properties should be IRI
s or literal
s. Only the values directly linked to the stored query subject in the RDF document will be saved, and the triples with a non-stored query subject will be ignored.
During creation of a stored query, arbitrary properties are added via -a
or --annotation
option as a list of key-value (IRI-RDF Value) pairs:
$ stardog-admin stored add -a prefix:iri=prefix:value -n queryName "select * {?s ?p ?o} order by ?s ?p ?o"
If a stored query’s properties are needed to be set after its creation, stored set
admin command (with a comma delimiter if multiple pairs are supplied) is leveraged:
$ stardog-admin stored set queryName -a prefix:iri=prefix:value,prefix:another_iri=prefix:another_value --
Note that the usage above overrides the values, if keys are already present. However, if multiple values are needed per key, --append
option gives that flexibility:
$ stardog-admin stored set queryName -a prefix:iri=prefix:value --append --
Importing and Exporting Stored Queries
Stored queries are saved as RDF statements in the Stardog system database and it is possible to export the RDF representation of the queries:
Using the stored-export
command:
$ stardog-admin stored export
@prefix system: <http://system.stardog.com/> .
system:QueryExportAll a system:StoredQuery , system:SharedQuery ;
system:queryName "ExportAll" ;
system:queryString """construct where {?s ?p ?o}""" ;
system:queryCreator "admin" ;
system:queryDatabase "*" .
system:QuerylistDroids a system:StoredQuery , system:ReasoningQuery ;
system:queryName "listDroids" ;
system:queryString "select ?x { ?x a :Droid }" ;
system:queryCreator "luke" ;
system:queryDatabase "starwars" .
The same RDF representation can be used to import the stored queries as an alternative way of storing new queries or updating existing stored queries.
Using the stored-import
command:
$ stardog stored import queries.ttl
Running Stored Queries
Stored queries can be executed using the regular query execution CLI command by passing the name of the stored query:
$ stardog query execute myDb listProperties
Other commands like query explain
also accept stored query names. They can also be passed instead of query string into HTTP API calls.
Listing Stored Queries
To see all the stored queries, use the stored list
command:
$ stardog-admin stored list
The results are formatted tabular:
+--------+-----------------------------------------+
| Name | Query String |
+--------+-----------------------------------------+
| graphs | SELECT ?graph (count(*) as ?size) |
| | FROM NAMED stardog:context:all |
| | WHERE { GRAPH ?graph {?s ?p ?o}} |
| | GROUP BY ?graph |
| | ORDER BY desc(?size) |
| people | CONSTRUCT WHERE { |
| | ?person a foaf:Person ; |
| | ?p ?o |
| | } |
| types | SELECT DISTINCT ?type ?label |
| | WHERE { |
| | ?s a ?type . |
| | OPTIONAL { ?type rdfs:label ?label } |
| | } |
+--------+-----------------------------------------+
3 stored queries
Users can only see the queries they’ve stored and the queries stored by other users that have been --shared
. The --verbose
option will show more details about the stored queries.
Removing Stored Queries
Stored queries can be removed using the stored remove
command:
$ stardog-admin stored remove storedQueryName
If you would like to clear all the stored queries then use the -a/--all
option:
$ stardog-admin stored remove -a
Stardog supports a way to use stored queries as subqueries in larger SPARQL queries. For more details see the Stored Query Service section and the blog post of the same name.
Security for Stored Queries
Stored queries can be read by their creators or users with superuser privileges, unless they are shared. In addition, stored queries can be deleted by their creators or users with superuser privileges. Shared stored queries can be read by any user.
As of Stardog 7.9, a resource type is introduced for stored queries in order to determine which users can stored queries. Hence, the security aspect of stored queries became independent of database metadata. See Security Model for further details.