4. Quick Start Guide

This guide gets you started running a simple xGT server and client, for the purposes of trying out xGT in its simplest form. Note that this will require you to have root privileges for your environment.

Step 1: Install dnf packages.

sudo dnf install apr apr-utils bzip2-libs hwloc-libs krb5-libs numactl openssl-libs zlib

Step 2: Install the RPMs.

Download the RPMs provided as link by Trovares (typically provided by email).

sudo dnf install xgt-license-tools-X.Y.Z-1.x86_64.rpm xgt-server-X.Y.Z-1.x86_64.rpm

Step 3: Retrieve host-id of system to run xGT.

/opt/xgtd/bin/lmxendutil -hostid

A sample output from such a run:

/opt/xgtd/bin/lmxendutil -hostid
LM-X End-user Utility v5.0
Copyright (C) 2002-2021 X-Formation. All rights reserved.

ETHERNET: ens3
HostID: 000C2BC32G83

ETHERNET: ens4
HostID: 0A42F8D4C3F0

HOSTNAME: wyvern
HostID: wyvern

USERNAME: jacob
HostID: jacob

IPADDRESS: 192.128.121.148
HostID: 192.128.121.148

IPADDRESS: 192.138.111.*
HostID: 192.138.111.*

IPADDRESS: 192.118.*.*
HostID: 192.118.*.*

Copy the output of the program and send it to gettingstarted@trovares.com, and you will receive a license to your machine. Once you receive the license, put it in /etc/xgtd/licenses/. It should be named xgtd.lic.

Step 4: Update the PAM xgtd file.

xGT makes use of Pluggable Authentication Modules (PAM). For this example we’ll use pam_permit, which simply allows authentication of any user and password combination. Replace the file at path /etc/pam.d/xgtd with the following (Note: writing to this file path requires root privileges):

#
# /etc/pam.d/xgtd - specify the PAM behavior for xgtd
#

auth       required     pam_permit.so
account    required     pam_permit.so
session    required     pam_permit.so

Warning

The pam_permit.so module is insecure and should never be used in a production environment where the xGT server and the xGT client are communicating over a network.

Step 5: Start xgtd.

Execute the following commands to start xgtd.

systemctl start xgtd

Step 6: Install the Python client.

pip install xgt

Step 7: Install Jupyter Notebook.

To run the following Jupyter Notebook, you need the jupyter client installed.

pip install jupyter

Now we have done everything needed to set up the xGT server and client and can run a simple example. You may download the following as a Jupyter Notebook.

import xgt
# Connect to server
server = xgt.Connection()

# Drop all objects
[server.drop_frame(f) for f in ['ReportsTo', 'Employees']]

# Define and create the graph schema in the "demo" namespace
employees = server.create_vertex_frame(
  name='Employees',
  schema=[['person_id', xgt.INT],
          ['name', xgt.TEXT],
          ['postal_code', xgt.INT]],
  key='person_id')

reports_to = server.create_edge_frame(
  name='ReportsTo',
  schema=[['employee_id', xgt.INT],
          ['boss_id', xgt.INT],
          ['start_date', xgt.DATE],
          ['end_date', xgt.DATE]],
  source=employees,
  target=employees,
  source_key='employee_id',
  target_key='boss_id')

# Load data to the graph in the xGT server.
# Use the insert() method for data of a few hundred rows or fewer;
# for bigger amounts of data, use the load() method with CSV files.
employees.insert(
  [[111111101, 'Manny', 98103],
   [111111102, 'Trish', 98108],
   [911111501, 'Frank', 98101],
   [911111502, 'Alice', 98102]
  ])
reports_to.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', None],
   [111111102, 911111502, '2017-04-15', None],
   [911111501, 911111502, '2017-04-15', None]
  ])

def run_query(server, query):
    j=server.run_job(query)
    return j.get_data(format = 'pandas')

# Example Query
run_query(server, """
  MATCH (employee:Employees)-[edge1:ReportsTo]->
        (boss:Employees)-[edge2:ReportsTo]->(employee)
  WHERE
    edge1.end_date <= edge2.start_date
  RETURN
    employee.person_id AS employee1_id,
    boss.person_id AS employee2_id,
    edge1.start_date AS start1,
    edge1.end_date AS end1,
    edge2.start_date AS start2,
    edge2.end_date AS end2
""")

# Cleanup, drop all objects
[server.drop_frame(f) for f in ['ReportsTo', 'Employees']]

If setting up the server and client on separate machines, information on ssh tunneling can be found here: Use SSH Tunneling.