xgt.Connection¶

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

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

Parameters:

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. flags (dict) – Dictionary containing flags. Possible flags are: aws_access_key_id : str Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string. aws_secret_access_key : str Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string. ssl : boolean If true use ssl authentication for secure server channels. The default is False. ssl_root_dir : str Path to the root folder for ssl certificates and private keys. Defaults to the user’s home directory. ssl_server_cn : str Common name on the certificate of the server to connect to. The default is the hostname.

host (str) – IP address of the computer where the server is running.
port (int) – Port where the server is listening on for RPC calls.
flags (dict) –
Dictionary containing flags. Possible flags are:

aws_access_key_id : str

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

aws_secret_access_key : str

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

ssl : boolean

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

ssl_root_dir : str

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

ssl_server_cn : str

Common name on the certificate of the server to connect to. The default is the hostname.

__init__(host='127.0.0.1', port=4367, flags=None)¶: Initialize self. See help(type(self)) for accurate signature.

Methods

`__init__`([host, port, flags])	Initialize self.
`call`(request, rpc_function)
`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_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)	Drop a VertexFrame, EdgeFrame, or TableFrame.
`get_edge_frame`(name)	Get an EdgeFrame object that allows interaction with a collection of edges.
`get_edge_frames`([names, graph])	Get a list of EdgeFrame objects present 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_table_frame`(name)	Get a TableFrame object that allows interaction with a table present in the xGT server.
`get_table_frames`([names])	Get a list of TableFrame objects present in the server.
`get_vertex_frame`(name)	Get a VertexFrame object that allows interaction with a collection of vertices.
`get_vertex_frames`([names])	Get a list of VertexFrame objects present in the xGT server.
`run_job`(query[, optlevel, timeout])	Run a TQL query as a job.
`schedule_job`(query[, optlevel])	Schedule a TQL query as a job.
`set_optimization_level`([optlevel])	Set the optimization level for TQL queries.
`wait_for_job`(job[, timeout])	Wait for a job.

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.

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

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges and run queries ...
>>> print(conn.cancel_job(18))
id:18, status:completed
>>> 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)¶

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) – Name of edge frame. 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.
Returns:	Frame to the collection of edges.
Return type:	EdgeFrame

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> conn.create_vertex_frame(
      name = 'Person',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]],
...   key = 'id')
>>> conn.create_vertex_frame(
      name = 'Company',
...   schema = [['id', xgt.INT],
...             ['size', xgt.TEXT],
...             ['name', xgt.TEXT]],
...   key = 'id')
>>> conn.create_edge_frame(
      name = 'WorksFor',
...   schema = [['srcid', xgt.INT],
...             ['role', xgt.TEXT],
...             ['trgid', xgt.INT]],
...   source = 'Person',
...   target = 'Company',
...   source_key = 'srcid',
...   target_key = 'trgid')

create_table_frame(name, schema)¶

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. schema (list of pairs) – List of pairs associating property names with xGT data types.
Returns:	Frame to the table.
Return type:	TableFrame

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> conn.create_table_frame(
      name = 'tab1',
...   schema = [['id', xgt.INT],
...             ['name', xgt.TEXT]])

create_vertex_frame(name, schema, key)¶

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) – Name of vertex frame. 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.
Returns:	Frame to the collection of vertices.
Return type:	VertexFrame

Examples

>>> import xgt
>>> conn = xgt.Connection()
>>> pers_vtx = conn.create_vertex_frame(
                 name = 'Person',
...              schema = [['id', xgt.INT],
...                        ['name', xgt.TEXT]],
...              key = 'id')

drop_frame(frame)¶

Drop a VertexFrame, EdgeFrame, or TableFrame.

Parameters:	frame (str, VertexFrame, EdgeFrame, or TableFrame) – A frame or the name of frame to drop on the xGT server.
Returns:	True if frame was found and dropped and False if frame was not found.
Return type:	bool

free_user_memory_size¶

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

Returns:	Currently available user memory, in bytes.
Return type:	int

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. Edge edge in an EdgeFrame shares the same properties, described in EdgeFrame.schema.

Parameters:	name (str) – EdgeFrame name.
Returns:	Frame to the collection of edges.
Return type:	EdgeFrame

Examples

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

get_edge_frames(names=None, graph=None)¶

Get a list of EdgeFrame objects present in the xGT server.

Parameters:	names (list of strings or None) – If a list, the list of names of edge frames to retrieve. If None, all edge frames are returned.
Returns:	EdgeFrame objects present in the server.
Return type:	list

Examples

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

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_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 name.
Returns:	Frame to the table.
Return type:	TableFrame

Examples

>>> conn = xgt.Connection()
>>> ... create graph and run queries ...
>>> t = conn.get_table_frame('Employee_table')
>>> print(str(t))
{
  'name': 'Employee_table',
  'schema': [
    ['PersonID', 'int'],
    ['Name', 'text'],
    ['PostalCode', 'int']]
}
>>> qr1 = 'MATCH (a:Employee) RETURN a.PersonID INTO Result1'
>>> conn.run_job(qr1)
>>> result1_table = conn.get_table_frame('Result1')
>>> num_results = result1_table.num_rows
>>> result1_data = result1_table.get_data_pandas()

get_table_frames(names=None)¶

Get a list of TableFrame objects present in the server.

Parameters:	names (list of strings or None) – If a list, the list of names of tables frames to retrieve. If None, all table frames are returned.
Returns:	TableFrame objects representing tables present in the server.
Return type:	list

Examples

>>> conn = xgt.Connection()
>>> ... create graph
>>> qr1 = 'MATCH (a:Employee) RETURN a.PersonID INTO Result1'
>>> conn.run_job(qr1)
>>> table_frames = conn.get_table_frames()
>>> print [f.name for f in table_frames]
['Employee_table', 'ReportsTo_table', 'Result1']
>>> result1_data = table_frames[2].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) – VertexFrame name.
Returns:	Frame to the collection of vertices.
Return type:	VertexFrame

Examples

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

get_vertex_frames(names=None)¶

Get a list of VertexFrame objects present in the xGT server.

Parameters:	names (list of strings or None) – If a list, the list of names of vertex frames to retrieve. If None, all vertex frames are returned.
Returns:	VertexFrame objects present in the server.
Return type:	list

Examples

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

max_user_memory_size¶

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

Returns:	Maximum available user memory, in bytes.
Return type:	int

run_job(query, optlevel=None, timeout=None)¶

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

Parameters:	queries (str) – One TQL query string. optlevel (int) – The optimization level values are: 0: No optimization. 1: General optimization. 2: WHERE-clause optimization. Optional. Default=None, which implies a value of ‘2’. timeout (int) – Maximum number of seconds that the query should take before being automatically canceled. Optional. Default=None where an infinite value is assumed.
Returns:	A Job object for the query.
Return type:	Job
Raises:	`XgtError` – If the query is not a string (str) or the query text is larger than 209,000 characters.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges ...
>>> job = conn.run_job('MATCH (a:Employee) RETURN a.PersonID INTO Result1')
>>> print(job)
id:20, status:completed

>>> conn.run_job('MATCH (a) RETURN a.id INTO Result1')
...
xgt.common.XgtError: Failed jobs:
id: 22
error:
VertexFrameManager: No object registered with this ObjectID 18446744073709551615

schedule_job(query, optlevel=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) – The optimization level values are: 0: No optimization. 1: General optimization. 2: WHERE-clause optimization.
Returns:	A Job object representing the job that has been scheduled.
Return type:	Job
Raises:	`XgtError` – If the query is not a string (str) or the query text is larger than 209,000 characters.

Examples

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

server_version¶

Obtains the current product version from the server.

Returns:	Version number.
Return type:	str

set_optimization_level(optlevel=2)¶

Set the optimization level for TQL queries.

Parameters:

Parameters:	optlevel (int) – The optimization level values are: 0: No optimization. 1: General optimization. 2: WHERE-clause optimization. Optional. Default is 2’.

optlevel (int) –

The optimization level values are:

0: No optimization.
1: General optimization.
2: WHERE-clause optimization.

Optional. Default is 2’.

wait_for_job(job, timeout=None)¶

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. Optional. Default=None (no timeout).
Returns:	A Job object representing the state of the job on the server.
Return type:	Job
Raises:	`XgtError` – If the query is not a string (str) or the query text is larger than 209,000 characters. If one or more query jobs failed.

Examples

>>> conn = xgt.Connection()
>>> ... create vertices and edges ...
>>> qr1 = 'MATCH (a:Employee) RETURN a.PersonID INTO Result1'
>>> jb1 = conn.schedule_job(qr1)
>>> qr2 = 'MATCH (b:Employee) RETURN b.PersonID INTO Result2'
>>> 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

xgt.Connection¶

Table of Contents

Search