GFQL Schema

GFQL Schema#

Experimental public declarative graph schema model for GFQL validation.

The import path is public, but this schema surface is still experimental while inference, coercion, remote transport, and planner use are developed.

class graphistry.schema.EdgeTopology(relationship_type, source_labels, destination_labels)#

Bases: object

Experimental source/destination-label contract for a relationship type.

Parameters:

  • relationship_type (str)

  • source_labels (FrozenSet[str])

  • destination_labels (FrozenSet[str])

as_metadata()#
Return type:

Dict[str, object]

destination_labels: FrozenSet[str]#
classmethod from_metadata(value)#

Import topology from the metadata shape emitted by as_metadata().

Parameters:

value (Mapping[str, object])

Return type:

EdgeTopology

pretty(format='cypher')#

Render this relationship topology as compact schema text.

Parameters:

format (Literal['cypher', 'yaml', 'compact'])

Return type:

str

relationship_type: str#
source_labels: FrozenSet[str]#
class graphistry.schema.EdgeType(name, source, destination, properties=None)#

Bases: object

Experimental declarative edge contract with topology constraints.

Parameters:

  • name (str)

  • source (FrozenSet[str])

  • destination (FrozenSet[str])

  • properties (Mapping[str, NodeRef | EdgeRef | ScalarType | PathType | ListType])

property columns: FrozenSet[str]#

Columns admitted for this edge type, including relationship label.

destination: FrozenSet[str]#
classmethod from_arrow(name, source, destination, schema, *, include_type_label=True, coercion='widen')#

Import an edge contract from a pyarrow.Schema declaration.

Parameters:

  • name (str)

  • source (NodeType | str | Iterable[str])

  • destination (NodeType | str | Iterable[str])

  • schema (Any)

  • include_type_label (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

EdgeType

name: str#
pretty(format='cypher')#

Render this edge contract as compact schema text.

Example:

EdgeType("WORKS_AT", "Person", "Company", {"since": int}).pretty() returns (:Person)-[:WORKS_AT {since: int64}]->(:Company).

Parameters:

format (Literal['cypher', 'yaml', 'compact'])

Return type:

str

properties: Mapping[str, NodeRef | EdgeRef | ScalarType | PathType | ListType]#
source: FrozenSet[str]#
to_arrow(*, include_type_label=True, coercion='widen')#

Export this edge contract as a pyarrow.Schema.

Parameters:

  • include_type_label (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

Any

to_row_schema(*, include_type_label=True)#

Export this edge contract as GFQL’s Arrow-bridge row schema.

Parameters:

include_type_label (bool)

Return type:

RowSchema

property topology: EdgeTopology#
class graphistry.schema.GraphSchema(node_types=(), edge_types=(), *, strict=True, node_id_column=None, edge_source_column=None, edge_destination_column=None)#

Bases: object

Experimental public graph schema contract for GFQL validation.

Parameters:

  • node_types (Tuple[NodeType, ...])

  • edge_types (Tuple[EdgeType, ...])

  • strict (bool)

  • node_id_column (str | None)

  • edge_source_column (str | None)

  • edge_destination_column (str | None)

edge_arrow(*, include_type_labels=True, coercion='widen')#

Export the union of edge declarations as a pyarrow.Schema.

Parameters:

  • include_type_labels (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

Any

property edge_columns: FrozenSet[str]#
property edge_columns_by_type: Dict[str, Tuple[str, ...]]#
edge_destination_column: str | None = None#
edge_source_column: str | None = None#
edge_types: Tuple[EdgeType, ...]#
classmethod from_arrow(declaration=None, *, node_types=None, edge_types=None, strict=True, node_id_column=None, edge_source_column=None, edge_destination_column=None, coercion='widen')#

Import graph schema declarations from Arrow schemas.

This is not inference: callers provide node/edge names and edge topology, either directly or via the payload emitted by to_arrow().

Parameters:

  • declaration (Mapping[str, Any] | None)

  • node_types (Mapping[str, Any] | None)

  • edge_types (Mapping[str, Any] | None)

  • strict (bool)

  • node_id_column (str | None)

  • edge_source_column (str | None)

  • edge_destination_column (str | None)

  • coercion (Literal['strict', 'widen'])

Return type:

GraphSchema

node_arrow(*, include_labels=True, coercion='widen')#

Export the union of node declarations as a pyarrow.Schema.

Parameters:

  • include_labels (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

Any

property node_columns: FrozenSet[str]#
property node_columns_by_label: Dict[str, Tuple[str, ...]]#
node_id_column: str | None = None#
node_types: Tuple[NodeType, ...]#
pretty(format='cypher')#

Render this schema for prompts, logs, or debugging.

format="cypher" is the compact default for LLM prompts, format="yaml" is indented for human debugging, and format="compact" returns a one-line summary.

Parameters:

format (Literal['cypher', 'yaml', 'compact'])

Return type:

str

strict: bool = True#
to_arrow(*, include_labels=True, include_type_labels=True, coercion='widen')#

Export this graph schema as Arrow declarations.

The payload is intentionally declaration-shaped rather than inferred: per-node and per-edge entries preserve public type names and topology, while nodes and edges expose table-level merged schemas for dataframe boundary validation.

Parameters:

  • include_labels (bool)

  • include_type_labels (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

Dict[str, Any]

to_catalog(*, node_id_column=None, edge_source_column=None, edge_destination_column=None, strict=None)#

Adapt this public schema into the internal GFQL schema catalog.

Parameters:

  • node_id_column (str | None)

  • edge_source_column (str | None)

  • edge_destination_column (str | None)

  • strict (bool | None)

Return type:

GraphSchemaCatalog

class graphistry.schema.NodeType(name, properties=None, labels=None)#

Bases: object

Experimental declarative node contract for GFQL schema validation.

name is the stable user-facing type name. labels defaults to (name,) and maps to GFQL’s existing label__<Label> convention.

Parameters:

  • name (str)

  • properties (Mapping[str, NodeRef | EdgeRef | ScalarType | PathType | ListType])

  • labels (FrozenSet[str])

property columns: FrozenSet[str]#

Columns admitted for this node type, including label columns.

classmethod from_arrow(name, schema, *, labels=None, include_labels=True, coercion='widen')#

Import a node contract from a pyarrow.Schema declaration.

Parameters:

  • name (str)

  • schema (Any)

  • labels (Iterable[str] | None)

  • include_labels (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

NodeType

labels: FrozenSet[str]#
name: str#
pretty(format='cypher')#

Render this node contract as compact schema text.

Example:

NodeType("Person", {"id": int}).pretty() returns (:Person {id: int64}).

Parameters:

format (Literal['cypher', 'yaml', 'compact'])

Return type:

str

properties: Mapping[str, NodeRef | EdgeRef | ScalarType | PathType | ListType]#
to_arrow(*, include_labels=True, coercion='widen')#

Export this node contract as a pyarrow.Schema.

Parameters:

  • include_labels (bool)

  • coercion (Literal['strict', 'widen'])

Return type:

Any

to_row_schema(*, include_labels=True)#

Export this node contract as GFQL’s Arrow-bridge row schema.

Parameters:

include_labels (bool)

Return type:

RowSchema

graphistry.schema.pretty_print_schema(schema, format='cypher')#

Render a public graph schema declaration.

This ergonomic wrapper mirrors each schema dataclass’s pretty() method. Example:

pretty_print_schema(schema, format="compact") returns a one-line summary such as GraphSchema(2 node types, 1 edge type, 5 properties).

Parameters:
Return type:

str