GFQL schema tutorial: infer, refine, bind, and validate Cypher

[lmeyerov]

Summary

Follow-up tutorial lane for the public GFQL schema/type-system work. This should run after #1338 lands so the tutorial can show the practical user workflow starting from existing graph data instead of requiring users to hand-write every schema.

Schedule

Do not start as an implementation lane until:

• feat(gfql): add public declarative schema model #1457 / GFQL type system follow-on A: public declarative schema model + stable exports #1337 has landed the public declarative schema API, and
• GFQL type system follow-on B: schema inference API + typed topology extraction #1338 has landed schema inference / typed topology extraction.

This is intentionally after inference, because the community-facing story should be: load graph data, infer a schema, refine it, bind it, and validate Cypher.

Scope

• Add a user-facing docs tutorial or notebook for GFQL schemas.
• Use a small pandas graph with clear node/edge types, e.g. Person, Company, WORKS_AT.
• Demonstrate infer_schema() once GFQL type system follow-on B: schema inference API + typed topology extraction #1338 lands.
• Show refining or overriding inferred schema declarations.
• Bind the schema to a graph and validate Cypher.
• Demonstrate helpful validation failures for missing properties and topology mismatch.
• Explain strict vs permissive validation once feat(gfql): add public declarative schema model #1457 strict-mode behavior is finalized.
• Link to Arrow/plottable boundary work from GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 without making that the main tutorial.

Out of scope

• Implementing schema inference itself; tracked by GFQL type system follow-on B: schema inference API + typed topology extraction #1338.
• Implementing Arrow/plottable boundary enforcement; tracked by GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339.
• Large cookbook or gallery expansion beyond one focused tutorial.

Acceptance

• Tutorial runs under docs/notebook validation used by the repo.
• Tutorial uses the public stable imports from GFQL type system follow-on A: public declarative schema model + stable exports #1337.
• Tutorial includes an inference-first workflow from GFQL type system follow-on B: schema inference API + typed topology extraction #1338.
• Tutorial covers at least one passing validation and one structured failure.
• [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046, GFQL type system follow-on B: schema inference API + typed topology extraction #1338, and GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 are cross-linked with the tutorial schedule.

Related

• [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046
• GFQL type system follow-on A: public declarative schema model + stable exports #1337
• GFQL type system follow-on B: schema inference API + typed topology extraction #1338
• GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339
• feat(gfql): add public declarative schema model #1457

[lmeyerov]

Coordinator schedule update: filed #1465 for gfql_remote() typed-schema transport.

For this tutorial lane, keep the core tutorial inference-first and local until #1465 lands. After #1465, add or link a short remote section showing that a bound schema can travel with gfql_remote() requests. Do not make remote schema transport a blocker for the first local schema tutorial unless we explicitly change the release story.

[lmeyerov]

Coordinator research follow-up note for #1464:

Keep this tutorial after #1338 inference. The community-facing workflow should be:

1. Load graph data.
2. Infer schema.
3. Refine schema.
4. Bind schema.
5. Validate Cypher / GFQL.
6. Optionally discuss Arrow boundary behavior after GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 and remote behavior after GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465.

Avoid presenting #1457 alone as a full static graph calculus. The tutorial should explain:

• Cypher labels are predicates.
• NodeType / EdgeType are open contracts.
• Multi-label conjunctive nodes merge trait/property fragments.
• Disjunctive labels branch and may make properties maybe-present.
• Graph-growing calls such as PageRank/degree require schema effects, which are a follow-on lane rather than part of the first tutorial unless already landed.