8.3.2. Procedures for query management

This section describes the procedures available for viewing running queries and transactions, and terminating queries in Neo4j.

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 section.
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. This number is cumulative over the duration of the query. For memory-intense or long-running queries the value may be larger than the current memory allocation.

pageHits

Integer

Page hits occurred during the execution.

pageFaults

Integer

Page faults occurred during the execution.

Example 8.5. 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.6. 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.7. 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.

message

String

A message stating whether the query was successfully found.

Example 8.8. 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    | message     |
+-----------------------------------------+
| "query-502" | "joesmith"  | Query found |
+-----------------------------------------+
1 row

The following example shows the output when trying to kill a query with an ID that does not exist.

CALL dbms.killQuery('query-502')
+---------------------------------------------------------+
| queryId     | username    | message                     |
+---------------------------------------------------------+
| "query-502" | "n/a"       | No Query found with this id |
+---------------------------------------------------------+
1 row

8.3.2.6. List all running transactions

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

Syntax:

CALL dbms.listTransactions()

Returns:

Name Type Description

transactionId

String

This is the ID of the transaction.

username

String

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

metaData

Map

This is any metadata associated with the transaction.

startTime

String

This is the time at which the transaction was started.

protocol

String

The protocol used by connection issuing the transaction.

clientAddress

String

The client address of the connection issuing the transaction.

requestUri

String

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

currentQueryId

String

This is the ID of the current query executed by transaction.

currentQuery

String

This is the current query executed by transaction.

activeLockCount

Integer

Count of active locks held by transaction.

status

String

Status of the executing transaction.

resourceInformation

Map

Information about what transaction is waiting for when it is blocked.

elapsedTimeMillis

Integer

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

cpuTimeMillis

Integer

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

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 transaction. This number is cumulative over the duration of the transaction. For memory-intense or long-running transactions the value may be larger than the current memory allocation.

allocatedDirectBytes

Integer

Direct bytes used by the executing transaction.

pageHits

Integer

Page hits occurred during the execution.

pageFaults

Integer

Page faults occurred during the execution.

Example 8.9. Viewing transactions that are currently executing

The following example shows that the user 'alwood' is currently running dbms.listTransactions(). The procedure call yields specific information about the running transaction, namely transactionId, username, currentQuery, elapsedTimeMillis, requestUri, and status.

CALL dbms.listTransactions() YIELD transactionId, username, currentQuery, elapsedTimeMillis, requestUri, status
╒════════════════╤═══════════╤══════════════════════════════════════╤════════════════════╤════════════════╤═══════════════════╕
│"transactionId" │"username" │"currentQuery"                        │"elapsedTimeMillis" │"requestUri"    │"status"           │
╞════════════════╪═══════════╪══════════════════════════════════════╪════════════════════╪════════════════╪═══════════════════╡
│"transaction-22"│"alwood"   │"CALL dbms.listTransactions() YIELD   │"1"                 │"127.0.0.1:7687"│"Running"          │
│                │           │ transactionId, username, currentQuery│                    │                │                   │
│                │           │elapsedTime, requestUri, status"      │                    │                │                   │
└────────────────┴───────────┴──────────────────────────────────────┴────────────────────┴────────────────┴───────────────────┘
1 row