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. Query IDs
5. Terminating Queries
   1. Automatically Killing Queries
6. Query Status
7. Slow Query Logging
8. 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 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, the elapsed time, and the database against which the query is running. Which queries are listed depends on permissions: your own by default, every query on a database or on the server with the grants described below, and all of them for a superuser. The ID column is the key to deleting queries.

Query IDs

Stardog assigns each query an ID and returns it in the SD-Query-Id response header. To track or kill a query without looking it up in the list first, a client can choose the ID itself: pass the id parameter to /{db}/query or /{db}/update, or send the SD-Process-Id header. If both are given, the id parameter is used. With the Java API, set the ID with Query.id(...).

A query ID can be any string, but it must be URL-encoded when used in GET or DELETE /admin/queries/{id}; the CLI and Java client do this for you. Using UUIDs is recommended. See Process IDs for the rules that apply to the SD-Process-Id header.

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

Any user can always see and kill the queries they ran themselves, and a superuser can see and kill every query. In between, these permissions widen what a user reaches:

Killing another user’s query takes both actions: EXECUTE on its own is not enough, since a query you are not allowed to see is not one you may kill.

---