Why did my query fail?

When a query fails, you can find details on its status in the Query Monitor. When errors or exceptions occur, the ExceptionDetails column provides relevant information (hover over the cell to display the full details, or right-click and select "Show Exception" to open the message in a dialog window).

Common causes of query failure

There are three primary causes of query failure:

  1. Initialization Failure: The query failed to initialize, most likely due to an error in the script. The ExceptionDetails column pinpoints the first problematic line (e.g., missing quotation marks, incorrect import paths, etc.). Another potential cause is exceeding the query server's maximum heap size when starting a new query. The DataRatio column estimates the heap size usage.
  2. Runtime Error: An error occurred after the query was initialized, such as an issue when processing incremental updates.
  3. Server Disconnection: The query failed because it disconnected from the server. See Query failure due to server connection for more details.

Analyzing Persistent Query failures

You can analyze Persistent Query (PQ) failures using the PersistentQueryStateLog in DbInternal. The following commands return details on queries that have failed today and have not been restarted:

lastPerReplica = db.liveTable("DbInternal", "PersistentQueryStateLog")
        .where("Date=today()")
        .sort("Timestamp")
        .lastBy("SerialNumber", "ReplicaSlot")

currentVersion = lastPerReplica.aggBy(AggMax("VersionNumber"), "SerialNumber")

currentStatus = lastPerReplica.naturalJoin(currentVersion, "SerialNumber", "CurrentVersion=VersionNumber")
        .where("VersionNumber=CurrentVersion")

from deephaven import agg

last_per_replica = (
    db.live_table("DbInternal", "PersistentQueryStateLog")
    .where("Date=today()")
    .sort("Timestamp")
    .last_by(["SerialNumber", "ReplicaSlot"])
)

current_version = last_per_replica.agg_by(agg.max_("VersionNumber"), "SerialNumber")

current_status = last_per_replica.natural_join(
    current_version, "SerialNumber", "CurrentVersion=VersionNumber"
).where("VersionNumber=CurrentVersion")

The ProcessInfoId column is a unique identifier for each worker. You can use it to find the appropriate logs and performance data for your query. To learn more about diagnosing query and troubleshooting solutions, see our Monitor query performance guide.