xgt.Connection

class xgt.Connection(host='127.0.0.1', port=4367, flags={})

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.
  • flags (dict) –

    Dictionary containing flags. Possible flags are: local : boolean

    Use Unix domain sockets to connect to a server on the same machine. The default is False.
    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.
__init__(host='127.0.0.1', port=4367, flags={})

x.__init__(…) initializes x; see help(type(x)) for signature

Methods

__init__([host, port, flags]) x.__init__(…) initializes x; see help(type(x)) for signature
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 using its name.
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

REST_VERSION
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 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.
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 lists) – List of lists 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 lists) – List of lists associating property name 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 using its name.

Parameters:frame (str, VertexFrame, EdgeFrame, or TableFrame) – Frame or name of frame to drop on xGT server
Returns:True if frame was found and dropped and False if frame was not found.
Return type:bool
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.

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

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

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()]
['Company', 'Person']
>>> print [f.num_vertices for f in conn.get_vertex_frames()]
[3, 101]
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:

xgt_exception – 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.xgt_exception: Failed jobs:
id: 22
error:
VertexTypeManager: 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:
  • 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’.
Returns:

A Job object representing the job that has been scheduled.
Return type:

Job
Raises:

xgt_exception – 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: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:

xgt_exception – 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