5.3.4. xgt.GraphFrame¶

class xgt.GraphFrame(conn: Connection, name: str, container_id: int, created_at: Timestamp | None = None)¶

A GraphFrame object represents a grouping of vertex and edge frames that make a logical graph. A GraphFrame should not be instantiated directly by the user. Instead it is created by the method Connection.create_graph().

Methods that return this object: Connection.get_frame(), Connection.get_frames(), Connection.create_graph() and Connection.get_default_graph().

Parameters:

conn (Connection) – An open connection to an xGT server.
name (str) – Fully qualified name of the graph, including the namespace.
container_id (int) – The ID of the graph’s container on the server.
created_at (google.protobuf.Timestamp, optional) – The date and time the graph was created.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> g = conn.create_graph('MyGraph', { 'v0' : 'Vertex0',
>>>                                    'v1' : 'other__Vertex0',
>>>                                    'e'  : 'Edge' })
>>> print(g.name)

Methods

`add_frames`(graph_members)	Deprecated alias for `add_members()`.
`add_members`(members)	Add frames to the graph.
`clear`()	Remove all rows from every frame in the graph, keeping the frames and their schemas.
`get_member_frames`([frame_type])	Get the frames belonging to this graph.
`remove_all_members`()	Remove every frame from the graph in a single atomic operation, leaving the frames and their data unchanged; only their membership in this graph is affected.
`remove_frames`(graph_members)	Deprecated alias for `remove_members()`.
`remove_members`(members)	Remove frames from the graph, leaving the frames and their data unchanged; only their membership in this graph is affected.

Attributes

`connection`	The connection used when constructing the frame.
`created_at`	The date and time the graph was created, as a timezone-aware datetime, or None if the creation time is unavailable.
`graph_members`	Deprecated alias for `members`.
`members`	The frames belonging to this graph.
`name`	Name of the graph frame.
`num_edges`	The total number of edges across the member edge frames.
`num_vertices`	The total number of vertices across the member vertex frames.
`updated_at`	The date and time of the graph's last update, as a timezone-aware datetime, or None if the update time is unavailable.
`user_permissions`	The actions a user is allowed to take on this graph.

add_frames(graph_members: Mapping[str, str | VertexFrame | EdgeFrame] | Iterable[str | VertexFrame | EdgeFrame]) → None¶: Deprecated alias for add_members().

Deprecated since version 2.7.0: Use add_members() instead.

Add frames to the graph. The new frames are given as either a dictionary mapping aliases to frames or a set of frames. The frames can be any of names, aliases, VertexFrames, and EdgeFrames. If a frame is given without an alias, it is given an alias of its fully qualified name.

Added in version 2.7.0: Renamed from add_frames.

Parameters:

Raises:

XgtNameError – If a frame specified in the dictionary or set does not exist in the system.
XgtTypeError – If the graph members are not a dictionary mapping strings to strings, VertexFrames, or EdgeFrames or a set of strings, VertexFrames, or EdgeFrames or if the request specifies a frame which is not a vertex or edge frame.

clear() → None¶

Remove all rows from every frame in the graph, keeping the frames and their schemas.

Added in version 2.7.0.

All member frames are cleared in a single transaction, so a member vertex frame and its member incident edge frames are emptied together. The graph itself and its membership are left intact. If a member vertex frame has a non-empty incident edge frame that is not a member of this graph, the clear fails and no frame is cleared.

Raises:

XgtNotImplemented – If the connected server is too old to support clear().
XgtFrameDependencyError – If clearing a member vertex frame would leave a non-member incident edge frame’s edges dangling.
XgtSecurityError – If the user does not have permission to delete rows from a member frame.

property connection: Connection¶: The connection used when constructing the frame.

property created_at: datetime | None¶: The date and time the graph was created, as a timezone-aware datetime, or None if the creation time is unavailable.

Added in version 2.7.0.

get_member_frames(frame_type: str | None = None) → dict[str, VertexFrame | EdgeFrame]¶

Get the frames belonging to this graph. Given as a dictionary mapping aliases to frame objects.

On servers that support it, the graph’s membership and the member frames’ metadata are resolved in a single transaction, so the result is a consistent snapshot of the graph. On older servers the retrieval falls back to two separate requests.

Added in version 2.7.0.

Parameters:

frame_type (str | None) – Selects the member frame type returned: Vertex or Edge. Must be one of ‘vertex’, ‘edge’, or None. If None, members of both types are returned.

Returns:

Frame objects for the graph’s members, keyed by alias.

Return type:

dict[str, VertexFrame | EdgeFrame]

Raises:

XgtValueError – If frame_type is not one of ‘vertex’, ‘edge’, or None.
XgtNameError – If a member frame is not visible to the user.

property graph_members: dict[str, str]¶: Deprecated alias for members.

Deprecated since version 2.7.0: Use members instead.

property members: dict[str, str]¶: The frames belonging to this graph. Given as a dictionary mapping aliases to frame names.

Added in version 2.7.0: Renamed from graph_members.

property name: str¶: Name of the graph frame.

property num_edges: int¶

The total number of edges across the member edge frames.

On servers that support it, the membership and the member sizes are read in a single transaction, so the count is a consistent snapshot of the graph. On older servers the sizes are read per frame without a snapshot guarantee.

Added in version 2.7.0.

property num_vertices: int¶

The total number of vertices across the member vertex frames.

On servers that support it, the membership and the member sizes are read in a single transaction, so the count is a consistent snapshot of the graph. On older servers the sizes are read per frame without a snapshot guarantee.

Added in version 2.7.0.

remove_all_members() → None¶

Remove every frame from the graph in a single atomic operation, leaving the frames and their data unchanged; only their membership in this graph is affected.

Added in version 2.7.0.

Raises:: XgtNotImplemented – If the connected server is too old to support removing all frames from a graph.

remove_frames(graph_members: Iterable[str | VertexFrame | EdgeFrame]) → None¶: Deprecated alias for remove_members().

Deprecated since version 2.7.0: Use remove_members() instead.

remove_members(members: Iterable[str | VertexFrame | EdgeFrame]) → None¶

Remove frames from the graph, leaving the frames and their data unchanged; only their membership in this graph is affected. An empty collection removes nothing. To remove every member from the graph, use remove_all_members().

Added in version 2.7.0: Renamed from remove_frames.

Parameters:: members (Iterable[str | VertexFrame | EdgeFrame]) – The frames to remove from the graph, given as any of names, aliases, VertexFrames, and EdgeFrames.
Raises:: XgtTypeError – If the graph members are not a set of strings, VertexFrames, or EdgeFrames.

property updated_at: datetime | None¶

The date and time of the graph’s last update, as a timezone-aware datetime, or None if the update time is unavailable.

This is fetched from the server on each access, since the graph may be updated asynchronously by other operations.

Added in version 2.7.0.

property user_permissions: dict[str, bool]¶

The actions a user is allowed to take on this graph.

The actions are:

Key	Description
create_rows	True if the user can add members to the graph.
update_rows	True if the user can update the graph’s membership.
delete_rows	True if the user can remove members from the graph.
delete_frame	True if the user can delete the graph.

Added in version 2.7.0.