Converting Legacy scripts to Core+ Scripts Cheat Sheet

See the User Guide in the Core docs and Core+ docs for comprehensive documentation on the new APIs.

Data access methods

Empty .where() clauses

In a Legacy worker, a .where() method applied to an uncoalesced table (e.g., the return from db.t before filtering by a partitioning column) would coalesce the table. Alternatively, the table could explicitly be realized with the .coalesce() method. In Core+, you must use the .coalesce() method instead of .where().

Snapshots

In a Legacy worker, trigger.snapshot(source, ...) snapshots table source according to table trigger. In Core+, the method is called snapshotWhen and the positions of the tables are inverted in the call: the trigger is the argument and the source is the table on which the operation is applied: source.snapshotWhen(trigger, ...).

In Legacy, the second argument to the snapshot call is a boolean specifying if an initial snapshot should be made. In Core+, the equivalent is to pass SnapshotWhenOptions.Flag.INITIAL in the optional list of flags.

Parameterized queries

Parameterized queries allow on-demand query execution with user-provided parameters through a UI panel. This is a Legacy-only feature and is not available in Core+ workers.

In Core+, parameterized queries are replaced by deephaven.ui, which provides a richer and more flexible set of interactive capabilities.

Key differences

Migration approach

To migrate a Legacy parameterized query to Core+:

1. Replace the ParameterizedQuery structure with a deephaven.ui application.
2. Convert Parameter definitions to appropriate UI input components (e.g., ui.text_input, ui.slider, ui.date_input).
3. Replace the query function's parameter retrieval logic with reactive UI state.
4. Remove scope.setResult() calls and directly return tables and visualizations.

For detailed information on Legacy parameterized queries, refer to the parameterized queries documentation in earlier versions of the documentation (Legacy only). For Core+ UI development, see the deephaven.ui documentation.

Migrating Persistent Queries

Persistent Queries (PQs) are queries that run regularly to perform data ingestion, analysis, and dashboard creation. Both Legacy and Core+ support PQs, but there are important differences in how they are created and managed.

Worker types

• Legacy workers: Use the Legacy API and syntax.
• Core+ workers: Use the modern Core+ API and syntax (Python snake_case, updated imports, etc.).

Migration steps

To migrate a PQ from a Legacy worker to a Core+ worker:

1. Update the query script: Convert all Legacy syntax to Core+ syntax using this cheat sheet.
2. Change the worker type: In the PQ configuration, switch from a Legacy worker to a Core+ worker.
3. Test thoroughly: Validate that the migrated query produces the same results.
4. Update dependencies: Ensure any custom libraries or plugins are compatible with Core+.

Creating and managing PQs

Both Legacy and Core+ PQs are created and managed through:

• The Query Monitor UI.
• Programmatic APIs (Python and Groovy).

The PQ management APIs are largely the same between Legacy and Core+, but the query scripts themselves must use the appropriate syntax for the worker type.

For more information on PQs, see:

• Persistent Query overview.
• Programmatic query management.

Time handling

The Deephaven Core+ time library is very different from the Legacy Library, having been thoroughly modernized as described in these blog posts:

• Time library rewrite: part 1
• Time library rewrite: part 2

In particular, Legacy queries that used currentDateNy() must use today(), business calendars are entirely re-written, and the syntax of periods as input to time_table have changed.

To get the current date, you must use the today() function, which takes an optional time zone. You can use a full time zone name like America/New_York or the shortcut ET for Eastern time. The equivalent function to currentDateNy() is either today(timeZone(`America/New_York`)) or today('ET'), as in the following example:

quotes = db.liveTable("Market", "EqQuote").where("Date=today('ET')")

quotes = db.live_table("Market", "EqQuote").where("Date=today('ET')")

When the time zone is omitted, the today() function uses the value of the user.timezone property.

The common Legacy idiom lastBusinessDateNy() to get the previous business day's data has been replaced by functions on the BusinessCalendar class. First, you must retrieve the calendar with the calendar() function, which on a default Core+ installation returns the USNYSE business calendar. To verify your default business calendar, you can run the following command:

println(io.deephaven.time.calendar.Calendars.calendar().name())

import deephaven.calendar

print(deephaven.calendar.calendar().name())

You can specify an alternative business calendar name as an argument to the calendar() function. For filtering Date partitions, you may either use the minusBusinessDays method and pass today() as a String argument or use the pastBusinessDate method and convert the resulting java.time.LocalDate to a String.

As a shortcut, you can elide calendar() for the default calendar.

The following examples all retrieve the previous business day's data:

quotes = db.historicalTable("Market", "EqQuote").where("Date=minusBusinessDays(today(), 1)")
quotes2 = db.historicalTable("Market", "EqQuote").where("Date=pastBusinessDate(1).toString()")
quotes3 = db.historicalTable("Market", "EqQuote").where("Date=calendar().minusBusinessDays(today(), 1)")
quotes4 = db.historicalTable("Market", "EqQuote").where("Date=calendar().pastBusinessDate(1).toString()")
quotes5 = db.historicalTable("Market", "EqQuote").where("Date=calendar(`USNYSE`).minusBusinessDays(today(), 1)")
quotes6 = db.historicalTable("Market", "EqQuote").where("Date=calendar(`USNYSE`).pastBusinessDate(1).toString()")
quotes7 = db.historical_table("Market", "EqQuote").where("Date=formatDate(calendar(`USNYSE`).pastBusinessDate(1))")

quotes = db.historical_table("Market", "EqQuote").where(
    "Date=minusBusinessDays(today(), 1)"
)
quotes2 = db.historical_table("Market", "EqQuote").where(
    "Date=pastBusinessDate(1).toString()"
)
quotes3 = db.historical_table("Market", "EqQuote").where(
    "Date=calendar().minusBusinessDays(today(), 1)"
)
quotes4 = db.historical_table("Market", "EqQuote").where(
    "Date=calendar().pastBusinessDate(1).toString()"
)
quotes5 = db.historical_table("Market", "EqQuote").where(
    "Date=calendar(`USNYSE`).minusBusinessDays(today(), 1)"
)
quotes6 = db.historical_table("Market", "EqQuote").where(
    "Date=calendar(`USNYSE`).pastBusinessDate(1).toString()"
)
quotes7 = db.historical_table("Market", "EqQuote").where(
    "Date=formatDate(calendar(`USNYSE`).pastBusinessDate(1))"
)

If you actually want yesterday's data instead of the previous business day's data, you can use minusDays in the clause, which will include non-business days (such as weekends) in the result. For example:

quotes = db.historicalTable("Market", "EqQuote").where("Date=calendar().minusDays(today(), 1)")

import deephaven.calendar

quotes = db.historical_table("Market", "EqQuote").where(
    "Date=calendar().minusDays(today(), 1)"
)

For time tables, you must use the new Period syntax. For example:

fiveSeconds = timeTable("PT5s")
oneHour = timeTable("PT1h")

from deephaven import time_table

five_seconds = time_table("PT5s")
one_hour = time_table("PT1h")

Python

Python-only summary of changes

• Method names are now snake_case. For example, lastBy becomes last_by.

• Aggregation names (previously ComboAggregateFactory) have changed, as detailed below. For example, AggLast becomes agg.last.

• In instances of more than one parameter, arguments may take array lists instead of multiple strings; e.g., t.update(["Update Statement 1", "Update Statement 2", ...]). These are marked in the "Python method renames" table below. For comparison:

  • In a Legacy script, AggTypes will be comma-separated: source.by(AggCombo(AggType("Col1"), AggType("Col2 = NewCol1")), "Key1" , "Key2").

  • In Core, this becomes an agg_list within arrays:

    agg_list=[
       agg.first(["Col1 = NewCol1"]),
       agg.last(["Col2 = NewCol2"]),
    ]
    
    source.agg_by(agg_list, by=["GroupingColumns..."])
    

Core+ Python import equivalents

Python method renames

Table constructors

Aggregation

Filter

Sort

Select

Join

Format

Metadata

Plot

Time

Miscellaneous