5.2.1. xgt.Connection¶

class xgt.Connection(host: str = '127.0.0.1', port: int = 4367, flags: dict | None = None, auth: ~xgt.connection.BasicAuth | ~xgt.connection.KerberosAuth | ~xgt.connection.PKIAuth = <xgt.connection.BasicAuth object>)¶

Connection to the server with functionality to create, change, and remove graph structures and run jobs.

Parameters:

host (str) – IP address of the computer where the server is running.
port (int) – Port where the server is listening on for RPC calls.
auth (BasicAuth or KerberosAuth or PKIAuth) –
Instance of the authentication mechanism to use. Can be BasicAuth, KerberosAuth or PKIAuth. Default is BasicAuth with no parameters.

Added in version 1.11.0.
flags (dict) –
Dictionary containing flags. Possible flags are:

aws_access_key_idstr
Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string.

aws_secret_access_keystr
Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string.

aws_session_tokenstr
Amazon Session Token, used for authentication when loading data files from S3 buckets. The default is an empty string.

sslboolean
If true use ssl authentication for secure server channels. The default is False.

ssl_root_dirstr
Path to the root folder for ssl certificates and private keys. Defaults to the user’s home directory.

ssl_server_cnstr
The Common Name (CN) on the certificate of the server to connect to. The default is the hostname.

ssl_server_certstr
File containing the certificate chain that validates the server’s certificate. Defaults to ssl_root_dir + ‘/certs/ca-chain.cert.pem’.

Added in version 1.11.0.

ssl_use_mtlsbool
Indicates whether to use the mutual TLS protocol. The client must provide certificates validating its identity under ssl_root_dir. Defaults to False.

Added in version 1.11.0.

ssl_client_certstr
File containing the client’s certificate. Defaults to ssl_root_dir + ‘/certs/client.cert.pem’

ssl_client_keystr
File containing the client’s key. Defaults to ssl_root_dir + ‘/private/client.key.pem’
versionadded: (..) – 1.16.0:

Methods

`__init__`([host, port, flags, auth])	Constructor for Connection.
`cancel_job`(job)	Cancel the execution of a job in the server.
`create_edge_frame`(name, schema, source, ...)	Create a new EdgeFrame in the server.
`create_edge_frame_from_data`(data_source, ...)	Create a new EdgeFrame in the server based on the data source.
`create_namespace`(name[, frame_labels, ...])	Create a new empty namespace on the server.
`create_table_frame`(name, schema[, ...])	Create a new TableFrame in the server.
`create_table_frame_from_data`(data_source, name)	Create a new TableFrame in the server based on the data source.
`create_vertex_frame`(name, schema, key[, ...])	Create a new VertexFrame in the server.
`create_vertex_frame_from_data`(data_source, ...)	Create a new VertexFrame in the server based on the data source.
`drop_frame`(frame[, attempts])	Drop a VertexFrame, EdgeFrame, or TableFrame.
`drop_frames`(frames[, attempts])	Drop a VertexFrame, EdgeFrame, or TableFrame.
`drop_namespace`(namespace[, force_drop, attempts])	Drop a namespace from the server.
`get_config`([keys])	Get one or more configuration values from the server.
`get_default_namespace`()	Get the name of the default namespace.
`get_frame`(name)	Get a frame object that allows interaction with a frame present in the xGT server.
`get_frame_labels`(frame)	Retrieve the current security labels (CRUD) on a specific frame.
`get_frames`([names, namespace, frame_type])	Get a list of Frame objects that correspond to each frame in the xGT server.
`get_jobs`([jobids])	Get a list of Job objects, each representing the state of the job on the server at the point in time of the invocation of this function.
`get_metrics_status`()	Check whether the metrics cache is on and finished with updates.
`get_namespaces`()	Get a list of namespaces present in the xGT server.
`get_schema_from_data`(data_source[, ...])	Get back an inferred frame schema from the data source passed in.
`get_user_labels`()	Retrieve the current security labels of the user.
`run_job`(query[, parameters, optlevel, ...])	Run a TQL query as a job.
`schedule_job`(query[, parameters, optlevel, ...])	Schedule a TQL query as a job.
`set_config`(config_dict)	Set key-value pairs in the server configuration.
`set_default_namespace`(default_namespace)	Set the default namespace for this user session.
`wait_for_job`(job[, timeout])	Wait for a job.
`wait_for_metrics`([timeout])	Wait until the metrics cache is finished with updates.

Attributes

`free_user_memory_size`	The amount of free memory available for user data on the xGT server.
`max_user_memory_size`	The maximum amount of memory available for user data on the xGT server.
`server_version`	The current server version.
`userid`	The identity of the connected user.

__init__(host: str = '127.0.0.1', port: int = 4367, flags: dict | None = None, auth: ~xgt.connection.BasicAuth | ~xgt.connection.KerberosAuth | ~xgt.connection.PKIAuth = <xgt.connection.BasicAuth object>)¶: Constructor for Connection. Called when Connection is created.

cancel_job(job: Job | int) → bool¶

Cancel the execution of a job in the server.

A job can be canceled only if it is running and will have a status of canceled after its cancellation. A job that already had a status of completed or failed before invoking this function will keep that status after invoking this function.

Parameters:: job (Job, int) – A Job object or an integer job id to cancel.
Returns:: True if the job was cancelled. False if the job already had a status of completed or failed before invoking this function.
Return type:: bool
Raises:: XgtSecurityError – If the user does not have required permissions for this action.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges and run queries ...
>>> print(conn.cancel_job(18))
True
>>> all_jobs = conn.get_jobs()
>>> for j in all_jobs:
>>> ... conn.cancel_job(j)

create_edge_frame(name: str, schema: list[list], source: str | VertexFrame, target: str | VertexFrame, source_key: str, target_key: str, frame_labels: Mapping[str, Sequence[str]] | None = None, row_label_universe: Sequence | None = None, attempts: int = 1) → EdgeFrame¶

Create a new EdgeFrame in the server.

An EdgeFrame represents a collection of edges held on the xGT server that share the same property names and types. The source vertex of each edge in an EdgeFrame must belong to the same VertexFrame. This source VertexFrame is identified by the source parameter of this function. The target vertex of each edge in an EdgeFrame must belong to the same VertexFrame. This target VertexFrame is identified by the target parameter.

For each edge in the EdgeFrame, its source vertex is identified by the edge property name given in the parameter source_key, which must be one of the properties listed in the schema. The edge target vertex is identified by the property name given in the parameter target_key, which must be one of the properties listed in the schema.

Parameters:

name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
schema (list of lists) – List of lists associating property names with xGT data types. Each edge in the EdgeFrame will have these properties.
source (str or VertexFrame) – The name of a VertexFrame or a VertexFrame object. The source vertex of each edge in this EdgeFrame will belong to this VertexFrame.
target (str or VertexFrame) – The name of a VertexFrame or a VertexFrame object. The target vertex of each edge in this EdgeFrame will belong to this VertexFrame.
source_key (str) – The edge property name that identifies the source vertex of an edge. This is one of the properties from the schema.
target_key (str) – The edge property name that identifies the target vertex of an edge. This is one of the properties from the schema.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterable of all possible labels to be used for rows inside this edge frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
attempts (int) – Number of times to attempt the creation of the EdgeFrame. It will be retried if it fails due to transactional conflicts.

Returns:

Frame to the collection of edges.

Return type:

EdgeFrame

Raises:

XgtNameError – If the name provided is not a correct frame name. If the source_key or target_key are not in the schema. If the source or target VertexFrames are not found. If a frame with this name already exists in the namespace.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> conn.create_vertex_frame(
      name = 'People',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]],
...   key = 'id')
>>> conn.create_vertex_frame(
      name = 'Companies',
...   schema = [['id', xgt.INT],
...             ['size', xgt.TEXT],
...             ['name', xgt.TEXT]],
...   key = 'id',
...   frame_labels = { 'create' : ['label1'],
...                    'delete' : ['label1', 'label2'] })
>>> conn.create_edge_frame(
      name = 'WorksFor',
...   schema = [['srcid', xgt.INT],
...             ['role', xgt.TEXT],
...             ['trgid', xgt.INT]],
...   source = 'People',
...   target = 'Companies',
...   source_key = 'srcid',
...   target_key = 'trgid',
...   frame_labels = { 'create' : ['label1'],
...                    'update' : ['label3'],
...                    'delete' : ['label1', 'label2'] })

create_edge_frame_from_data(data_source: str | Iter[str] | pandas.DataFrame | pyarrow.Table, name: str, source: str | VertexFrame, target: str | VertexFrame, source_key: str, target_key: str, schema: List[List] | None = None, header_mode: str = 'none', delimiter: str = ',', column_mapping: Map[str, str | int] | None = None, frame_labels: Seq[str] | None = None, row_label_universe: Seq | None = None, row_labels: Seq[str] | None = None, row_label_columns: Seq[str] | None = None, source_vertex_row_labels: Seq[str] | None = None, target_vertex_row_labels: Seq[str] | None = None, suppress_errors: bool = False, on_duplicate_keys: str = 'error') → EdgeFrame¶

Create a new EdgeFrame in the server based on the data source. (Beta)

The schema of the frame will be automatically inferred from the data passed in as data_source and the data will be inserted into the frame.

Parameters:

data_source (str, list of str, pyarrow Table, pandas DataFrame) – The data source from which to create a frame. If a string or list of strings, each entry must be a file path possibly with wildcards. For the file path, the same protocols are supported as load(). Refer to load().
name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
source (str) – The name of a VertexFrame. The source vertex of each edge in this EdgeFrame will belong to this VertexFrame. This frame will be automatically created if it does not already exist.
target (str) – The name of a VertexFrame. The target vertex of each edge in this EdgeFrame will belong to this VertexFrame. This frame will be automatically created if it does not already exist.
source_key (str) – The edge property name that identifies the source vertex of an edge. This is one of the properties from the schema. Note that the schema will be automatically inferred from the data_source and may be affected by the header_mode and column_mapping parameters.
target_key (str) – The edge property name that identifies the target vertex of an edge. This is one of the properties from the schema. Note that the schema will be automatically inferred from the data_source and may be affected by the header_mode and column_mapping parameters.
schema (list of lists) –
List of lists associating property names with xGT data types. Each edge in the EdgeFrame will have these properties.

Optional. Default is None. If None, the schema is inferred from data_source.
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.
Optional. Default=HeaderMode.NONE. Only applies to CSV files.
delimiter (str) – 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 frame’s 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.

Optional. Default is None.

Added in version 1.15.0.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterable of all possible labels to be used for rows inside this edge frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
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.
source_vertex_row_labels (list) – A list of security labels to attach to each source vertex that is implicitly inserted. Each label must have been passed in to the row_label_universe parameter when creating the frame.
target_vertex_row_labels (list) – A list of security labels to attach to each target vertex that is implicitly inserted. Each label must have been passed in to the row_label_universe parameter when creating the frame.
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.

Raises:

XgtNameError – If the name provided is not a correct frame name or a frame with this name already exists in the namespace. If the source_key or target_key parameters cannot be found in the schema of data_source or in the schema parameter. If column_mapping is used, the keys should be found there.
XgtIOError – If there are errors in the data being inserted or some data could not be inserted into the frame.
XgtTypeError – If the data source contains data types not supported by this method. If the source or target vertex frames exist with an incompatible key type.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Returns:

Frame to the collection of edges.

Return type:

EdgeFrame

create_namespace(name: str, frame_labels: Mapping[str, Sequence[str]] | None = None, row_label_universe: Iterable[str] | None = None, attempts: int = 1) → None¶

Create a new empty namespace on the server.

Parameters:

name (str) – The name of the namespace to create.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are “create”, “read”, “update”, and “delete”. By default, no labels are required.
row_label_universe (Iterable of strs) – NOT yet supported. An iterable of all possible labels to be used for rows inside this namespace. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
attempts (int) – Number of times to attempt the creation of the namespace. It will be retried if it fails due to transactional conflicts.

Raises:

XgtNameError – If the name provided does not follow rules for namespace names. A namespace name cannot contain “__”, which is used as a separator between namespace and name in fully qualified frame names. If a namespace with this name already exists.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> labels = { 'create' : ['label1', 'label2'],
...            'read' : ['label1'],
...            'update' : ['label1'],
...            'delete' : ['label1', 'label2', 'label3'] }
>>> row_label_universe = [ 'label1', 'label4' ]
>>> conn.create_namespace('career', labels, row_label_universe)

create_table_frame(name: str, schema: list[list], frame_labels: Mapping[str, Sequence[str]] | None = None, row_label_universe: Sequence | None = None, attempts: int = 1) → TableFrame¶

Create a new TableFrame in the server.

A TableFrame object represents a table held on the xGT server and can be used to retrieve information about it. The TableFrame schema describes the names and data types of table properties.

Parameters:

name (str) – Name of table. Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
schema (list of lists) – List of lists associating property names with xGT data types.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterable of all possible labels to be used for rows inside this table frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
attempts (int) – Number of times to attempt the creation of the TableFrame. It will be retried if it fails due to transactional conflicts.

Returns:

Frame to the table.

Return type:

TableFrame

Raises:

XgtNameError – If the name provided is not a correct frame name or a frame with this name already exists in the namespace.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> conn.create_table_frame(
...   name = 'Table1',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]],
...   frame_labels = { 'create' : ['label1'],
...                    'delete' : ['label1', 'label2'] })

create_table_frame_from_data(data_source: str | Iter[str] | pandas.DataFrame | pyarrow.Table, name: str, schema: List[List] | None = None, header_mode: str = 'none', delimiter: str = ',', column_mapping: Map[str, str | int] | None = None, frame_labels: Seq[str] | None = None, row_label_universe: Seq | None = None, row_labels: Seq[str] | None = None, row_label_columns: Seq[str] | None = None, suppress_errors: bool = False, on_duplicate_keys: str = 'error') → TableFrame¶

Create a new TableFrame in the server based on the data source. (Beta)

The schema of the frame will be automatically inferred from the data passed in as data_source and the data will be inserted into the frame.

Parameters:

data_source (str, list of str, pyarrow Table, pandas DataFrame) – The data source from which to create a frame. If a string or list of strings, each entry must be a file path possibly with wildcards. For the file path, the same protocols are supported as load(). Refer to load().
name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
schema (list of lists) –
List of lists associating property names with xGT data types. Each row in the TableFrame will have these properties.

Optional. Default is None. If None, the schema is inferred from data_source.
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.
Optional. Default=HeaderMode.NONE. Only applies to CSV files.
delimiter (str) – 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 frame’s 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.

Optional. Default is None.

Added in version 1.15.0.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterable of all possible labels to be used for rows inside this edge frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
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.
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.

Raises:

XgtNameError – If the name provided is not a correct frame name or a frame with this name already exists in the namespace.
XgtIOError – If there are errors in the data being inserted or some data could not be inserted into the frame.
XgtTypeError – If the data source contains data types not supported by this method.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Returns:

Frame containing the data passed in.

Return type:

TableFrame

create_vertex_frame(name: str, schema: list[list], key: str, frame_labels: Mapping[str, Sequence[str]] | None = None, row_label_universe: Sequence | None = None, attempts: int = 1) → VertexFrame¶

Create a new VertexFrame in the server.

A VertexFrame represents a grouping or collection of vertices held on the xGT server, all sharing the same property names and types. This function creates a new frame of vertices on the xGT server and returns a VertexFrame representing it.

Parameters:

name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
schema (list of lists) – List of lists associating property names with xGT data types. Each vertex in the VertexFrame will have these properties.
key (str) – The property name used to uniquely identify vertices in the graph. This is the name of one of the properties from the schema and must be unique for each vertex in the frame.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterable of all possible labels to be used for rows inside this vertex frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
attempts (int) – Number of times to attempt the creation of the VertexFrame. It will be retried if it fails due to transactional conflicts.

Returns:

Frame to the collection of vertices.

Return type:

VertexFrame

Raises:

XgtNameError – If the name provided is not a correct frame name. If the key is not in the schema. If a frame with this name already exists in the namespace.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> people = conn.create_vertex_frame(
...            name = 'People',
...            schema = [['id', xgt.INT],
...                      ['name', xgt.TEXT]],
...            key = 'id',
...            frame_labels = { 'create' : ['label1'],
...                             'delete' : ['label1', 'label2'] })

create_vertex_frame_from_data(data_source: str | Iter[str] | pandas.DataFrame | pyarrow.Table, name: str, key: str, schema: List[List] | None = None, header_mode: str = 'none', delimiter: str = ',', column_mapping: Map[str, str | int] | None = None, frame_labels: Seq[str] | None = None, row_label_universe: Seq | None = None, row_labels: Seq[str] | None = None, row_label_columns: Seq[str] | None = None, suppress_errors: bool = False, on_duplicate_keys: str = 'error') → VertexFrame¶

Create a new VertexFrame in the server based on the data source. (Beta)

The schema of the frame will be automatically inferred from the data passed in as data_source and the data will be inserted into the frame.

Parameters:

data_source (str, list of str, pyarrow Table, pandas DataFrame) – The data source from which to create a frame. If a string or list of strings, each entry must be a file path possibly with wildcards. For the file path, the same protocols are supported as load(). Refer to load().
name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.
key (str) – The property name used to uniquely identify vertices in the graph. This is the name of one of the properties from the schema and must be unique for each vertex in the frame. Note that the schema will be automatically inferred from the data_source and may be affected by the header_mode and column_mapping parameters.
schema (list of lists) –
List of lists associating property names with xGT data types. Each vertex in the VertexFrame will have these properties.

Optional. Default is None. If None, the schema is inferred from data_source.
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.
Optional. Default=HeaderMode.NONE. Only applies to CSV files.
delimiter (str) – 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 frame’s 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.

Optional. Default is None.

Added in version 1.15.0.
frame_labels (dictionary) – A dictionary mapping a string to a list of strings. The key represents the permission type. The value represents the labels required for this permission. Permission types are create, read, update, and delete. By default, no labels are required.
row_label_universe (Iterable of strs) – An iterbale of all possible labels to be used for rows inside this edge frame. A maximum of 128 labels are supported for rows in each frame. By default, no row labels are required.
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.
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.
on_duplicate_keys ({‘error’, ‘skip’, 'skip_same'}, default 'error') –
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.13.0.

Raises:

XgtNameError – If the name provided is not a correct frame name or a frame with this name already exists in the namespace. If the key parameter cannot be found in the schema of data_source or in the schema parameter. If column_mapping is used, the key should be found there.
XgtIOError – If there are errors in the data being inserted or some data could not be inserted into the frame.
XgtTypeError – If the data source contains data types not supported by this method.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Returns:

Frame to the collection of vertices.

Return type:

VertexFrame

drop_frame(frame: str | VertexFrame | EdgeFrame | TableFrame, attempts: int = 10) → bool¶

Drop a VertexFrame, EdgeFrame, or TableFrame.

Parameters:

frame (str, VertexFrame, EdgeFrame, or TableFrame) – A frame or the name of a frame to drop on the xGT server. The namespace is optional for a frame name, and if not given it will use the default namespace.
attempts (int) – Number of times to attempt the deletion of the frame. It will be retried if it fails due to transactional conflicts.

Returns:

True if frame was found and dropped and False if frame was not found.

Return type:

bool

Raises:

XgtFrameDependencyError – If another frame depends on this frame. The dependent frame should be dropped first.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

drop_frames(frames: Iterable[str], attempts: int = 10) → bool¶

Drop a VertexFrame, EdgeFrame, or TableFrame.

Added in version 1.14.0.

Parameters:

frames (list of str, VertexFrame, EdgeFrame, or TableFrame) – A potentially mixed list of frames or names of frames to drop on the xGT server. The namespace is optional for frame names, and if not given it will use the default namespace.
attempts (int) – Number of times to attempt the deletion of the frames. It will be retried if it fails due to transactional conflicts.

Returns:

True if frame was found and dropped and False if frame was not found.

Return type:

bool

Raises:

XgtFrameDependencyError – If another frame depends on this frame. The dependent frame should be dropped first.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

drop_namespace(namespace: str, force_drop: bool = False, attempts: int = 10) → bool¶

Drop a namespace from the server.

Parameters:

name (str) – The name of the namespace to drop.
force_drop (bool) – If True, the namespace will be dropped even if it is not empty along with any frames it contains. If False, a non-empty namespace will not be dropped.
attempts (int) – Number of times to attempt the deletion of the namespace. It will be retried if it fails due to transactional conflicts.

Returns:

True if the namespace was found and dropped. False if the namespace was not found.

Return type:

bool

Raises:

XgtFrameDependencyError – If the namespace is not empty and force_drop is False.
XgtNameError – If the name provided does not follow rules for namespace names. A namespace name cannot contain “__”, which is used as a separator between namespace and name in frame names.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> labels = { 'create' : ['label1', 'label2'],
...            'read'   : ['label1'],
...            'update' : ['label1'],
...            'delete' : ['label1', 'label2', 'label3'] }
>>> conn.create_namespace('career', labels)
>>> conn.drop_namespace('career')
>>> conn.drop_namespace('career', force_drop = True)

property free_user_memory_size: float¶

The amount of free memory available for user data on the xGT server. In gibibytes.

Type:: float

get_config(keys: Sequence[str] | None = None) → Mapping¶

Get one or more configuration values from the server. These values may not be the same as those set by the user.

Parameters:

keys (list of str or None) – If a list, the list of config keys to retrieve. If None, all config values are returned.

Returns:

Dictionary of key-value pairs representing configuration information from the server.

Return type:

dict

Raises:

XgtNameError – If any keys requested are not valid.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> conn = xgt.Connection()
>>> conf1 = conn.get_config()
>>> conf2 = conn.get_config(["key1", "key2", ... ])

get_default_namespace() → str¶

Get the name of the default namespace.

Returns:: String value of the default namespace.
Return type:: str

Examples

>>> conn = xgt.Connection()
>>> defaultNamespace = conn.get_default_namespace()

get_frame(name: str) → EdgeFrame | VertexFrame | TableFrame¶

Get a frame object that allows interaction with a frame present in the xGT server.

Added in version 1.14.0.

Parameters:

name (str) – Must be a valid frame name. The namespace is optional, and if not given it will use the default namespace.

Returns:

Frame representing the corresponding type.

Return type:

EdgeFrame, VertexFrame or TableFrame

Raises:

XgtNameError – If the frame requested does not exist or is not visible to the user.
XgtTransactionError – If a conflict with another transaction occurs.

get_frame_labels(frame: str) → Mapping[str, Sequence[str]]¶

Retrieve the current security labels (CRUD) on a specific frame.

Parameters:

frame (str, VertexFrame, EdgeFrame, or TableFrame) – A frame or the name of a frame from which to retrieve the security labels.

Returns:

A dictionary in the form:

{
  "create" : ['label1', ... ],
  "read" : ['label1', ... ],
  "update" : ['label1', ... ],
  "delete" : ['label1', ... ],
}

Return type:

dict

Raises:

XgtNameError – If the name provided is not a correct frame name.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Get a list of Frame objects that correspond to each frame in the xGT server. Only frames that the calling user has permission to read are returned.

A specific frame object allows for interaction with a frame present in the xGT server.

Added in version 1.14.0.

Parameters:

names (list of str or None) – If a list, the list of names of frames to retrieve. Each name must be a valid frame name. The namespace is optional and will use the default if none is given. If None and the parameter namespace is None, all frames are returned.
namespace (str or None) – Returns all frames in this namespace. At most one of names and namespace can be a value other than None.
frame_type (str) – Selects the frame type returned: Edge, Vertex, or Table. Must be one of ‘edge’, ‘vertex’, ‘table’, or None. If None is selected it will return all types. Optional. Default=None.

Returns:

EdgeFrame, TableFrame, VertexFrame objects representing the frames present in the server.

Return type:

list

Raises:

XgtNameError – If a frame name requested does not exist or is not visible to the user. If a frame or namespace name does not follow naming rules.
XgtTransactionError – If a conflict with another transaction occurs.

get_jobs(jobids: Sequence[int] | None = None) → list[Job]¶

Get a list of Job objects, each representing the state of the job on the server at the point in time of the invocation of this function.

Parameters:: jobids (list of ints) – A list of job IDs for which to return Job objects. By default, all jobs are returned.
Returns:: A list of Job objects, each representing the state of a job in the server.
Return type:: list

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges and run queries ...
>>> all_jobs = conn.get_jobs()
>>> for j in all_jobs:
>>> ... print j
id:6, status:completed
id:7, status:completed
id:8, status:running

get_metrics_status() → str¶

Check whether the metrics cache is on and finished with updates. A status of metrics_complete is only valid for as long as no vertex or edge frames are modified or created.

Returns:: The status of metrics collection: metrics_completed, metrics_running, or metrics_off.
Return type:: str

Examples

>>> conn = xgt.Connection()
>>> conn.get_metrics_status()

get_namespaces() → list[str]¶

Get a list of namespaces present in the xGT server.

Returns:: Names of namespaces present in the server.
Return type:: list

Examples

>>> conn = xgt.Connection()
>>> namespaces = conn.get_namespaces()
>>> for ns in namespaces:
>>> ... conn.drop_namespace(ns)

Get back an inferred frame schema from the data source passed in. (Beta)

Note that this is not the schema of an existing frame, but can be used to create a new frame. The data schema can contain the following types: string, integer, floating point, double, boolean, date, time, and datetime.

Parameters:

data_source (str, list of str, pyarrow Table, pandas DataFrame) – The data source from which to create a frame. If a string or list of strings, each entry must be a file path possibly with wildcards. For the file path, the same protocols are supported as load(). Refer to load().
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.
Optional. Default=HeaderMode.NONE. Only applies to CSV files.
delimiter (str) – Delimiter for CSV data. Only applies to CSV files.
column_mapping (dictionary) –
Maps the frame column names to input columns for the ingest. The key of each element is frame’s column name. The value is either the name of the input column (from the file header, pandas, or arrow table names) 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.

Optional. Default is None.

Added in version 1.15.0.

Raises:

XgtIOError – If there are errors in reading the data.
XgtTypeError – If the data source contains data types not supported for automatic schema inference.

Returns:

Describes a schema for an xGT frame, with property names and types.

Return type:

list of lists

get_user_labels() → Sequence[str]¶

Retrieve the current security labels of the user.

Returns:: A list of strings corresponding to the security labels of the user.
Return type:: list of str

property max_user_memory_size: float¶

The maximum amount of memory available for user data on the xGT server. In gibibytes.

Type:: float

run_job(query: str, parameters: Mapping | None = None, optlevel: int = 4, description: str | None = None, timeout: int = 0, record_history: bool = True)¶

Run a TQL query as a job. This function blocks until the job stops running.

Parameters:

query (str) – One TQL query string.
parameters (dict) – Optional dictionary to contain Cypher parameters.
optlevel (int) –
Sets the level of query optimization. The valid values are:
- 0: No optimization.
- 1: General optimization.
- 2: WHERE-clause optimization.
- 3: Degree-cycle optimization.
- 4: Query order optimization.
description (str) – Optional description of the job. If description is None, this will default to the query text.
timeout (int) – Maximum number of seconds that the query should take before being automatically canceled. A value less than or equal to zero means no limit on the query time.
record_history (bool) – If true, records the history of the job.

Returns:

A Job object for the query.

Return type:

Job

Raises:

XgtSyntaxError – If there is a syntax error in the TQL query.
XgtNameError – If there is a name error in the TQL query, such as specifying a frame that does not exist.
XgtTypeError – If there is a type error in the TQL query, such as comparing a schema property to the wrong data type.
XgtValueError – If there is a value error in the TQL query.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges ...
>>> job = conn.run_job('MATCH (a:Employees) RETURN a.person_id INTO Results1', timeout=200)
>>> print(job)
id:20, status:completed

>>> conn.run_job('MATCH (a) RETURN a.id INTO Results1')
...
xgt.common.XgtValueError: Invalid column name: 'id'

schedule_job(query: str, parameters: Mapping | None = None, optlevel: int = 4, description: str | None = None, record_history: bool = True) → Job¶

Schedule a TQL query as a job. This function returns immediately after scheduling the job.

Parameters:

query (str) – One TQL query string.
parameters (dict) – Optional dictionary to contain query parameters.
optlevel (int) –
Sets the level of query optimization. The valid values are:
- 0: No optimization.
- 1: General optimization.
- 2: WHERE-clause optimization.
- 3: Degree-cycle optimization.
- 4: Query order optimization.
description (str) – Optional description of the job. If description is None, this will default to the query text.
record_history (bool) – If true, records the history of the job.

Returns:

A Job object representing the job that has been scheduled.

Return type:

Job

Raises:

XgtSyntaxError – If there is a syntax error in the TQL query.
XgtNameError – If there is a name error in the TQL query, such as specifying a frame that does not exist.
XgtTypeError – If there is a type error in the TQL query, such as comparing a schema property to the wrong data type.
XgtValueError – If there is a value error in the TQL query.
XgtSecurityError – If the user does not have required permissions for this action.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges ...
>>> query = 'MATCH (a:Employees) RETURN a.person_id INTO Results1'
>>> job = conn.schedule_job(query)
>>> print(job)
id:25, status:scheduled

property server_version: str¶

The current server version.

Type:: str

set_config(config_dict: Mapping) → None¶

Set key-value pairs in the server configuration.

Parameters:

config_dict (dict) – Dictionary containing config key-values.

Raises:

XgtNameError – If any keys provided are not valid.
XgtTypeError – If any config values provided are of the wrong type.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

Examples

>>> conn = xgt.Connection()
>>> conn.set_config({"mykey" : 14, "another_key" : "This string"})

set_default_namespace(default_namespace: str) → None¶

Set the default namespace for this user session.

Parameters:

default_namespace (str) – String value to be the default namespace. If set to None, this will disable the default namespace.

Raises:

XgtNameError – If the provided string is not valid.
XgtSecurityError – If the user does not have required permissions for this action.

Examples

>>> conn = xgt.Connection()
>>> conn.set_default_namespace("mynamespace")

property userid: str¶

The identity of the connected user.

Type:: str

wait_for_job(job: Job | int, timeout: float = 0) → Job¶

Wait for a job. This function blocks until the job stops running.

Parameters:

job (Job, int) – A Job object or an integer job id.
timeout (int) – Number of seconds each job is allowed to execute before being automatically cancelled. A value less than or equal to zero means no limit on the wait time.

Returns:

A Job object representing the state of the job on the server.

Return type:

Job

Raises:

XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.
XgtError – If one or more query jobs failed.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges ...
>>> qr1 = 'MATCH (a:Employees) RETURN a.person_id INTO Results0'
>>> jb1 = conn.schedule_job(qr1)
>>> qr2 = 'MATCH (b:Companies) RETURN b.company_id INTO Results1'
>>> jb2 = conn.schedule_job(qr2)
>>> jb1 = conn.wait_for_job(jb1)
>>> print(jb1)
id:31, status:completed
>>> jb2 = conn.wait_for_job(jb2)
>>> print(jb2)
id:32, status:completed

wait_for_metrics(timeout: float = 0) → bool¶

Wait until the metrics cache is finished with updates. This function blocks until there are no more metrics to update or until metrics collection is turned off through the config or until the optional timeout is reached.

Parameters:: timeout (float) – Max number of seconds the function will block. A value less than or equal to zero means no limit on the block time.
Returns:: Returns True if metrics collection was finished when the function returned. Returns False if metrics collection is not finished (if either metrics collection didn’t complete before the timeout or if metrics cache is off.)
Return type:: bool

Examples

>>> conn = xgt.Connection()
>>> finished = conn.wait_for_metrics()