The Python interface to the Trovares xGT graph analytics engine.

Main Features

Data loading

xGT is a strongly-typed graph system. Loading data is a two-step process:

  1. Describe the structure and data types of your graph.

    Vertex and Edge objects describe the schema behind properties in your graph. These two are combined into a Graph object and passed to an xGT server to create the graph structure.

  2. Load your edge and vertex data.

    Once the type structure is set, the VertexProxy and EdgeProxy objects provide access to the server-side structures. Each of these provide high-performance, parallel load() methods to ingest data as well as a direct insert() method to add small amounts of data piecewise.

Query processing

Queries are expressed as strings written in TQL.

>>> query = '''
        MATCH  (emp:Employee)-[edge1:ReportsTo]->(boss:Employee)
        RETURN emp.PersonID AS EmployeeID,
               boss.PersonID AS BossID
        INTO   ResultTable
        '''

A query runs in the context of a Job, which can be run, scheduled and canceled. The run_job() method runs the query and blocks until it finishes successfully, terminates by an error, or it’s canceled.

Example

The following Python script shows some of the functions that can be used to create a graph, load data into it, run a query and access the results, and finally remove that graph from the system.

import xgt

#-- Connect to xgtd --
conn = xgt.connect()

#-- Define and create the graph --
conn.drop_graph('Company')
ng = xgt.Graph('Company')

v1 = xgt.Vertex(name   = 'Employee',
                schema = [['PersonID', xgt.INT],
                          ['Name', xgt.TEXT],
                          ['PostalCode', xgt.INT]],
                key    = ['PersonID'])

e1 = xgt.Edge(name   = 'ReportsTo',
              schema = [['EmpID', xgt.INT],
                        ['BossID', xgt.INT],
                        ['StartDate', xgt.DATE],
                        ['EndDate', xgt.DATE]],
              source = [['EmpID', v1.key.PersonID]],
              target = [['BossID', v1.key.PersonID]])
ng.add(v1).add(e1)

conn.create(ng)

#-- Load data to the graph in xgtd --
cg = conn.get_graph('Company')

emp = cg.vertices.Employee
rep = cg.edges.ReportsTo

# Use the insert() method for data of a few hundred rows or less;
# for bigger amounts of data, use the load() method with csv files.
emp.insert(
  [[111111101, 'Manny', 98103],
   [111111102, 'Trish', 98108],
   [911111501, 'Frank', 98101],
   [911111502, 'Alice', 98102]
  ])
rep.insert(
  [[111111101, 911111501, '2015-01-03', '2017-04-14'],
   [111111102, 911111501, '2016-04-02', '2017-04-14'],
   [911111502, 911111501, '2016-07-07', '2017-04-14'],
   [111111101, 911111502, '2017-04-15', '3000-12-31'],
   [111111102, 911111502, '2017-04-15', '3000-12-31'],
   [911111501, 911111502, '2017-04-15', '3000-12-31']
  ])


#-- Query data --
conn.drop_table('Result1')
cmd = '''
  MATCH
    (emp:Employee)-[edge1:ReportsTo]->
    (boss:Employee)-[edge2:ReportsTo]->
    (emp)
  WHERE
    edge1.EndDate <= edge2.StartDate
  RETURN
    emp.PersonID AS Employee1ID,
    boss.PersonID AS Employee2ID,
    edge1.StartDate AS FirstStart,
    edge1.EndDate AS FirstEnd,
    edge2.EndDate AS SecondEnd,
    edge2.StartDate AS SecondStart
  INTO
    Result1
  '''
conn.run_job(cmd)

#-- Results extraction --
ncols = emp.num_properties()
nrows = emp.num_vertices()
print('Employee columns: {0} rows: {1} '.format(ncols, nrows))

ncols = rep.num_properties()
nrows = rep.num_edges()
print('ReportsTo columns: {0} rows: {1} '.format(ncols, nrows))

r1 = conn.get_table('Result1')
ncols = r1.num_cols()
nrows = r1.num_rows()
print('Result columns: {0} rows: {1} '.format(ncols, nrows))
print('')

print('--- Result1 ---')
r1dat = r1.get_data(0, 100)
for row in r1dat:
    print(', '.join([str(c) for c in row]))
print('')

#-- Drop all objects --
conn.drop_graph('Company')
conn.drop_table('Result1')

General

connect([host, port, local, debug, key_id, …]) Connect to a running xGT server.
Service([host, port, local, debug, key_id, …]) Connection to the server with functionality to create, change, and remove graph structures and run jobs.
Job(data) Represents a user-scheduled Job.

Type Classes

Graph(name) Defines a new graph type, composed of vertex and edge types.
Vertex(name, schema, key) Defines a new vertex type.
Edge(name, schema, source, target) Defines a new edge type.
CustomDictionary() An object that behaves as a dictionary and allows access to the keys as dynamic properties.
Key(name, key) Object used to hold a Vertex key encoded as the name of the Vertex and a list of key names.

Data Access and Manipulation

GraphProxy(conn, obj) GraphProxy objects represent a graph structure held on the xGT server and can be used to retrieve information about graph data on it.
VertexProxy(conn, obj) VertexProxy objects represent a collection of vertices held on the xGT server and can be used to retrieve information about them.
EdgeProxy(conn, obj) EdgeProxy objects represent a collection of edges held on the xGT server and can be used to retrieve information about them.
TableProxy(conn, obj) TableProxy objects represent a table held on the xGT server and can be used to retrieve information about it.
DataTable(columns, data) Aggregate object containing data shaped as columns and rows returned from an xGT server.
DataTableValues(data) A list of rows of data from a DataTable.

Indices and tables