docs: DOC-612: Engine internals#8190
Draft
margaretkennedy wants to merge 4 commits into
Draft
Conversation
margaretkennedy
added
documentation
Contributor
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “mental model / patterns of use” conceptual guide (Python + Groovy) and expands the “Deephaven’s design” deep-dive with more concrete internal execution details, then wires the new guide into both doc sidebars.
Changes:
- Introduce new conceptual docs: “How Deephaven works: A mental model and patterns of use” (Python and Groovy) plus accompanying overview SVGs.
- Expand “Deephaven’s design” with a “live data stack” overview and step-by-step descriptions of how
where/updatework internally. - Add doc sidebar entries and generated Python snapshot JSONs for the new page’s code blocks.
Reviewed changes
Copilot reviewed 17 out of 19 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/python/snapshots/edaf23d8ed270a873a4a503d061ce5b3.json | Adds snapshot output for mental-model examples (static vs live). |
| docs/python/snapshots/c0cf9368b55fc7ce4243bd32c3db0aa8.json | Adds snapshot output for mental-model table creation example. |
| docs/python/snapshots/9083051d0fcd1b3b42d104274e1c8a0d.json | Adds snapshot output for mental-model empty_table example. |
| docs/python/snapshots/8f9813a80ee597fea42abbcb27cade4b.json | Adds snapshot output for mental-model aggregation example. |
| docs/python/snapshots/8c311880e96e78f67a5f699ca3772067.json | Adds snapshot output for mental-model formula example. |
| docs/python/snapshots/8bb27d10d6138d538b1fe44d3e9b8f27.json | Adds snapshot output for mental-model derived-values example. |
| docs/python/snapshots/58f5fd60819f04fc140186f690789cc7.json | Adds snapshot output for mental-model live filtering example. |
| docs/python/snapshots/487ca331c13ee0bcd82b2f4a315a37f5.json | Adds snapshot output for mental-model “recipes” example. |
| docs/python/snapshots/28e41f33305dcb9b4f677a0f55b0db61.json | Adds snapshot output for mental-model view vs update example. |
| docs/python/snapshots/266038b5eda5c011dedb6a4d8d9a49f4.json | Adds snapshot output for mental-model ii / i example. |
| docs/python/snapshots/1b0d0916de46d1846243aded35151e27.json | Adds snapshot output for mental-model sequential-processing example. |
| docs/python/sidebar.json | Adds “Patterns of use” entry under Architectural details (needs formatting fix). |
| docs/python/conceptual/deephaven-mental-model.md | New mental-model conceptual guide (Python). |
| docs/python/conceptual/deephaven-design.md | Adds onboarding note and new “live data stack” + “how operations work” sections. |
| docs/python/assets/conceptual/mental-model-overview.svg | New diagram used by the Python mental-model page. |
| docs/groovy/sidebar.json | Adds “Patterns of use” entry under Architectural Details. |
| docs/groovy/conceptual/deephaven-mental-model.md | New mental-model conceptual guide (Groovy). |
| docs/groovy/conceptual/deephaven-design.md | Adds “live data stack” + “how operations work” sections (contains a broken link). |
| docs/groovy/assets/conceptual/mental-model-overview.svg | New diagram used by the Groovy mental-model page. |
Comment on lines
+125
to
128
| { | ||
| "label": "Patterns of use", | ||
| "path": "conceptual/deephaven-mental-model.md" | ||
| }, |
|
|
||
| 1. **Formula parsing**: The formula (e.g., `"Total = Price * Quantity"`) is parsed using [JavaParser](https://javaparser.org/). Simple formulas may use pre-compiled implementations; complex formulas trigger dynamic compilation of a new Java class. | ||
|
|
||
| 2. **Column source creation**: A new `ColumnSource` is created for each derived column. This source computes values on-demand or caches them, depending on the operation variant ([`update`](../reference/table-operations/select/update.md) vs [`updateView`](../reference/table-operations/select/updateView.md)). |
| | I want to... | Use this | | ||
| | -------------------------- | ------------------------------------------------------ | | ||
| | Check if a table updates | `table.is_refreshing` | | ||
| | Stop updates | `table.snapshot()` | |
| | I want to... | Use this | | ||
| | -------------------------- | ------------------------------------------------------ | | ||
| | Check if a table updates | `table.isRefreshing()` | | ||
| | Stop updates | `table.snapshot()` | |
margaretkennedy
marked this pull request as draft
July 1, 2026 15:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.