Skip to content

docs: correct df.instance_nodes column types to TEXT - #301

Merged
pinodeca merged 1 commit into
mainfrom
docs/295-instance-nodes-column-types
Jul 27, 2026
Merged

docs: correct df.instance_nodes column types to TEXT#301
pinodeca merged 1 commit into
mainfrom
docs/295-instance-nodes-column-types

Conversation

@pinodeca

Copy link
Copy Markdown
Collaborator

Problem

df.instance_nodes() documents result and status_details as JSONB, but
the function actually returns them as TEXT.

The values originate from genuine JSONB columns on df.nodes, but the
function explicitly casts them on the way out:

  • result::text in the SPI projection (src/monitoring.rs)
  • "status_details::text" returned by status_details_select_expr
    (src/node_status.rs)

This also made the documented example non-functional. ->> is only defined
for json/jsonb, so copy-pasting the documented query:

SELECT status_details->>'execution_id' FROM df.instance_nodes('a1b2c3d4');

fails with operator does not exist: text ->> unknown.

Changes

  • docs/api-reference.md: column types for result and status_details
    corrected from JSONB to TEXT, with a note that they carry JSON text and
    need an explicit ::jsonb cast for JSON operators.
  • docs/api-reference.md: the example query now casts before extracting.
  • USER_GUIDE.md: the Function Nodes column descriptions note the same cast
    requirement.

Documentation only — no code, schema, or upgrade-script changes.

Follow-up (not in this PR)

Whether TEXT is the right return type is a separate question. The sibling
APIs (df.result(), df.instance_info().output) return TEXT because their
payload comes back from the duroxide runtime as an opaque string with no schema
guarantee. That reasoning does not apply here: these two columns come from real
JSONB columns whose contents are guaranteed well-formed, so the cast is pure
ceremony and converts an impossible failure into a possible one.

Changing it is a breaking signature change (DROP FUNCTION + CREATE, plus a
retained TEXT-returning wrapper symbol for Scenario B1 against frozen 0.2.2-0.2.4
schemas). Worth deciding while the 0.2.5 upgrade script is still open, since the
API is only one release old and the pre-1.0 breaking-change allowance goes away
at 1.0.

Closes #295

df.instance_nodes() projects result and status_details as TEXT
(result::text in src/monitoring.rs, status_details::text in
src/node_status.rs), but the API reference and user guide both
documented them as JSONB.

This also made the documented example non-functional: `->>` is only
defined for json/jsonb, so `status_details->>'execution_id'` against
a TEXT column raises "operator does not exist: text ->> unknown".

Document the actual TEXT return types and show the explicit ::jsonb
cast required to use JSON operators.

Closes #295
@pinodeca
pinodeca merged commit 9723f45 into main Jul 27, 2026
5 checks passed
@pinodeca
pinodeca deleted the docs/295-instance-nodes-column-types branch July 27, 2026 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

df.instance_nodes: status_details/result are TEXT but docs say JSONB

1 participant