Add agtype <-> jsonb bidirectional casts (#350)

[gregfelice]

Summary

Adds explicit casts between agtype and jsonb (issue #350, open since 2022):

-- agtype -> jsonb: use jsonb operators on graph data
SELECT properties(n)::jsonb FROM cypher('g', $$ MATCH (n) RETURN n $$) AS (n agtype);
SELECT (props::jsonb)->>'name' FROM cypher('g', $$ MATCH (n) RETURN properties(n) $$) AS (props agtype);

-- jsonb -> agtype: pass jsonb data into Cypher context
SELECT '{"key": "value"}'::jsonb::agtype;

-- Roundtrip
SELECT ('{"x": 1}'::agtype::jsonb)::agtype;

-- Vertex/edge → jsonb (properties extracted as JSON object)
SELECT n::jsonb FROM cypher('g', $$ MATCH (n:Person) RETURN n $$) AS (n agtype);

Implementation

SQL language functions using json-intermediate paths:

• agtype → jsonb: ag_catalog.agtype_to_json($1)::jsonb
• jsonb → agtype: $1::text::agtype

Why json intermediate? agtype extends jsonb's binary format with types (AGTV_INTEGER, AGTV_FLOAT, AGTV_VERTEX, AGTV_EDGE, AGTV_PATH) that jsonb does not recognize. Direct binary cast causes "unknown type of jsonb container" errors. The json roundtrip correctly handles all value types — graph types are serialized as JSON objects with their properties.

Files changed

• sql/agtype_coercions.sql — adds the two cast functions and CREATE CAST statements (27 lines).
• regress/sql/agtype_jsonb_cast.sql + regress/expected/agtype_jsonb_cast.out — new regression suite covering scalar/array/object roundtrips, all jsonb scalar types → agtype, vertex/edge → jsonb with structural key checks, and NULL handling (137 + 261 lines).
• Makefile — registers agtype_jsonb_cast in the REGRESS list so the new suite runs as part of make installcheck.

No C code changes.

Test plan

• Object with integers: '{"name": "Alice", "age": 30}'::agtype::jsonb
• Arrays: '[1, 2, 3]'::agtype::jsonb
• Strings: '"hello"'::agtype::jsonb
• Nested objects: '{"a": {"b": [1, true, null]}}'::agtype::jsonb
• jsonb → agtype: '{"key": "value"}'::jsonb::agtype
• Roundtrip: ('{"x": 1}'::agtype::jsonb)::agtype
• Vertex → jsonb: graph type converted to JSON object
• properties() → jsonb: direct property extraction
• JSONB operators on agtype data: (props::jsonb)->>'name'
• All existing regression tests pass
• New agtype_jsonb_cast regression suite passes

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds explicit, bidirectional casts between agtype and jsonb so users can interoperate with PostgreSQL’s jsonb operators/functions and pass jsonb into Cypher contexts without manual conversion steps.

Changes:

• Add ag_catalog.agtype_to_jsonb(agtype) SQL wrapper and CREATE CAST (agtype AS jsonb).
• Add ag_catalog.jsonb_to_agtype(jsonb) SQL wrapper and CREATE CAST (jsonb AS agtype).
• Document rationale for using a textual/JSON intermediate to avoid binary-format incompatibilities.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jrgemignani]

@gregfelice Please see the above comments by Copilot

[gregfelice]

Addressed both Copilot suggestions:

1. Comment/implementation mismatch — Updated comment to describe the actual json-intermediate conversion path (agtype_to_json() -> json::jsonb) instead of the incorrect "text intermediate".

2. Regression tests — Added agtype_jsonb_cast test suite registered in Makefile covering:

   • agtype -> jsonb: string, null, arrays (simple/nested/empty), objects (simple/nested/with arrays/empty)
   • jsonb -> agtype: all scalar types (string, int, float, bool, null), arrays, objects
   • Roundtrips: jsonb -> agtype -> jsonb for objects, arrays, null
   • Graph data: vertex and edge -> jsonb with structural key checks (label, properties, jsonb operator access)
   • NULL handling: SQL NULL through both cast directions

All regression tests pass (agtype_jsonb_cast: ok).

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gregfelice]

Rebased onto master (force push) — the branch previously included commit cd0aebc from PR #2360 (pattern expressions), which caused Copilot to flag unrelated changes (ExplainStmt comment, %expect, Makefile).

The PR now contains only the 2 cast-specific commits:

• 7c2c8ee2 Add agtype <-> jsonb bidirectional casts (issue agtype to jsonb conversion #350)
• 6801d3ac Address Copilot review: fix comment, add regression tests

The 3 Copilot comments about pattern expression code (cypher_gram.y comment placement, %expect/%expect-rr, Makefile scope) are no longer applicable. The 2 original Copilot suggestions (comment/implementation mismatch, regression test coverage) were already addressed in the previous round.

Regression test: agtype_jsonb_cast OK.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jrgemignani]

@gregfelice It looks like just one item left and we're good.

[gregfelice]

@jrgemignani — resolved the final Copilot thread. The PR description already reflects the regression test and Makefile changes (see "Files changed"). All items addressed; ready for merge when you have a moment. Thanks!

[gregfelice]

Gentle bump — all Copilot feedback has been resolved (since 2026-04-15), CI is green on the 6 checks, and the branch still merges cleanly against current master (no rebase needed). Ready when you have review bandwidth. Thanks!

[jrgemignani]

@gregfelice Sorry for the delay. Can you rebase this with the master, plz. It is complaining that there are conflicts.

[gregfelice]

On it

[gregfelice]

@jrgemignani — rebased onto current master (HEAD 01ee9414).

Conflict resolution: only one conflict, in Makefile's REGRESS list, between this branch's agtype_jsonb_cast test entry and master's newly-added reserved_keyword_alias test. Resolved by appending agtype_jsonb_cast after reserved_keyword_alias — alphabetical-adjacent, no semantic difference.

Post-rebase discovery — third commit added (506138f4): the age_upgrade regression test (added to master after this PR was originally opened) flagged that the new agtype_to_jsonb / jsonb_to_agtype functions and their casts were missing from the upgrade template age--1.7.0--y.y.y.sql. Added them at the end of the template per its own "add all additions to the end of this file" convention.

Cassert installcheck: 35/36 AGE tests green (pgvector skipped — vector extension not installed locally, unrelated to this PR).