8.3.2. Procedures for query management

This section describes the procedures available for viewing and terminating currently-executing queries.

The features described in this section are available in Neo4j Enterprise Edition.

Unless stated otherwise, all arguments to the procedures described in this section must be supplied.

8.3.2.1. Terminology

administrator
This is a user who has been assigned the admin role. Refer to Section 7.1.4, “Native user and role management” for managing users and roles.
current user
This is the currently logged-in user invoking the commands described in this chapter.
user
  • A user is composed of a username and credentials, where the latter is a unit of information, such as a password, verifying the identity of a user.
  • A user may represent a human, an application etc.

8.3.2.2. List all running queries

An administrator is able to view all queries that are currently executing within the instance. Alternatively, the current user may view all of their own currently-executing queries.

Syntax:

CALL dbms.listQueries()

Returns:

Name Type Description

queryId

String

This is the ID of the query.

username

String

This is the username of the user who is executing the query.

metaData

Map

This is any metadata associated with the transaction.

query

String

This is the query itself.

parameters

Map

This is a map containing all the parameters used by the query.

planner

String

Planner used by the query

runtime

String

Runtime used by the query

indexes

List

Indexes used by the query

startTime

String

This is the time at which the query was started.

elapsedTime

String

Deprecated: Use elapsedTimeMillis instead. This is the time that has elapsed since the query was started.

connectionDetails

String

Deprecated: Use requestScheme, clientAddress,requestUri These are the connection details pertaining to the query.

protocol

String

The protocol used by connection issuing the query.

clientAddress

String

The client address of the connection issuing the query.

requestUri

String

The request URI used by the client connection issuing the query.

status

String

Status of the executing query.

resourceInformation

Map

Status of the executing query.

activeLockCount

Integer

Count of active locks held by transaction executing the query.

elapsedTimeMillis

Integer

This is the time in milliseconds that has elapsed since the query was started.

cpuTimeMillis

Integer

CPU time in milliseconds that has been actively spent executing the query.

waitTimeMillis

Integer

Wait time in milliseconds that has been spent waiting to acquire locks.

idleTimeMillis

Integer

Idle time in milliseconds.

allocatedBytes

Integer

Bytes allocated for the executing query

pageHits

Integer

Page hits occurred during the execution

pageFaults

Integer

Page faults occurred during the execution

Example 8.2. Viewing queries that are currently executing

The following example shows that the user 'alwood' is currently running dbms.listQueries() yielding specific variables, namely queryId, username, query, elapsedTimeMillis, requestUri, and status.

CALL dbms.listQueries() YIELD queryId, username, query, elapsedTimeMillis, requestUri, status
╒══════════╤═══════════╤══════════════════════════════╤════════════════════╤════════════════╤═══════════════════╕
│"queryId" │"username" │"query"                       │"elapsedTimeMillis" │"requestUri"    │"status"           │
╞══════════╪═══════════╪══════════════════════════════╪════════════════════╪════════════════╪═══════════════════╡
│"query-33"│"alwood"   │"CALL dbms.listQueries() YIELD│"1"                 │"127.0.0.1:7687"│{"state":"RUNNING"}│
│          │           │ queryId, username, query, ela│                    │                │                   │
│          │           │psedTime, requestUri, status" │                    │                │                   │
└──────────┴───────────┴──────────────────────────────┴────────────────────┴────────────────┴───────────────────┘
1 row

8.3.2.3. List all active locks for a query

An administrator is able to view all active locks held by the transaction executing the query with the queryId.

Syntax:

CALL dbms.listActiveLocks(queryId)

Returns:

Name Type Description

mode

String

Lock mode corresponding to the transaction.

resourceType

String

Resource type of the locked resource

resourceId

Integer

Resource id of the locked resource .

Example 8.3. Viewing active locks for a query

The following example shows the active locks held by transaction executing query with id query-614

CALL dbms.listActiveLocks( "query-614" )
╒════════╤══════════════╤════════════╕
│"mode"  │"resourceType"│"resourceId"│
╞════════╪══════════════╪════════════╡
│"SHARED"│"SCHEMA"      │"0"         │
└────────┴──────────────┴────────────┘
1 row

The following example shows the active locks for all currently executing queries by yielding the queryId from dbms.listQueries procedure

CALL dbms.listQueries() YIELD queryId, query
CALL dbms.listActiveLocks( queryId ) YIELD resourceType, resourceId, mode
RETURN queryId, query, resourceType, resourceId, mode
╒═══════════╤══════════════════════════════╤══════════════╤════════════╤════════╕
│"queryId"  │"query"                       │"resourceType"│"resourceId"│"mode"  │
╞═══════════╪══════════════════════════════╪══════════════╪════════════╪════════╡
│"query-614"│"match (n), (m), (o), (p), (q)│"SCHEMA"      │"0"         │"SHARED"│
│           │ return count(*)"             │              │            │        │
├───────────┼──────────────────────────────┼──────────────┼────────────┼────────┤
│"query-684"│"CALL dbms.listQueries() YIELD│"SCHEMA"      │"0"         │"SHARED"│
│           │ .."                          │              │            │        │
└───────────┴──────────────────────────────┴──────────────┴────────────┴────────┘
2 rows

8.3.2.4. Terminate multiple queries

An administrator is able to terminate within the instance all transactions executing a query with any of the given query IDs. Alternatively, the current user may terminate all of their own transactions executing a query with any of the given query IDs.

Syntax:

CALL dbms.killQueries(ids)

Arguments:

Name Type Description

ids

List<String>

This is a list of the IDs of all the queries to be terminated.

Returns:

Name Type Description

queryId

String

This is the ID of the terminated query.

username

String

This is the username of the user who was executing the (now terminated) query.

Example 8.4. Terminating multiple queries

The following example shows that the administrator has terminated the queries with IDs 'query-378' and 'query-765', started by the users 'joesmith' and 'annebrown', respectively.

CALL dbms.killQueries(['query-378','query-765'])
+---------------------------+
| queryId     | username    |
+---------------------------+
| "query-378" | "joesmith"  |
| "query-765" | "annebrown" |
+---------------------------+
2 rows

8.3.2.5. Terminate a single query

An administrator is able to terminate within the instance any transaction executing the query whose ID is provided. Alternatively, the current user may terminate their own transaction executing the query whose ID is provided.

Syntax:

CALL dbms.killQuery(id)

Arguments:

Name Type Description

id

String

This is the ID of the query to be terminated.

Returns:

Name Type Description

queryId

String

This is the ID of the terminated query.

username

String

This is the username of the user who was executing the (now terminated) query.

Example 8.5. Terminating a single query

The following example shows that the user 'joesmith' has terminated his query with the ID 'query-502'.

CALL dbms.killQuery('query-502')
+---------------------------+
| queryId     | username    |
+---------------------------+
| "query-502" | "joesmith"  |
+---------------------------+
1 row