Package io.deephaven.uri

Class PersistentQueryURI

java.lang.Object
io.deephaven.uri.PersistentQueryURI
@Immutable public abstract class PersistentQueryURI extends Object

A PersistentQueryURI is a URI composing the scheme `pq`, the persistent query name or serial, `/scope/`, the name of the table being fetched, and an optional argument to select a live subscription, or snapshot.


The accepted query options are

  • snapshot (false) - A boolean value indicating it the fetch should be a live subscription or a snapshot. Defaults to false
  • onDisconnect (clear) - When `snapshot` is false, or not provided, set the behavior of the table when the source query becomes unavailable. Possible values are `retain` and `clear`. When `retain` is set, the table will keep the last set of values it had before the query became unavailable. When `clear` is set it will clear all rows.
  • retryWindowMillis (500_000)- The timeout after which, if the query does not become available the table declares an error
  • waitTimeout (none) - An ISO-8601 duration (e.g. PT20S) to wait for the initial snapshot before throwing. Omit for no timeout.
  • maxRetries (0) - The maximum number of retries allowed within the `retryWindowMillis`. 0 means unlimited.

For example:

pq://my_query/scope/my_table

Fetches a live subscription to the full table `my_table` from the PQ `my_query`


To fetch a static snapshot of `my_table` from the query with serial `123456789` use:

pq://123456789/scope/my_table?snapshot=true
NOTE: Only the `snapshot` option is used when connecting to Community queries.

  • Field Details

  • Constructor Details

    • PersistentQueryURI

      public PersistentQueryURI()

  • Method Details

    • isWellFormed

      public static boolean isWellFormed(@NotNull @NotNull URI uri)
      Check if the uri is formatter properly with the scheme and path. Note that the query is validated later to provide finer grained details if there is a problem.
      Parameters:
      uri - the URI to check
      Returns:
      true if the URI is formatted properly.

    • of

      public static PersistentQueryURI of(@NotNull @NotNull String uriString)
      Create a new PersistentQueryURI from the specified URI string.
      Parameters:
      uriString - the uri string to convert
      Returns:
      a new PersistentQueryURI

    • of

      public static PersistentQueryURI of(@NotNull @NotNull URI uri)
      Create a new PersistentQueryURI from the specified URI.
      Parameters:
      uri - the uri to convert
      Returns:
      a new PersistentQueryURI

    • builder

      public static PersistentQueryURI.Builder builder()
      Get a new builder to construct a PersistentQueryURI.
      Returns:
      a new builder

    • pqIdentifier

      public abstract String pqIdentifier()
      Get the identifier of the Persistent query as a string. This could be the serial, or the query name.
      Returns:
      the Persistent Query identifier

    • variableName

      public abstract String variableName()
      Get the variable being addressed in the query scope.
      Returns:
      the name of the variable being requested

    • isSnapshot

      @Default public boolean isSnapshot()
      Get if the fetched result should be a live table, or a single snapshot. Defaults to false.
      Returns:
      true if the fetched result should be a snapshot

    • clearOnDisconnect

      @Default public boolean clearOnDisconnect()
      Get if the table should clear its rows when the source becomes unavailable. Defaults to true
      Returns:
      if the table should clear its rows on disconnect

    • retryWindowMillis

      @Default public long retryWindowMillis()
      Get the window in which the table is allowed to reconnect before an error is declared. Defaults to 5 minutes
      Returns:
      the retry window in milliseconds.

    • maxRetriesInWindow

      @Default public int maxRetriesInWindow()
      Get the maximum number of reconnection retries allowed within the retry window. Defaults to 0 (unlimited).
      Returns:
      the number or retries allowed

    • isBlink

      @Default public boolean isBlink()
      Get if the upstream table should be a blink table.
      Returns:
      true if the table should be a blink table.

    • waitTimeout

      public abstract Optional<Duration> waitTimeout()
      Get the timeout to wait for the initial snapshot. An empty Optional means wait indefinitely. Defaults to Optional.empty().

      Expressed as an ISO-8601 duration in the URI query string, e.g. waitTimeout=PT20S.

      Returns:
      the wait timeout, or Optional.empty() for no timeout

    • includedColumns

      @NotNull public abstract @NotNull Set<String> includedColumns()
      Get the columns to include from the upstream table. Defaults to all (null)
      Returns:
      the columns to include, or null for all of them.