Query Management
This page discusses the ins and outs of query management in Stardog. Managing query performance is discussed in a separate section.
Page Contents
Overview
Stardog includes the capability to manage running queries according to configurable policies set at run-time; this capability includes support for:
- listing running queries;
- deleting running queries;
- reading the status of a running query;
- killing running queries that exceed a time threshold automatically;
- logging slow queries for analysis.
Stardog is pre-configured with sensible server-wide defaults for query management parameters; these defaults may be overridden or disabled per database, or even per query.
Configuring Query Management
For many use cases, the default configuration will be sufficient. However, you may need to tweak the timeout parameters to be longer or shorter, depending on the hardware, data load, queries, throughput, etc.
The default configuration has a server-wide query timeout value of query.timeout (or query.update.timeout for update queries), which is inherited by all the databases in the server. You can customize the server-wide timeout values and then set per-database custom values, too. Any database without a custom value inherits the server-wide value. To disable query timeout, set query.timeout to 0.
You can set the timeout for individual queries by passing a timeout parameter over HTTP or using the --timeout flag on the CLI in the stardog query execute command, but only if the query.timeout.override.enabled property is not set to false in stardog.properties (true is the default). However, if stardog.properties contains the entry query.timeout.override.enabled=false, then end users can use shorter timeouts for their queries but not longer timeouts. This is especially useful if Stardog’s SPARQL endpoint is accessible to the public and longer query timeouts could result in resource utilization issues.
The value of query.timeout or query.update.timeout is a positive integer concatenated with a letter, interpreted as a time duration: h (for hours), m (for minutes), s (for seconds), or ms (for milliseconds). For example, 1h for 1 hour, 5m for 5 minutes, 90s for 90 seconds, and 500ms for 500 milliseconds.
The default values of query.timeout and query.update.timeout are 5 minutes and 10 hours, respectively.
Listing Queries
To see all running queries from the command line, use the query list command:
$ stardog-admin query list
The results are returned in tabular format:
+----+----------+-------+--------------+
| ID | Database | User | Elapsed time |
+----+----------+-------+--------------+
| 2 | test | admin | 00:00:20.165 |
| 3 | test | admin | 00:00:16.223 |
| 4 | test | admin | 00:00:08.769 |
+----+----------+-------+--------------+
3 queries running
You can see which user owns the query (superusers can see all running queries), as well as the elapsed time and the database against which the query is running. The ID column is the key to deleting queries.
Terminating Queries
To terminate a running query, simply pass its ID to the query kill command:
$ stardog-admin query kill 3
The output confirms the query kill completing successfully:
Query 3 killed successfully
Automatically Killing Queries
For production use, the automatic query killing feature can be useful, especially when a Stardog database is exposed to arbitrary query input. It will protect a Stardog Server from queries that consume too many resources.
Once the execution time of a query exceeds the value of query.timeout (or query.update.timeout for an update query), the query will be killed automatically.
There may be some delay since Stardog only checks the timeout value against internal query evaluation timers periodically.
The client that submitted the query will receive an error message. The value of query.timeout or query.update.timeout may be overridden by setting a different value (smaller or longer) in database options. To disable, set to query.timeout or query.update.timeout to 0.
Query Status
To see more detail about a running query, use the query status command:
$ stardog-admin query status 1
The resulting output includes query metadata, including the query itself:
Username: admin
Database: test
Started : 2013-02-06 09:10:45 AM
Elapsed : 00:01:19.187
Query :
select ?x ?p ?o1 ?y ?o2
where {
?x ?p ?o1.
?y ?p ?o2.
filter (?o1 > ?o2).
}
order by ?o1
limit 5
Slow Query Logging
Stardog does not log slow queries in the default configuration because there isn’t a single value that determines what counts as a “slow query”. (The definition is relative to queries, access patterns, dataset sizes, etc.) While slow query logging has minimal overhead, what counts as a slow query in some context may not be acceptable in another.
A guide to enabling slow query logging is contained in the logging section.
Security and Query Management
The security model for query management is simple: any user can kill any running query submitted by that user, and a superuser can kill any running query. The same restriction is applied to query status; you cannot see status for a query that you do not own, and a superuser can see the status of every query.