PersistentQueryStateLog

The Persistent Query Controller manages all Persistent Queries (PQs) in Deephaven, including starting, stopping, and monitoring the health of the PQs.

When a query worker is started or stopped, it goes through a series of state changes that represent the worker's status. Each state represents a specific condition, and every state change for every PQ is stored in the PersistentQueryStateLog. Current states are also visible in the status column in the Query Configuration Deephaven console panel.

The [Persistent Query Configuration Log] (./persistent-query-configuration-log. md) table stores PQ history (details about each PQ addition, modification, and deletion).

Columns

Column NameColumn TypeDescription
DateStringThe date the state change occurred. This is the partitioning column.
OwnerStringThe owner of the Persistent Query.
NameStringThe name of the Persistent Query.
TimestampDateTimeThe timestamp for the state change.
StatusStringThe new query state.
ControllerHostStringThe controller host that managed the query.
DispatcherHostStringThe host of the dispatcher that managed the worker.
ServerHostStringThe host on which the query ran.
WorkerNameStringThe worker's name.
ProcessInfoIdStringThe process info ID of the worker (a unique identifier for the process that can be used to cross-reference the worker with logs such as the query performance logs).
WorkerPortintThe worker's port for connections.
LastModifiedByAuthenticatedStringThe authenticated user who last started this query.
LastModifiedByEffectiveStringThe effective user who last started this query.
SerialNumberlongThe query's serial number (a system-generated identifier unique to each Persistent Query).
VersionNumberlongThe query's version number (a number that starts at 1 for each query and is incremented each time the query is updated).
TypeSpecificStateStringA type-specific state value; this will not apply to most queries.
ExceptionMessageStringIf applicable, the exception message for a failed query.
ExceptionStackTraceStringIf applicable, the full stack trace for a failed query.
EngineVersionStringFor Core+ workers, the version of the engine on which the worker ran, such as 0.39.0.
WorkerKindStringThe type of worker, either DeephavenEnterprise or DeephavenCommunity.
ScriptLoaderStateMapState of script loader infrastructure when logged. Currently, only "git" repository states are relevant, with the revision fingerprint of each, keyed by repo name, logged.
DispatcherPortintThe dispatcher port that managed the worker.
ReplicaSlotintThe replica slot of the worker.
StatusDetailsStringFurther details on the PQ state, such as the worker pod state in Kubernetes.

Query states

StateDescription
UninitializedThe query has no status as it has not been run.
ConnectingThe controller is connecting.
AuthenticatingThe query is authenticating with the authentication server.
AcquiringWorkerThe dispatcher is creating a worker process for the query.
InitializingThe worker process for the query is initializing.
RunningThe query worker is running (script query types only).
FailedThe query worker failed to start correctly; an exception should be visible.
ErrorThe query generated an error.
DisconnectedThe query worker disconnected unexpectedly. This may occur, for example, if the JVM experiences an OutOfMemoryError, a Hotspot error (possibly caused by a buggy native module), or if the garbage collector pauses the JVM for longer than the heartbeat interval between the worker and dispatcher.
StoppingThe query is shutting down.
StoppedThe query stopped normally (Live Query (Script) query types only).
CompletedThe query completed successfully (Batch Query (RunAndDone) and data-management (merge, import, and validation) query types only).
ExecutingThe query is executing (Batch Query (RunAndDone) and data-management (merge, import, and validation) query types only).

Example

To see the state changes of a specific Persistent Query (PQ), you can filter the PersistentQueryStateLog table by the query's name. The following example shows how to do this in both Core+ Python and Groovy, using today's data.

pqsl=db.liveTable("DbInternal", "PersistentQueryStateLog").where("Date=today()", "Name=`<PQ Name>`").sort("Timestamp")
pqsl = (
    db.live_table("DbInternal", "PersistentQueryStateLog")
    .where(["Date=today()", "Name=`<PQ Name>`"])
    .sort("Timestamp")
)

The following combines the PersistentQueryStateLog with the ProcessEventLog table to see the events for the most recent run of a PQ.

  • First, it queries the PersistentQueryStateLog to find the most recent entry for the specified PQ.
  • Then it queries the ProcessEventLog table for all events that match the ProcessInfoId of the most recent entry.
  • If you're using replicas or spares, you may want to restrict the PersistentQueryStateLog to a specific replica.
pqslLast=db.liveTable("DbInternal", "PersistentQueryStateLog").where("Date=today()", "Name=`<PQ Name>`")
        .sort("Timestamp")
        .tail(1)

pel=db.liveTable("DbInternal", "ProcessEventLog")
        .where("Date=today()")
        .whereIn(pqslLast, "ProcessInfoId")
        .sort("Timestamp")
pqslLast = (
    db.live_table("DbInternal", "PersistentQueryStateLog")
    .where(["Date=today()", "Name=`<PQ Name>`"])
    .sort("Timestamp")
    .tail(1)
)

pel = (
    db.live_table("DbInternal", "ProcessEventLog")
    .where("Date=today()")
    .where_in(pqslLast, "ProcessInfoId")
    .sort("Timestamp")
)