docs: correct df.instance_nodes column types to TEXT - #301
Merged
Conversation
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
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.
Problem
df.instance_nodes()documentsresultandstatus_detailsasJSONB, butthe function actually returns them as
TEXT.The values originate from genuine
JSONBcolumns ondf.nodes, but thefunction explicitly casts them on the way out:
result::textin the SPI projection (src/monitoring.rs)"status_details::text"returned bystatus_details_select_expr(
src/node_status.rs)This also made the documented example non-functional.
->>is only definedfor
json/jsonb, so copy-pasting the documented query:fails with
operator does not exist: text ->> unknown.Changes
docs/api-reference.md: column types forresultandstatus_detailscorrected from
JSONBtoTEXT, with a note that they carry JSON text andneed an explicit
::jsonbcast 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 castrequirement.
Documentation only — no code, schema, or upgrade-script changes.
Follow-up (not in this PR)
Whether
TEXTis the right return type is a separate question. The siblingAPIs (
df.result(),df.instance_info().output) return TEXT because theirpayload 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
JSONBcolumns whose contents are guaranteed well-formed, so the cast is pureceremony and converts an impossible failure into a possible one.
Changing it is a breaking signature change (
DROP FUNCTION+CREATE, plus aretained 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