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
  • 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_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.

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

Check whether the metrics cache is on and finished with updates.

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.

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.

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 = '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')
>>> 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')
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 = 'Table1',
...   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()
>>> people = conn.create_vertex_frame(
...            name = 'People',
...            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

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 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': 'People',
  'target': 'Companies',
  '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.

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

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_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_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('EmployeeData')
>>> print(str(t))
{
  'name': 'EmployeeData',
  'schema': [
    ['person_id', 'int'],
    ['name', 'text'],
    ['postal_code', 'int']]
}
>>> qr1 = 'MATCH (a:EmployeeData) RETURN a.person_id INTO Results1'
>>> conn.run_job(qr1)
>>> results = conn.get_table_frame('Results1')
>>> num_results = results.num_rows
>>> results_data = results.get_data_pandas()
get_table_frames(names=None)

Get a list of TableFrame objects present in the 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

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 Results1'
>>> conn.run_job(qr1)
>>> table_frames = conn.get_table_frames()
>>> print [f.name for f in table_frames]
['Results1']
>>> results1_data = conn.get_table_frame('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) – VertexFrame name.

Returns

Frame to the collection of vertices.

Return type

VertexFrame

Examples

>>> conn = xgt.Connection()
>>> v = conn.get_vertex_frame('People')
>>> print(str(v))
{
  'name': 'People',
  '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.

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. 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()]
['Companies', '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 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.

    • 3: Degree-cycle optimization.

    • 4: Query order optimization.

    Optional. Default=None, which implies a value of ‘4’.

  • 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:Employees) RETURN a.person_id INTO Results1')
>>> 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, 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.

    • 3: Degree-cycle optimization.

    • 4: Query order optimization.

    Optional. Default=None, which implies a value of ‘4’.

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:Employees) RETURN a.person_id INTO 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_optimization_level(optlevel=4)

Set the optimization level for TQL queries.

Parameters

optlevel (int) –

The optimization level values are:
  • 0: No optimization.

  • 1: General optimization.

  • 2: WHERE-clause optimization.

  • 3: Degree-cycle optimization.

  • 4: Query order 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:Employees) RETURN a.person_id INTO Results1'
>>> jb1 = conn.schedule_job(qr1)
>>> qr2 = 'MATCH (b:Employees) RETURN b.person_id INTO Results2'
>>> 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=None)

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 (int) – Max number of seconds the function will block. Optional. Default=None (no timeout).

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