Skip to content

feat(gfql): add public declarative schema model#1457

Open
lmeyerov wants to merge 1 commit into
masterfrom
feature/issue-1337-public-schema
Open

feat(gfql): add public declarative schema model#1457
lmeyerov wants to merge 1 commit into
masterfrom
feature/issue-1337-public-schema

Conversation

@lmeyerov
Copy link
Copy Markdown
Contributor

@lmeyerov lmeyerov commented May 15, 2026

Closes #1337

Summary

  • add stable public graphistry.schema declarations: NodeType, EdgeType, GraphSchema, EdgeTopology
  • make node/edge property declarations Arrow-first: accept pyarrow.Schema, Arrow dtype/field mapping values, and GFQL RowSchema, while preserving int/str shorthand
  • export node/edge declarations back to pyarrow.Schema with to_arrow() through the existing GFQL Arrow bridge
  • support graphistry.bind(..., schema=schema) / g.bind(schema=schema) and adapt public schemas into the existing internal GraphSchemaCatalog
  • extend Cypher preflight/binder validation for scoped node properties, scoped edge properties, declared relationship types, and edge source/destination topology
  • wire schema-level strict/permissive policy: GraphSchema(strict=False) now makes schema-bound g.gfql_validate(...) permissive by default, while explicit call-level strict=True still forces strict validation
  • document the public contract and add changelog/tests

Notes

Validation

  • python3 -m pytest -q graphistry/tests/compute/gfql/test_public_schema.py graphistry/tests/compute/gfql/cypher/test_binder.py::test_binder_schema_metadata_can_disable_schema_field_checks graphistry/tests/compute/gfql/cypher/test_binder.py::test_binder_schema_enforced_even_when_legacy_strict_name_flag_false -> 14 passed
  • python3 -m pytest -q graphistry/tests/compute/gfql/test_public_schema.py graphistry/tests/compute/gfql/test_ir_arrow_bridge.py graphistry/tests/compute/gfql/cypher/test_binder.py -> 100 passed, 10 warnings
  • ./bin/ruff.sh graphistry/compute/gfql_validate.py graphistry/compute/gfql/frontends/cypher/binder.py graphistry/tests/compute/gfql/test_public_schema.py graphistry/tests/compute/gfql/cypher/test_binder.py graphistry/schema.py -> pass
  • ./bin/typecheck.sh graphistry/compute/gfql_validate.py graphistry/compute/gfql/frontends/cypher/binder.py graphistry/schema.py -> pass
  • python3 -m compileall -q graphistry/compute/gfql_validate.py graphistry/compute/gfql/frontends/cypher/binder.py graphistry/schema.py -> pass
  • git diff --check origin/master...HEAD -> pass
  • Rebased onto origin/master@94577717; final PR head 3f3319d9
  • Review skill reconverged after the strict/permissive policy fix: wave 10 found/fixed the IMPORTANT strict policy gap; waves 11/12 found no further issues; waves 13/14 reconverged after the final rebase
  • DGX RAPIDS/cuDF on 3f3319d9: 25.02/gfql PASS, 26.02/gfql PASS; selected suite showed 366 passed, 5 warnings
  • GitHub CI green on 3f3319d9: duplicate tck-gfql, docs, ReadTheDocs, full AI, core Python, pandas/polars, CodeQL, and no-plans-in-repo all passing

Local ./bin/test-minimal-lite.sh was attempted earlier through a temporary python -> python3 shim and failed in this CPU shell on local CUDA/cuDF initialization (cudaErrorNoDevice) plus GPU-backed UMAP/text paths. GPU validation has since passed on dgx-spark.

@lmeyerov lmeyerov force-pushed the feature/issue-1337-public-schema branch from ba92106 to 45c1b2c Compare May 15, 2026 21:21
@lmeyerov lmeyerov marked this pull request as ready for review May 15, 2026 21:43
@lmeyerov lmeyerov force-pushed the feature/issue-1337-public-schema branch from 45c1b2c to 582009a Compare May 15, 2026 21:58
@lmeyerov lmeyerov force-pushed the feature/issue-1337-public-schema branch 2 times, most recently from dd31542 to 9532bd2 Compare May 15, 2026 23:59
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.

GFQL type system follow-on A: public declarative schema model + stable exports

1 participant