Link Search Menu Expand Document
Start for Free

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
  1. Overview
  2. Configuring Query Management
  3. Listing Queries
  4. Terminating Queries
    1. Automatically Killing Queries
  5. Query Status
  6. Slow Query Logging
  7. Security and Query Management

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 uses cases the default configuration will be sufficient. But you may need to tweak the timeout parameter 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, which is inherited by all the databases in the server. You can customize the server-wide timeout value 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.

If individual queries need to set their own timeout, this can be done 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 set to true for the database (true is the default).

The value of query.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 value of query.timeout is five minutes.

Listing Queries

To see all running queries from the command line, use the query list command:

$ stardog-admin query list

The results are formatted tabularly:

+----+----------+-------+--------------+
| 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 (superuser’s 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, especially when a Stardog database is exposed to arbitrary query input, some of which may not execute in an acceptable time, the automatic query killing feature is useful. 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, the query will be killed automatically.

There may be some delay since Stardog only periodically checks the query.timeout value against internal query evaluation timers.

The client that submitted the query will receive an error message. The value of query.timeout may be overriden by setting a different value (smaller or longer) in database options. To disable, set to query.timeout to 0.

Query Status

To see more detail about query in-flight, 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 for what counts as a “slow query”, which is entirely 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 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 general 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.