5.3.1. xgt.VertexFrame¶

class xgt.VertexFrame(conn: Connection, name: str, schema: Iterable[list[Any] | tuple[Any]], key: str, container_id: int, commit_id: int)¶

A VertexFrame represents a collection of vertices held on the xGT server. It can be used to retrieve information about the frame and the vertex properties. A VertexFrame should not be instantiated directly by the user. Instead it is created by the method Connection.create_vertex_frame().

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

Each vertex in a VertexFrame shares the same properties, described in the frame’s schema. Each vertex in the frame is uniquely identified by the schema property listed in VertexFrame.key.

Parameters:

conn (Connection) – An open connection to an xGT server.
name (str) – Fully qualified name of the vertex frame, including the namespace.
schema (Iterable[list[Any] | tuple[Any]]) – The schema defining the property names and types. Each vertex in the frame will have these properties. Given as a list of lists associating property names with xGT data types.
key (str) – The schema property name used to uniquely identify vertices in the graph. The property’s value must be unique for each vertex in the frame.
container_id (int) – The ID of the frame’s container on the server.
commit_id (int) – The ID of the last commit to the frame.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> v1 = conn.create_vertex_frame(
...        name = 'People',
...        schema = [['id', xgt.INT],
...                  ['name', xgt.TEXT]],
...        key = 'id')
>>> v2 = conn.get_frame('Companies') # An existing vertex frame
>>> print(v1.name, v2.name)

Methods

`append_columns`(new_columns)	Appends columns to the frame's schema.
`delete_columns`(columns)	Deletes columns from the frame's schema.
`get_data`([offset, length, rows, columns, ...])	Returns frame data starting at a given offset and spanning a given length.
`insert`(data[, row_labels, ...])	Inserts data rows.
`load`(paths[, header_mode, record_history, ...])	Loads data from one or more files specified in the list of paths.
`modify_columns`(new_columns)	Modifies the frame's columns.
`save`(path[, offset, length, headers, ...])	Writes the rows from the frame to a file in the location indicated by the path parameter.
`update_columns`(columns, data[, offset, ...])	Updates the entries for columns in a frame.

Attributes

`connection`	The connection used when constructing the frame.
`graphs`	The names of the graphs that the frame belongs to.
`key`	The property name that uniquely identifies vertices of this type.
`key_column`	The column position of the frame's key.
`name`	Name of the frame.
`num_rows`	The number of rows in the frame.
`num_vertices`	The number of vertices in the VertexFrame.
`row_label_universe`	The universe of row security labels that can be attached to rows of this frame.
`schema`	The frame's property names and types.
`user_permissions`	The actions a user is allowed to take on this frame.

append_columns(new_columns: Iterable[list[Any] | tuple[Any]]) → None¶

Appends columns to the frame’s schema. The new columns are given as schema entries and must have names unique from the existing column names. Entries in new columns are initialized to null values. If new_columns is None or has no entries, the function just returns.

Added in version 1.15.0.

Parameters:

new_columns (Iterable[list[Any] | tuple[Any]]) – The columns to append to the frame. Given as an iterable over list or tuple representing valid column entries.

Raises:

XgtTypeError – If new_columns is not an Iterable or None or an entry is not a tuple or list giving a valid schema entry.
XgtValueError – If a new column has a duplicate name.

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

delete_columns(columns: Iterable[int | str]) → None¶

Deletes columns from the frame’s schema. The columns are given as a mixed list of column positions and schema column names. Duplicates of the same column are accepted and behave as if the column were given once. If columns is None or has no entries, the function just returns.

Added in version 1.15.0.

Parameters:

columns (Iterable[int | str]) – The columns to delete. Given as an iterable over mixed column positions and schema column names.

Raises:

XgtTypeError – If columns is not an Iterable or an entry is not an int or str.
XgtValueError – If a position is out-of-bounds, a name is not in the schema, or a key column is deleted.

Returns frame data starting at a given offset and spanning a given length.

Parameters:

offset (int) – Position (index) of the first row to be retrieved. Cannot be given with rows.
length (int | None) – Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Cannot be given with rows.
rows (Iterable[int] | None) –
The rows to retrieve. A value of ‘None’ means all rows. Cannot be given with either offset or length.

Added in version 1.16.0.
columns (Iterable[int | str] | None) –
The columns to retrieve. Given as an iterable over mixed column positions and schema column names. A value of ‘None’ means all columns.

Added in version 1.14.0.
format (str) –
Selects the data format returned: a Python list of list, a pandas Dataframe, or an Apache Arrow Table. Must be one of ‘python’, ‘pandas’, or ‘arrow’.

Added in version 1.14.0.
include_row_labels (bool) – Indicates whether the security labels for each row should be egested along with the row. Default=False.
row_label_column_header (str | None) – The header column name to use for all row labels if include_row_labels is true and headers is true. Ignored for python format. Default=None.
row_filter (str | None) –
OpenCypher fragment used to filter, modify and parameterize the frame’s data to produce the row data returned to the client. Default=None.

Added in version 1.15.0.
expand (str) –
Controls what is returned for a RowID column type. Allowed values are:
- ’none’: Only RowID. Original behavior.
- ’light’: Expands RowIDs to Vertex, Edge, and TableRow types that include properties.
- ’full’: Expands RowIDs to Vertex, Edge, and TableRow types that include properties. Also includes frame data.
Works only for python and pandas format.

Experimental: The API of this parameter may change in future releases.

Return type:

list[list[Any]] | pandas.DataFrame | pyarrow.Table

Raises:

XgtNameError – If the frame does not exist on the server.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.
ValueError – If parameter is out of bounds or invalid format given.
OverflowError – If data is out of bounds when converting.

property graphs: set[str]¶: The names of the graphs that the frame belongs to. Only includes graphs the user has permissions to see.

Experimental: The API of this property may change in future releases.

insert(data: Iterable[Iterable[Any]] | pandas.DataFrame | pyarrow.Table, row_labels: Iterable[str] | None = None, row_label_columns: Iterable[int] | None = None, column_mapping: Mapping[str, str | int] | None = None, suppress_errors: bool = False, on_duplicate_keys: str = 'error', row_filter: str | None = None, chunk_size: int = 10000) → Job¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:

data (Iterable[Iterable[Any]] | pandas.DataFrame | pyarrow.Table) – Data represented by a list of lists of data items, by a pandas DataFrame or by a pyarrow Table.
row_labels (Iterable[str] | None) – A list of security labels to attach to each row inserted. Each label must have been passed in to the row_label_universe parameter when creating the frame. Note: Only one of row_labels and row_label_columns must be passed.
row_label_columns (Iterable[int] | None) – A list of integer column indices indicating which columns in the input data contain security labels to attach to the inserted row. Note: Only one of row_labels and row_label_columns must be passed.
column_mapping (Mapping[str, str | int] | None) –
Maps the frame column names to input columns for the ingest. The key of each element is a frame column name. The value is either the name of the column (from the Pandas frame or xGT schema column name for lists) or the file column index.

Added in version 1.15.0.
suppress_errors (bool) –
If true, will continue to insert data if an ingest error is encountered, placing the first 1000 errors in the job history. If false, stops on first error and raises. Defaults to False.

Added in version 1.11.0.
row_filter (str | None) –
OpenCypher fragment used to filter, modify and parameterize the raw data from the input to produce the row data fed to the frame.

Added in version 1.15.0.
on_duplicate_keys (str) –
Specifies what to do upon encountering a duplicate key. Allowed values are:
- ’error’: raise an Exception when a duplicate key is found.
- ’skip’: skip duplicate keys without raising.
- ’skip_same’: skip duplicate keys if the row is exactly the same without raising.
Added in version 1.12.0.
chunk_size (int) –
Number of rows to transfer in a single Arrow chunk between the client and the server.

Added in version 1.16.0.

Returns:

A Job object representing the job that has executed the insert.

Return type:

Job

Raises:

XgtIOError – If there are errors in the data being inserted or some data could not be inserted into the frame.
XgtNameError – If the frame does not exist on the server.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

property key: str¶: The property name that uniquely identifies vertices of this type.

property key_column: int¶: The column position of the frame’s key.

load(paths: Iterable[str] | str, header_mode: str = 'none', record_history: bool = True, row_labels: Iterable[str] | None = None, row_label_columns: Iterable[int | str] | None = None, delimiter: str = ',', column_mapping: Mapping[str, str | int] | None = None, suppress_errors: bool = False, row_filter: str | None = None, chunk_size: int = 10000, on_duplicate_keys: str = 'error') → Job¶

Loads data from one or more files specified in the list of paths. These files may be CSV, Parquet, or compressed CSV. Some limitations exist for compressed CSV. See docs.rocketgraph.com for more details. Each path may have its own protocol as described below.

Parameters:

paths (list or str) –

A single path or a list of paths to files. Local or server paths may contain wildcards. Wildcard expressions can contain *, ?, range sets, and negation. See docs.rocketgraph.com for more details.

Syntax for one file path
Resource type	Path syntax
local to Python:	’<path to file>’ ‘xgt://<path to file>’
xGT server:	’xgtd://<path to file>’
AWS S3:	’s3://<path to file>’
https site:	’https://<path to file>’
http site:	’http://<path to file>’
ftps server:	’ftps://<path to file>’
ftp server:	’ftp://<path to file>’

header_mode (str) –
Indicates how the file header should be processed:
- HeaderMode.NONE: No header exists.
- HeaderMode.IGNORE: Ignore the first line containing the header.
- HeaderMode.NORMAL: Process the header in non-strict mode. If a schema column is missing, a null value is ingested for that schema column. Any file column whose name does not correspond to a schema column or a security label column is ignored.
- HeaderMode.STRICT: Process the header in strict mode. The name of each header column should correspond to a schema column, a security label column, or be named IGNORE. Each schema column must appear in the file.
Only applies to CSV files.

Added in version 1.11.0.
record_history (bool) – If true, records the history of the job.
row_labels (list) – A list of security labels to attach to each row inserted with the load. Each label must have been passed in to the row_label_universe parameter when creating the frame. Note: Only one of row_labels and row_label_columns must be passed.
row_label_columns (list) – A list of columns indicating which columns in the CSV file contain security labels to attach to the inserted row. If the header mode is NONE or IGNORE, this must be a list of integer column indices. If the header mode is NORMAL or STRICT, this must be a list of string column names. Note: Only one of row_labels and row_label_columns must be passed.
delimiter (str) – Single character delimiter for CSV data. Only applies to CSV files.
column_mapping (dictionary) –
Maps the frame column names to file columns for the ingest. The key of each element is a frame column name. The value is either the name of the file column (from the file header) or the file column index. If file column names are used, the header_mode must be NORMAL. If only file column indices are used, the header_mode can be NORMAL, NONE, or IGNORE.

Added in version 1.15.0.
suppress_errors (bool) –
If true, continues to load data if an ingest error is encountered, placing the first 1000 errors into the job history. If false, stops on first error and raises. Defaults to False.

Added in version 1.11.0.
row_filter (str) –
OpenCypher fragment used to filter, modify and parameterize the raw data from the input to produce the row data fed to the frame.

Added in version 1.15.0.
chunk_size (int) –
Number of rows to transfer in a single Arrow chunk between the client and the server.

Added in version 1.16.0.
on_duplicate_keys (str) –
Specifies what to do upon encountering a duplicate key. Allowed values are:
- ’error’: Raise an Exception when a duplicate key is found.
- ’skip’: Skip duplicate keys without raising.
- ’skip_same’: Skip duplicate keys if the row is exactly the same without raising.
Added in version 1.12.0.

Returns:

A Job object representing the job that has executed the load.

Return type:

Job

Raises:

XgtIOError – If a file specified cannot be opened or if there are errors inserting any lines in the file into the frame.
XgtNameError – If the frame does not exist on the server.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

modify_columns(new_columns: Iterable[int | str | list[Any] | tuple[Any]]) → None¶

Modifies the frame’s columns. Can be used to add, delete, or reorder columns. The new columns are given as a list or tuple of mixed column positions, schema column names, or schema entries. Added columns must be given as schema entries. Column positions or names must be valid in the current schema.

Any columns in the current schema that are not in the new columns are deleted. Schema entries in the new columns with names not in the current schema are added. The columns are reordered to the order given in the new columns. Entries in added columns are initialized to null values.

The types of columns in the current schema cannot be changed. Key columns must be in the new columns.

Added in version 1.15.0.

Parameters:

new_columns (Iterable[int | str | list[Any] | tuple[Any]]) – The new schema to apply to the frame. Given as an iterable over mixed column positions, schema column names, or sequences representing valid column entries.

Raises:

XgtTypeError – If new_columns is not an Iterable, is empty, or an entry is not an int, str, or list or tuple giving a valid schema entry. If the type of an existing column is changed.
XgtValueError – If a position is out-of-bounds, a name is not in the schema, a key column is not included in the new schema, or a column name is duplicated.

property name: str¶: Name of the frame.

property num_rows: int¶: The number of rows in the frame.

property num_vertices: int¶: The number of vertices in the VertexFrame.

property row_label_universe: list[str]¶: The universe of row security labels that can be attached to rows of this frame. Only labels that are also in the authenticated user’s label set are returned.

save(path: str, offset: int = 0, length: int | None = None, headers: bool = False, record_history: bool = True, include_row_labels: bool = False, row_label_column_header: str | None = None, preserve_order: bool = False, number_of_files: int = 1, duration_as_interval: bool = False, delimiter: str = ',', row_filter: str | None = None, windows_newline: bool = False) → Job¶

Writes the rows from the frame to a file in the location indicated by the path parameter. Will save as a Parquet file if the extension is .parquet, otherwise saves as a CSV.

Parameters:

path (str) –

Path to a file.

Syntax for one file path
Resource type	Path syntax
local to Python:	’<path to file>’ ‘xgt://<path to file>’
xGT server:	’xgtd://<path to file>’
AWS S3 (Beta):	’s3://<path to file>’

offset (int) – Position (index) of the first row to be retrieved.
length (int | None) – Maximum number of rows to be retrieved.
headers (bool) – Indicates if headers should be added.
record_history (bool) – If true, records the history of the job.
include_row_labels (bool) – Indicates whether the security labels for each row should be egested along with the row.
row_label_column_header (str | None) – The header column name to use for all row labels if include_row_labels is true and headers is true.
preserve_order (bool) – Indicates if the output should keep the order the frame is stored in.
number_of_files (int) – Number of files to save. Only works with the xgtd:// protocol.
duration_as_interval (bool) –
For Parquet files duration will be saved as the logical Interval type instead of the default 64 bit unsigned integer type. Only works with the xgtd:// protocol.

Added in version 1.13.0.
delimiter (str) –
Single character delimiter for CSV data. Only applies to CSV files.

Added in version 1.13.1.
row_filter (str | None) –
OpenCypher fragment used to filter, modify and parameterize the frame’s data to produce the row data saved in the file.

Added in version 1.15.0.
windows_newline (bool) –
False indicates CSV files should use a Unix newline of line feed (LF). True indicates a Windows newline of carriage return (CR), line feed (LF). Only applies to CSV files.

Added in version 2.0.4.

Returns:

A Job object representing the job that has executed the save.

Return type:

Job

Raises:

XgtIOError – If a file specified cannot be opened.
XgtNameError – If the frame does not exist on the server.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

property schema: list[list[Any]]¶: The frame’s property names and types.

update_columns(columns: Iterable[int | str], data: Iterable[Iterable[Any]] | pandas.DataFrame | pyarrow.Table, offset: int = 0, chunk_size: int = 10000) → None¶

Updates the entries for columns in a frame. The columns are specified by position or name. The data used for the update can be python data, a pandas dataframe or a pyarrow table (Beta).

Added in version 1.16.0.

Parameters:

columns (Iterable[int | str]) – The columns to update. Given as a column’s name or position.
data (Iterable[Iterable[Any]] | pandas.DataFrame | pyarrow.Table) – Data represented by a list of lists of data items, by a pandas DataFrame or by a pyarrow Table.
offset (int) – Position (index) of the first row to update.
chunk_size (int) – Number of rows to transfer in a single Arrow chunk between the client and the server.

Raises:

XgtTypeError – If column is not a str or int.
XgtValueError – If the column’s name or position is not in the schema or if the offset is invalid.

property user_permissions: dict[str, bool]¶

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

The actions are:

Key	Description
create_rows	True if the user can add rows to the frame.
update_rows	True if the user can update columns/properties of rows.
delete_rows	True if the user can delete rows of the frame.
delete_frame	True if the user can delete the frame.

Added in version 2.0.1.