--- title: PersistentQueryStateLog --- The [Persistent Query Controller](../../sys-admin/pq-controller/pq-controller.md) manages all [Persistent Queries](../../query-management/pq-overview.md) (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](#query-states) 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 Name | Column Type | Description | | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Date` | String | The date the state change occurred. This is the partitioning column. | | `Owner` | String | The owner of the Persistent Query. | | `Name` | String | The name of the Persistent Query. | | `Timestamp` | DateTime | The timestamp for the state change. | | `Status` | String | The new query [state](#query-states). | | `ControllerHost` | String | The controller host that managed the query. | | `DispatcherHost` | String | The host of the dispatcher that managed the worker. | | `ServerHost` | String | The host on which the query ran. | | `WorkerName` | String | The worker's name. | | `ProcessInfoId` | String | The 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). | | `WorkerPort` | int | The worker's port for connections. | | `LastModifiedByAuthenticated` | String | The authenticated user (e.g., the user who logged in via password, SAML, etc.) who last started this query. | | `LastModifiedByEffective` | String | The effective user (e.g., the "operate as" user if the authenticated user is using the "operate as" option) who last started this query. | | `SerialNumber` | long | The query's serial number (a system-generated identifier unique to each Persistent Query). | | `VersionNumber` | long | The query's version number (a number that starts at 1 for each query and is incremented each time the query is updated). | | `TypeSpecificState` | String | A type-specific state value; this will not apply to most queries. | | `ExceptionMessage` | String | If applicable, the exception message for a failed query. | | `ExceptionStackTrace` | String | If applicable, the full stack trace for a failed query. | | `EngineVersion` | String | For Core+ workers, the version of the engine on which the worker ran, such as `0.39.0`. | | `WorkerKind` | String | The type of worker, either `DeephavenEnterprise` or `DeephavenCommunity`. | | `ScriptLoaderState` | Map | State of script loader infrastructure when logged. Currently, only "git" repository states are relevant, with the revision fingerprint of each, keyed by repo name, logged. | | `DispatcherPort` | int | The dispatcher port that managed the worker. | | `ReplicaSlot` | int | The [replica slot](../../query-management/ui-queries.md#load-balancing) of the worker. | | `StatusDetails` | String | Further details on the PQ state, such as the worker pod state in Kubernetes. | ## Query states | State | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Uninitialized` | The query has no status as it has not been run. | | `Connecting` | The controller is connecting. | | `Authenticating` | The query is authenticating with the authentication server. | | `AcquiringWorker` | The dispatcher is creating a worker process for the query. | | `Initializing` | The worker process for the query is initializing. | | `Running` | The query worker is running (script query types only). | | `Failed` | The query worker failed to start correctly; an exception should be visible. | | `Error` | The query generated an error. | | `Disconnected` | The 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. | | `Stopping` | The query is shutting down. | | `Stopped` | The query stopped normally (Live Query (Script) query types only). | | `Completed` | The query completed successfully (Batch Query (RunAndDone) and data-management (merge, import, and validation) query types only). | | `Executing` | The 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. ```python pqsl = ( db.live_table("DbInternal", "PersistentQueryStateLog") .where(["Date=today()", "Name=``"]) .sort("Timestamp") ) ``` ```groovy pqsl=db.liveTable("DbInternal", "PersistentQueryStateLog").where("Date=today()", "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. ```python pqslLast = ( db.live_table("DbInternal", "PersistentQueryStateLog") .where(["Date=today()", "Name=``"]) .sort("Timestamp") .tail(1) ) pel = ( db.live_table("DbInternal", "ProcessEventLog") .where("Date=today()") .where_in(pqslLast, "ProcessInfoId") .sort("Timestamp") ) ``` ```groovy pqslLast=db.liveTable("DbInternal", "PersistentQueryStateLog").where("Date=today()", "Name=``") .sort("Timestamp") .tail(1) pel=db.liveTable("DbInternal", "ProcessEventLog") .where("Date=today()") .whereIn(pqslLast, "ProcessInfoId") .sort("Timestamp") ``` ## Related documentation - [Internal tables overview](./internal-tables.md) - [`AuditEventLog`](./audit-event-log.md) - [`PersistentQueryConfigurationLog`](./persistent-query-configuration-log.md) - [`ProcessEventLogIndex`](./process-event-log-index.md) - [`ProcessEventLog`](./process-event-log.md) - [`ProcessInfo`](./process-info.md) - [`ProcessMetrics`](./process-metrics.md) - [`QueryOperationPerformanceLogCoreV2Index`](./query-operation-performance-log-index.md) - [`QueryOperationPerformanceLogCoreV2`](./query-operation-performance-log.md) - [`QueryPerformanceLogCoreV2`](./query-performance-log.md) - [`QueryUserAssignmentLog`](./query-user-assignment-log.md) - [`ResourceUtilization`](./resource-utilization.md) - [`ServerStateLogIndex`](./server-state-log-index.md) - [`ServerStateLog`](./server-state-log.md) - [`UpdatePerformanceLogCoreV2Index`](./update-performance-log-core-index.md) - [`UpdatePerformanceLogCoreV2`](./update-performance-log-core.md) - [`WorkspaceDataSnapshot`](./workspace-data-snapshot.md) - [`WorkspaceData`](./workspace-data.md)