7.2.1. xgt.Connection¶

class xgt.Connection(host='127.0.0.1', port=4367, flags=None, userid='', credentials='')¶

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.
userid (str) – The user name to authenticate as.
credentials (str) – Credentials used to authenticate.
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.

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
Common name on the certificate of the server to connect to. The default is the hostname.

Methods

`__init__`([host, port, flags, userid, …])	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_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_vertex_frame`(name, schema, key[, …])	Create a new VertexFrame in the server.
`drop_frame`(frame[, 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_edge_frame`(name)	Get an EdgeFrame object that allows interaction with a collection of edges.
`get_edge_frames`([names, namespace])	Get a list of EdgeFrame objects corresponding to each edge frame in the xGT server.
`get_frame_labels`(frame)	Retrieve the current security labels (CRUD) on a specific frame.
`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_table_frame`(name)	Get a TableFrame object that allows interaction with a table present in the xGT server.
`get_table_frames`([names, namespace])	Get a list of TableFrame objects that correspond to each table frame in the xGT server.
`get_vertex_frame`(name)	Get a VertexFrame object that allows interaction with a collection of vertices.
`get_vertex_frames`([names, namespace])	Get a list of VertexFrame objects corresponding to each vertex frame in the xGT server.
`run_job`(query[, optlevel, description, …])	Run a TQL query as a job.
`schedule_job`(query[, optlevel, description, …])	Schedule a TQL query as a job.
`set_config`(config_dict)	Set key-value pairs in the server configuration.
`set_optimization_level`([optlevel])	Set the optimization level for TQL queries.
`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`	Returns the amount of free memory available for user data on the xGT server.
`max_user_memory_size`	Returns the maximum amount of memory available for user data on the xGT server.
`server_version`	Obtains the current product version from the server.

__init__(host='127.0.0.1', port=4367, flags=None, userid='', credentials='')¶: Constructor for Connection. Called when Connection is created.

cancel_job(job)¶

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, schema, source, target, source_key, target_key, frame_labels=None, security_labels=None, row_label_universe=None, attempts=1)¶

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) – Fully qualified frame name. It must include the namespace in which the frame will be created.
schema (list of pairs) – List of pairs 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.
security_labels (dictionary) – same as frame_labels (DEPRECATED)
row_label_universe (array) – An array 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. (since version 1.5.0)
attempts (int) – Number of times to attempt the creation of the EdgeFrame. It will be retried if it fails due to transactional conflicts. (since version 1.4.1)

Returns

Frame to the collection of edges.

Return type

EdgeFrame

Raises

XgtNameError – If the name provided is not a correct fully qualified 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 = 'career__People',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]],
...   key = 'id')
>>> conn.create_vertex_frame(
      name = 'career__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 = 'career__WorksFor',
...   schema = [['srcid', xgt.INT],
...             ['role', xgt.TEXT],
...             ['trgid', xgt.INT]],
...   source = 'career__People',
...   target = 'career__Companies',
...   source_key = 'srcid',
...   target_key = 'trgid',
...   frame_labels = { 'create' : ['label1'],
...                    'update' : ['label3'],
...                    'delete' : ['label1', 'label2'] })

create_namespace(name, frame_labels=None, security_labels=None, row_label_universe=None, attempts=1)¶

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.
security_labels (dictionary) – same as frame_labels (DEPRECATED)
row_label_universe (array) – NOT yet supported. An array 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. (since version 1.4.1)

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, schema, frame_labels=None, security_labels=None, row_label_universe=None, attempts=1)¶

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. Fully qualified frame name. It must include the namespace in which the frame will be created.
schema (list of pairs) – List of pairs 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.
security_labels (dictionary) – same as frame_labels (DEPRECATED)
row_label_universe (array) – An array 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. (since version 1.5.0)
attempts (int) – Number of times to attempt the creation of the TableFrame. It will be retried if it fails due to transactional conflicts. (since version 1.4.1)

Returns

Frame to the table.

Return type

TableFrame

Raises

XgtNameError – If the name provided is not a correct fully qualified 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 = 'career__Table1',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]],
...   frame_labels = { 'create' : ['label1'],
...                    'delete' : ['label1', 'label2'] })

create_vertex_frame(name, schema, key, frame_labels=None, security_labels=None, row_label_universe=None, attempts=1)¶

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) – Fully qualified frame name. It must include the namespace in which the frame will be created.
schema (list of pairs) – List of pairs 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.
security_labels (dictionary) – same as frame_labels (DEPRECATED)
row_label_universe (array) – An array 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. (since version 1.5.0)
attempts (int) – Number of times to attempt the creation of the VertexFrame. It will be retried if it fails due to transactional conflicts. (since version 1.4.1)

Returns

Frame to the collection of vertices.

Return type

VertexFrame

Raises

XgtNameError – If the name provided is not a correct fully qualified 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 = 'career__People',
...            schema = [['id', xgt.INT],
...                      ['name', xgt.TEXT]],
...            key = 'id',
...            frame_labels = { 'create' : ['label1'],
...                             'delete' : ['label1', 'label2'] })

drop_frame(frame, attempts=10)¶

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 name must be a fully qualifed name that includes the namespace in which the frame exists.
attempts (int) – Number of times to attempt the deletion of the frame. It will be retried if it fails due to transactional conflicts. (since version 1.4.1)

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 depending frame should be dropped first.
XgtNameError – If the name provided is not a correct fully qualified name.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

drop_namespace(namespace, force_drop=False, attempts=10)¶

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. (since version 1.4.1)

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 fully qualified 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¶

Returns the amount of free memory available for user data on the xGT server.

Returns: Currently available user memory, in gibibytes.
Return type: float

get_config(keys=None)¶

Get one or more configuration values from the server.

Parameters

keys (list of strings 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_edge_frame(name)¶

Get an EdgeFrame object that allows interaction with a collection of edges.

An EdgeFrame represents a collection of edges held on the xGT server and can be used to retrieve information about them. EdgeFrame.get_data_pandas() and EdgeFrame.get_data() are used to retrieve member edges. Each edge in an EdgeFrame shares the same properties, described in EdgeFrame.schema.

Parameters

name (str) – EdgeFrame name. The name must be a fully qualifed name that includes the namespace in which the frame exists.

Returns

Frame to the collection of edges.

Return type

EdgeFrame

Raises

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

Examples

>>> conn = xgt.Connection()
>>> ... create graph and run queries ...
>>> e = conn.get_edge_frame('career__WorksFor')
>>> print(str(e))
{
  'name': 'career__WorksFor',
  'source': 'career__People',
  'target': 'career__Companies',
  'schema': [
    ['srcid', 'int'],
    ['trgid', 'int']],
  'source_key' : 'srcid',
  'target_key' : 'trgid'
}
>>> edges = e.get_data_pandas()

get_edge_frames(names=None, namespace=None)¶

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

An EdgeFrame represents a collection of edges held on the xGT server and can be used to retrieve information about them. EdgeFrame.get_data_pandas() and EdgeFrame.get_data() are used to retrieve member edges. Each edge in an EdgeFrame shares the same properties, described in EdgeFrame.schema.

Parameters

names (list of strings or None) – If a list, the list of names of edge frames to retrieve. Each name must be a fully qualifed name that includes the namespace in which the frame exists. If None and the parameter namespace is None, all edge frames are returned.
namespace (string or None) – Returns all edge frames in this namespace. At most one of names and namespace can be a value other than None.

Returns

EdgeFrame objects corresponding to edge frames present in the server.

Return type

list

Raises

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

Examples

>>> conn = xgt.Connection()
>>> print [f.name for f in conn.get_edge_frames()]
['career__RelatedTo', 'career__WorksFor']

get_frame_labels(frame)¶

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 fully qualified name.
XgtSecurityError – If the user does not have required permissions for this action.
XgtTransactionError – If a conflict with another transaction occurs.

get_jobs(jobids=None)¶

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()¶

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()¶

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_table_frame(name)¶

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

A TableFrame object allows for interaction with a table present in the xGT server. For example, a table may be created by a MATCH query and may contain query results. It may also be explicitly created with Connection.create_table_frame().

Parameters

name (str) – Table frame name. The name must be a fully qualifed name that includes the namespace in which the frame exists.

Returns

Frame to the table.

Return type

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.

Examples

>>> conn = xgt.Connection()
>>> ... create graph in the namespace career and run queries ...
>>> t = conn.get_table_frame('career__EmployeeData')
>>> print(str(t))
{
  'name': 'career__EmployeeData',
  'schema': [
    ['person_id', 'int'],
    ['name', 'text'],
    ['postal_code', 'int']]
}
>>> qr1 = 'MATCH (a:career__EmployeeData) RETURN a.person_id INTO career__Results1'
>>> conn.run_job(qr1)
>>> results = conn.get_table_frame('career__Results1')
>>> num_results = results.num_rows
>>> results_data = results.get_data_pandas()

get_table_frames(names=None, namespace=None)¶

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

A TableFrame object allows for interaction with a table present in the xGT server. For example, a table may be created by a MATCH query and may contain query results. It may also be explicitly created with Connection.create_table_frame().

Parameters

names (list of strings or None) – If a list, the list of names of tables frames to retrieve. Each name must be a fully qualifed name that includes the namespace in which the frame exists. If None and the parameter namespace is None, all table frames are returned.
namespace (string or None) – Returns all table frames in this namespace. At most one of names and namespace can be a value other than None.

Returns

TableFrame objects representing tables present in the server.

Return type

list

Raises

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

Examples

>>> conn = xgt.Connection()
>>> ... create graph in the namespace career
>>> qr1 = 'MATCH (a:career__Employee) RETURN a.PersonID INTO career__Results1'
>>> conn.run_job(qr1)
>>> table_frames = conn.get_table_frames()
>>> print(str([f.name for f in table_frames]))
['career__Results1']
>>> results1_data = conn.get_table_frame('career__Results1').get_data_pandas()

get_vertex_frame(name)¶

Get a VertexFrame object that allows interaction with a collection of vertices.

A VertexFrame represents a collection of vertices held on the xGT server and can be used to retrieve information about them. VertexFrame.get_data_pandas() and VertexFrame.get_data() are used to retrieve member vertices. Each vertex in a VertexFrame shares the same properties, described in VertexFrame.schema. Each vertex in a VertexFrame is uniquely identified by the property listed in VertexFrame.key.

Parameters

name (str) – Vertex frame name. The name must be a fully qualifed name that includes the namespace in which the frame exists.

Returns

Frame to the collection of vertices.

Return type

VertexFrame

Raises

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

Examples

>>> conn = xgt.Connection()
>>> v = conn.get_vertex_frame('career__People')
>>> print(str(v))
{
  'name': 'career__People',
  'key': 'id',
  'schema': [
    ['id', 'int'],
    ['name', 'text']],
}
>>> print(str(v.num_vertices))
101
>>> vertices = v.get_data_pandas()

get_vertex_frames(names=None, namespace=None)¶

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

A VertexFrame represents a collection of vertices held on the xGT server and can be used to retrieve information about them. VertexFrame.get_data_pandas() and VertexFrame.get_data() are used to retrieve member vertices. Each vertex in a VertexFrame shares the same properties, described in VertexFrame.schema. Each vertex in a VertexFrame is uniquely identified by the property listed in VertexFrame.key.

Parameters

names (list of strings or None) – If a list, the list of names of vertex frames to retrieve. Each name must be a fully qualifed name that includes the namespace in which the frame exists. If None and the parameter namespace is None, all vertex frames are returned.
namespace (string or None) – Returns all vertex frames in this namespace. At most one of names and namespace can be a value other than None.

Returns

VertexFrame objects corresponding to the vertex frames present in the server.

Return type

list

Raises

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

Examples

>>> conn = xgt.Connection()
>>> print [f.name for f in conn.get_vertex_frames()]
['career__Companies', 'career__People']
>>> print [f.num_vertices for f in conn.get_vertex_frames()]
[3, 101]

property max_user_memory_size¶

Returns the maximum amount of memory available for user data on the xGT server.

Returns: Maximum available user memory, in gibibytes.
Return type: float

run_job(query, optlevel=4, description=None, timeout=0, record_history=True, parameters=None)¶

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

Parameters

query (str) – One TQL query string.
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. (since version 1.4.0)
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. (since version 1.4.0)
parameters (dict) – Optional dictionary to contain Cypher parameters. (since version 1.6.0)

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:career__Employees) RETURN a.person_id INTO career__Results1', timeout=200)
>>> print(job)
id:20, status:completed

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

schedule_job(query, optlevel=4, description=None, record_history=True, parameters=None)¶

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

Parameters

query (str) – One TQL query string.
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. (since version 1.4.0)
record_history (bool) – If true, records the history of the job. (since version 1.4.0)
parameters (dict) – Optional dictionary to contain query parameters. (since version 1.6.0)

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:career__Employees) RETURN a.person_id INTO career__Results1'
>>> job = conn.schedule_job(query)
>>> print(job)
id:25, status:scheduled

property server_version¶

Obtains the current product version from the server.

Returns: Version number.
Return type: str

set_config(config_dict)¶

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_optimization_level(optlevel=None)¶

Set the optimization level for TQL queries. (Removed in 1.4.1)

See the documentation for run_job() and schedule_job() for how to pass optimization levels to each job.

wait_for_job(job, timeout=0)¶

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:career__Employees) RETURN a.person_id INTO career__Results0'
>>> jb1 = conn.schedule_job(qr1)
>>> qr2 = 'MATCH (b:career__Companies) RETURN b.company_id INTO career__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=0)¶

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()