xgt package¶

Submodules¶

xgt.common module¶

exception xgt.common.xgt_exception(msg, trace='')¶

Bases: Exception

Exception to be thrown by xgt in error cases.

exception xgt.common.xgt_invalid_filepath(msg, trace='')¶: Bases: xgt.common.xgt_exception

exception xgt.common.xgt_not_supported(msg, trace='')¶: Bases: xgt.common.xgt_exception

class xgt.common.Job(data)¶

Bases: object

Represents a user-scheduled Job.

An instance of this object is created by job-scheduling functions like xgt.Service.run_job and xgt.Service.schedule_job.

A Job is used as a proxy for a job in the server and allows the user to monitor its execution, possibly cancel it, and learn about its status during and after execution.

Attributes:	`end_time` str: Date and time when the job finished running. `error` str: User-friendly error message describing the reason a job failed. `id` int: Identifier of the job. `start_time` str: Date and time when the job was scheduled. `status` str: Status of the job. `trace` str: Very detailed error message for a failed job.

end_time¶

str: Date and time when the job finished running.

This is a formatted string that has a resolution of seconds.

error¶: str: User-friendly error message describing the reason a job failed.

id¶

int: Identifier of the job.

A 64-bit integer value that uniquely identifies a job. It is automatically incremented for each scheduled job over the lifetime of the xgtd server process.

start_time¶

str: Date and time when the job was scheduled.

This is a formatted string that has a resolution of seconds.

status¶

str: Status of the job.

The possible values are:

trace¶

str: Very detailed error message for a failed job.

This error message contains the friendly error message and a stack strace for the code that participated in the error.

class xgt.common.CustomDictionary¶

Bases: object

An object that behaves as a dictionary and allows access to the keys as dynamic properties. The keys are ordered by arrival as a list and are iterable. A data item can be accessed using the key name using dictionary syntax and also using a ‘property’ access syntax. Key names are case sensitive in both dictionary key reference syntax and ‘property’ access syntax.

Examples

Instances of this class are during the creation of table, vertex type and edge type. >>> t = xgt.Table(name = ‘mytable’, … schema = [(‘col0’, xgt.INT), (‘col1’, xgt.TEXT)]) >>> conn.create(t) >>> tbl = conn.get_table(‘mytable’) >>> print(tbl.schema) [[‘col0’, ‘int’], [‘col1’, ‘text’]] >>> # A column can be accessed in the schema as a dictionary key. >>> print(tbl.schema[‘col0’]) int >>> # The same column can be accessed in the schema as a property. >>> print(tbl.schema.col0) int

class xgt.common.Key(name, key)¶

Bases: object

Object used to hold a Vertex key encoded as the name of the Vertex and a list of key names. A Key instance allows accessing the key names as dynamic properties and also provides a string representation of the key to represent it as json and tql.

Examples

>>> vtx = xgt.Key('Person', ['name', 'lastname'])
>>> print(vtx.name)
Person.name
>>> print(vtx.lastname)
Person.lastname

xgt.connection module¶

class xgt.connection.Connection(host='127.0.0.1', port=4367, local=False, debug=False)¶

Bases: object

Connection to the server.

Parameters:	host : str IP address of the computer where the server is running. port : int Port where the server is listening on. debug : boolean Run the server in debug mode.

REST_VERSION = '1.0'¶

xgt.experimental module¶

class xgt.experimental.BooleanExpression(text)¶

Bases: xgt.experimental.Expression

Represents a boolean expression in the context of a query.

Parameters:	text : str Textual representation of the expression in Cypher.

Methods

`and_`(expr)	Returns an ‘and’ boolean expression of two boolean expressions.
`as_`(col_name)	Creates an alternative name for a property or a name for an expression.
`or_`(expr)	Returns an ‘or’ boolean expression of two boolean expressions.

and_(expr)¶

Returns an ‘and’ boolean expression of two boolean expressions.

Parameters:	expr : BooleanExpression A boolean expression.

or_(expr)¶

Returns an ‘or’ boolean expression of two boolean expressions.

Parameters:	expr : BooleanExpression A boolean expression.

class xgt.experimental.Expression(text)¶

Bases: object

Represents an expression in the context of a query.

Parameters:	text : str Textual representation of the expression in Cypher.

Methods

as_(col_name) Creates an alternative name for a property or a name for an expression.

as_(col_name)¶

Creates an alternative name for a property or a name for an expression. It is meant to be used in the ‘return_’ or ‘return_distinct’ functions.

Parameters:	col_name : str Name to be given to an expression.

class xgt.experimental.Link(edge)¶

Bases: object

Represents an edge in a query pattern.

Parameters:	edge : EdgeProxy Instance of an EdgeProxy.

class xgt.experimental.Node(vertex)¶

Bases: object

Represents a vertex in a query pattern.

Parameters:	vertex : VertexProxy Instance of a VertexProxy.

Methods

`indegree`()	Returns the count of incoming edges.
`outdegree`()	Returns the count of outgoing edges.

indegree()¶: Returns the count of incoming edges.

outdegree()¶: Returns the count of outgoing edges.

class xgt.experimental.Property(entity, name, ptype)¶

Bases: object

Represents a vertex or edge property in the context of a query.

Parameters:	entity : VertexProxy, EdgeProxy Instance of VertexProxy or EdgeProxy. name : str Name of the property obtained from the schema in the VertexProxy or EdgeProxy. ptype : str xGT data type of the property.
Attributes:	`name` Name of the property. `type` Data type of the property.

Methods

`as_`(alias)	Creates an alias for the expression.
`avg`()	Average aggregation of the property across the rows of the result.
`contains`(strval)	If the property’s value contains the text in strval it returns True; otherwise it returns False.
`ends_with`(strval)	If the property’s value ends with the text in strval it returns True; otherwise it returns False.
`in_`(lst)	If the property’s value is in the list returns True; False otherwise.
`is_null`()	If the property’s value is Null returns True; False otherwise.
`max`()	Maximum aggregation of the property across the rows of the result.
`min`()	Minimum aggregation of the property across the rows of the result.
`starts_with`(strval)	If the property’s value starts with the text in strval it returns True; otherwise it returns False.
`sum`()	Sum aggregation of the property across the rows of the result.

as_(alias)¶

Creates an alias for the expression.

Parameters:	alias : str Alias provided for the expression.

avg()¶: Average aggregation of the property across the rows of the result.

contains(strval)¶

If the property’s value contains the text in strval it returns True; otherwise it returns False.

Parameters:	strval : str Text value.

ends_with(strval)¶

If the property’s value ends with the text in strval it returns True; otherwise it returns False.

Parameters:	strval : str Text value.

in_(lst)¶

If the property’s value is in the list returns True; False otherwise.

Parameters:	lst : list List of values. Example: [‘a’, ‘b’, ‘c’].

is_null()¶: If the property’s value is Null returns True; False otherwise.

max()¶: Maximum aggregation of the property across the rows of the result.

min()¶: Minimum aggregation of the property across the rows of the result.

name¶: Name of the property.

starts_with(strval)¶

If the property’s value starts with the text in strval it returns True; otherwise it returns False.

Parameters:	strval : str Text value.

sum()¶: Sum aggregation of the property across the rows of the result.

type¶: Data type of the property.

class xgt.experimental.Query(lcls, *args)¶

Bases: object

Allows expressing a graph query in Python syntax. A query consists of a set of sub-patterns to form a graph search pattern. A sub-pattern can be a single vertex: (vertex) or a tuple of items with the following format: (source vertex, edge, target vertex). Optionally a tuple can have a fourth item that indicates edge navigation direction and can be used as follows: (source vertex, edge, target vertex, xgt.REV).

Parameters:	lcls : locals() Provide the Python function “locals()”. This function is required and makes name discovery possible. args : list List of tuples representing query sub-patterns.

Methods

`into_table`(table_name)	Sets the name of the table that will receive the query results.
`limit`(row_count)	The result will contain no more rows than the specified by ‘row_count’.
`order_by`(*args)	Allows listing the properties to use to order/sort the query result.
`return_`(*args)	Allows listing the properties or expressions to be returned as part of the query result.
`return_distinct`(*args)	Allows listing the properties or expressions to be returned as part of the query result.
`skip`(row_count)	The result will attempt to skip a number of rows equal to ‘row_count’ and then will include the remaining ones.
`where`(val)	Allows conditional filtering of query results.

into_table(table_name)¶

Sets the name of the table that will receive the query results.

Parameters:	table_name : str Name of a table.

limit(row_count)¶

The result will contain no more rows than the specified by ‘row_count’.

Parameters:	row_count : int Maximum number of rows to return.

order_by(*args)¶

Allows listing the properties to use to order/sort the query result.

Parameters:	args : list One or more properties.

return_(*args)¶

Allows listing the properties or expressions to be returned as part of the query result.

Parameters:	args : list One or more properties or expressions.

return_distinct(*args)¶

Allows listing the properties or expressions to be returned as part of the query result. Each row in the result will have a unique combination of values.

Parameters:	args : list One or more properties or expressions.

skip(row_count)¶

The result will attempt to skip a number of rows equal to ‘row_count’ and then will include the remaining ones. If the result set orginally had as many or less rows than ‘row_count’ then no rows will be returned.

Parameters:	row_count : int Number of rows to skip.

where(val)¶

Allows conditional filtering of query results.

Parameters:	val : BooleanExpression Expression resulting of the composition of Boolean expressions involving Node properties and Link properties.

xgt.experimental.count_rows()¶: Returns a ‘count(*)’ expression.

xgt.experimental.not_(expr)¶

Returns a ‘not’ boolean expression of the provided boolean expression.

Parameters:	expr : BooleanExpression A boolean expression.

xgt.graph module¶

class xgt.graph.DataTable(columns, data)¶

Bases: object

Aggregate object containing data shaped as columns and rows returned from an xGT server. Instances of this class are returned by the get_data() method in VertexProxy, EdgeProxy, and TableProxy.

Attributes:	`columns` List of column names `values` List of data rows expressed as a list of lists.

columns¶: List of column names

values¶: List of data rows expressed as a list of lists.

class xgt.graph.DataTableValues(data)¶

Bases: object

A list of rows of data from a DataTable. An instance of this class is created by DataTable to represent the data portion (without column names) of a data set.

Methods

tolist

tolist()¶

class xgt.graph.Edge(name, schema, source, target)¶

Bases: object

Defines a new edge type.

Edge objects capture the names and datatypes of properties on edges, and they are required in order to define a new graph.

Parameters:

Parameters:	name : str Edge type name. schema : list of tuples List of tuples associating property names with xGT data types. source : list of tuples Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the source of the edge. target : list of tuples Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the target of the edge.

name : str: Edge type name.
schema : list of tuples: List of tuples associating property names with xGT data types.
source : list of tuples: Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the source of the edge.
target : list of tuples: Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the target of the edge.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> v1 = ...
>>> v2 = ...
>>> e1 = xgt.Edge(name   = 'WorksFor',
...               schema = [('srcid', xgt.INT),
...                         ('trgid', xgt.INT)],
...               source = [('srcid', v1.key.id)],
...               target = [('trgid', v2.key.id)])
>>> ng.add(v1).add(v2).add(e1)
>>> conn.create(ng)

Attributes:	`name` str: Name of the edge type. `schema` list of tuples: List of name-type pairs.

name¶: str: Name of the edge type.

schema¶: list of tuples: List of name-type pairs.

class xgt.graph.EdgeProxy(conn, obj)¶

Bases: object

EdgeProxy objects represent a collection of edges held on the xGT server and can be used to retrieve information about them. These objects are returned from a GraphProxy object, not directly instantiated.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal edge structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> e = g.edges.WorksFor          # WorksFor is an existing edge type
>>> print(e.name)

Attributes:	`name` str: Name of the edge type. `schema` CustomDictionary: Set of edge properties. `source` str : Name of the source vertex. `target` str : Name of the target vertex.

Methods

`get_data`([offset, length])	Returns edge data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing edge data starting at a given offset and spanning a given length.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_edges`()	int: Gets the number of edges of the edge type.
`num_properties`()	int: Gets the number of properties of the edge type.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

entity

entity()¶

get_data(offset=0, length=None)¶

Returns edge data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing edge data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

Parameters:	paths : list Paths to the CSV files. Syntax for one CSV file path: local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’ headerMode : str Indicates if the files contain headers: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT Optional. Default=HeaderMode.NONE.

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> g = conn.get_graph('Company')
>>> g.edges.WorksFor.load('xgtd:///home/username/file.csv')

name¶: str: Name of the edge type.

num_edges()¶: int: Gets the number of edges of the edge type.

num_properties()¶: int: Gets the number of properties of the edge type.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

Parameters:	path : str Path to the CSV file. Syntax for one CSV file path: local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’ offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved. Optional. Default=None. headers : boolean Indicates if headers should be added. Optional. Default=False.

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of edge properties.

source¶: str : Name of the source vertex.

target¶: str : Name of the target vertex.

class xgt.graph.Graph(name)¶

Bases: object

Defines a new graph type, composed of vertex and edge types.

An instance of Graph is used by the Service.create() function to create a new graph in xGT.

Parameters:	name : str Graph name.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> ...
>>> conn.create(ng)

Attributes:	`edges` CustomDictionary: the Edge Types used in the graph. `name` str: Name of the graph. `vertices` CustomDictionary: the Vertex Types used in the graph.

Methods

add(obj) Adds a vertex or an edge object to the graph.

add(obj)¶

Adds a vertex or an edge object to the graph.

Parameters:	obj : Vertex, Edge An instance of the Vertex or Edge class.
Returns:	Graph The current Graph object, allowing chaining of methods.

edges¶

CustomDictionary: the Edge Types used in the graph.

Edges can be accessed either as a list using indices: `graph.edges[1]` or as an object using edge names as attributes: `graph.edges.edge_name`

name¶: str: Name of the graph.

vertices¶

CustomDictionary: the Vertex Types used in the graph.

Vertices can be accessed either as a list using indices: `graph.vertices[1]` or as an object using vertex names as attributes: `graph.vertices.vertex_name`

class xgt.graph.GraphProxy(conn, obj)¶

Bases: object

GraphProxy objects represent a graph structure held on the xGT server and can be used to retrieve information about graph data on it. These objects are returned by the Service.get_graph() method.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal graph structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> print(g.name)

Attributes:	`edges` CustomDictionary: Set of edges in the graph. `name` str: Name of the graph. `vertices` CustomDictionary: Set of vertices in the graph.

Methods

`num_edges`()	int: Total count of edges across all Edge Types contained by the Graph.
`num_vertices`()	int: Total count of vertices across all Vertex Types contained by the Graph.

edges¶: CustomDictionary: Set of edges in the graph.

name¶: str: Name of the graph.

num_edges()¶: int: Total count of edges across all Edge Types contained by the Graph.

num_vertices()¶: int: Total count of vertices across all Vertex Types contained by the Graph.

vertices¶: CustomDictionary: Set of vertices in the graph.

class xgt.graph.HeaderMode¶

Bases: object

IGNORE = 1¶

NONE = 0¶

NORMAL = 2¶

STRICT = 3¶

class xgt.graph.Table(name, schema)¶

Bases: object

Used to define a new table.

An instance of Table can be passed to the conn.create() function to create a new table in xGT.

Parameters:	name : str Table name. schema : list List of property names and data types. [(‘col0’, xgt.INT), (‘col1’, xgt.TEXT), … ]

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_table('table01')
>>> nt = xgt.Table(name   = 'table01',
...                schema = [('col01', xgt.INT),
...                          ('col02', xgt.TEXT),
...                          ('col03', xgt.DATE)])
>>> conn.create(nt)

Attributes:	`name` str: Name of the table. `schema` list of tuples: List of name-type pairs.

name¶: str: Name of the table.

schema¶: list of tuples: List of name-type pairs.

class xgt.graph.TableProxy(conn, obj)¶

Bases: object

TableProxy objects represent a table held on the xGT server and can be used to retrieve information about it. These objects are returned from a Connection object, not directly instantiated.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal table structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> t = conn.get_table('table01')
>>> print(t.name)

Attributes:	`name` str: Name of the table. `schema` CustomDictionary: Set of table columns.

Methods

`get_data`([offset, length])	Returns table data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing table data starting at a given offset and spanning a given length.
`get_definition`()	str: Gets the TQL command that could be used to recreate the table.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_cols`()	int: Gets the number of columns of the table.
`num_rows`()	int: Gets the number of rows of the table.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

get_data(offset=0, length=None)¶

Returns table data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing table data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

get_definition()¶: str: Gets the TQL command that could be used to recreate the table.

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> t = conn.get_table('table01')
>>> t.load('xgtd:///home/username/file.csv')

name¶: str: Name of the table.

num_cols()¶: int: Gets the number of columns of the table.

num_rows()¶: int: Gets the number of rows of the table.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of table columns.

class xgt.graph.Vertex(name, schema, key)¶

Bases: object

Defines a new vertex type.

Vertex objects capture the names and datatypes of properties on vertices, and they are required in order to define a new graph.

Parameters:	name : str Vertex type name. schema : list of tuples List of tuples associating property names with xGT data types. key : list of strings List of one or more property names that are used to uniquely identify vertices in the graph.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> v1 = xgt.Vertex(name   = 'Person',
...                 schema = [('id', xgt.INT),
...                           ('name', xgt.TEXT)],
...                 key    = ['id'])
>>> ng.add(v1)
>>> ...
>>> conn.create(ng)

Attributes:	`key` list: List of property names that identify a single vertex. `name` str: Name of the vertex type. `schema` list of tuples: List of name-type pairs.

key¶: list: List of property names that identify a single vertex.

name¶: str: Name of the vertex type.

schema¶: list of tuples: List of name-type pairs.

class xgt.graph.VertexProxy(conn, obj)¶

Bases: object

VertexProxy objects represent a collection of vertices held on the xGT server and can be used to retrieve information about them. These objects are accessed through a GraphProxy object, not directly instantiated.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal vertex structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> v = g.vertices.Person          # Person is an existing vertex type
>>> print(v.name)

Attributes:	`name` str: Name of the vertex type. `schema` CustomDictionary: Set of vertex properties.

Methods

`get_data`([offset, length])	Returns vertex data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing vertex data starting at a given offset and spanning a given length.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_properties`()	int: Gets the number of properties of the vertex type.
`num_vertices`()	int: Gets the number of vertices of the vertex type.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

entity

entity()¶

get_data(offset=0, length=None)¶

Returns vertex data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing vertex data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> g = conn.get_graph('Company')
>>> g.vertices.Person.load('xgtd:///home/username/file.csv')

name¶: str: Name of the vertex type.

num_properties()¶: int: Gets the number of properties of the vertex type.

num_vertices()¶: int: Gets the number of vertices of the vertex type.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of vertex properties.

xgt.service module¶

class xgt.service.Service(host='127.0.0.1', port=4367, local=False, debug=False, key_id='', secret_key='')¶

Bases: xgt.connection.Connection

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. debug : boolean Run the server in debug mode. key_id : str Amazon Access Key ID. secret_key : str AWS Secret Access Key corresponding to the AWS Access Key ID.

Methods

`about`()	Obtains some statistics from the server.
`cancel_job`(jobid)	Cancel the execution of a job in the server.
`create`(obj)	Create a new graph or a table in the server.
`drop_graph`(name)	Drop a graph using its name.
`drop_table`(name)	Drop a table using its name.
`explain`(query)	This function is unsupported.
`format_explain`(query_explanation)	This function is unsupported.
`get_graph`(name)	Get a proxy object that allows interaction with the graph.
`get_graph_definition`(name)	Get a textual representation of the graph.
`get_graphs`()	Get a list of graph names present in the server.
`get_job`(jobid)	Get a Job object that represents the state of a job in the server at the point in time of the invocation of this function.
`get_job_status`(jobid)	Get the status of a job.
`get_jobs`()	Get a list of job IDs initiated from the client interface.
`get_table`(name)	Get a proxy object that allows interaction with the table.
`get_tables`()	Get a list of table names present in the server.
`run_job`(queries[, optlevel, timeout])	Run one a or more TQL queries as a single job.
`schedule_job`(queries[, optlevel])	Schedule one a or more TQL queries as a single job.
`set_optimization_level`(optlevel)	Set the optimization level for TQL queries.
`version`()	Obtains the current product version from the server.
`wait_for_jobs`(jobs[, timeout])	Wait for one a or more jobs.

stat_report
stat_reset

about()¶

Obtains some statistics from the server.

Returns:	dict High level statistics relevant to xgtd.

Examples

>>> conn = xgt.connect()
>>> print(conn.about())
{'version': '0.15.0',
 'platform': 'singlenode',
 'localities': 1,
 'workerthreads': 4,
 'currentmemory': '25.45MB',
 'peakmemory': '25.45MB',
 'totalmemory': '11.82GB'}

cancel_job(jobid)¶

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:	jobid : int Job id obtained using the xgt.Service.get_jobs function.
Returns:	Job Information for the canceled job.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> print(conn.cancel_job(18))
id:18, status:completed

create(obj)¶

Create a new graph or a table in the server.

Parameters:	obj : Graph, Table Instance of Graph or Table with the new graph or table definition.

drop_graph(name)¶

Drop a graph using its name.

Parameters:	name : str Graph name.

drop_table(name)¶

Drop a table using its name.

Parameters:	name : str Table name.

explain(query)¶: This function is unsupported.

format_explain(query_explanation)¶: This function is unsupported.

get_graph(name)¶

Get a proxy object that allows interaction with the graph.

Parameters:	name : str Graph name.
Returns:	GraphProxy Proxy to the graph.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> g = conn.get_graph('Company')
>>> print(str(g))
{
    'vertices': [{
        'name': 'Employee',
        'key': ['PersonID'],
        'schema': [
            ['PersonID', 'int'],
            ['Name', 'text'],
            ['PostalCode', 'int']]
    }],
    'name':
    'Company',
    'edges': [{
        'source': 'Employee',
        'target': 'Employee',
        'name': 'ReportsTo',
        'schema': [
            ['EmpID', 'int'],
            ['BossID', 'int'],
            ['StartDate', 'date'],
            ['EndDate', 'date']]
    }]
}

get_graph_definition(name)¶

Get a textual representation of the graph.

Parameters:	name : str Graph name.

get_graphs()¶

Get a list of graph names present in the server.

Returns:	list Names of graphs present in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> print(conn.get_graphs())
['Company']

get_job(jobid)¶

Get a Job object that represents the state of a job in the server at the point in time of the invocation of this function.

Parameters:	jobid : int Job id obtained using the xgt.Service.get_jobs function.
Returns:	Job State of a job in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> j = conn.get_job(18)
>>> print(j)
id:18, status:completed

get_job_status(jobid)¶

Get the status of a job.

Parameters:

jobid : int: Job id obtained using the xgt.Service.get_jobs function.

Returns:

str

Status of the job.

The possible values are:

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> print(conn.get_job_status(18))
completed

get_jobs()¶

Get a list of job IDs initiated from the client interface.

Returns:	list A list of integer job IDs.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]

get_table(name)¶

Get a proxy object that allows interaction with the table.

Parameters:	name : str Table name.
Returns:	TableProxy Proxy to the table.

Examples

>>> conn = xgt.connect()
>>> ... create graph and run queries ...
>>> t = conn.get_table('Employee_table')
>>> print(str(t))
{
    'name': 'Employee_table',
    'schema': [
        ['PersonID', 'int'],
        ['Name', 'text'],
        ['PostalCode', 'int']]
}

get_tables()¶

Get a list of table names present in the server.

Returns:	list Table names present in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph and run queries ...
>>> print(conn.get_tables())
['Employee_table', 'ReportsTo_table', 'Result1']

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

Run one a or more TQL queries as a single job. This function blocks until the job stops running.

If a list of queries is provided each query will be executed one at a time.

Parameters:	queries : str, list One TQL query string or a list of TQL query strings. 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:	list List of jobs with completed queries.
Raises:	xgt_exception If any of the query(ies) 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.connect()
>>> ... create graph(s) ...
>>> job = conn.run_job('MATCH (a:Employee) RETURN a.PersonID INTO Result1')
>>> print(job[0])
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(queries, optlevel=None)¶

Schedule one a or more TQL queries as a single job. This function returns immediately after scheduling the job.

If a list of queries is provided each query will be executed one at a time.

Parameters:	queries : str, list One TQL query string or a list of TQL query strings. 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:	Job A Job scheduled to run as soon as possible.
Raises:	xgt_exception If any of the query(ies) is not a string (str) or the query text is larger than 209,000 characters.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> queries = ['MATCH (a:Employee) RETURN a.PersonID INTO Result1',
               'MATCH (b:Employee) RETURN b.PersonID INTO Result2']
>>> job = conn.schedule_job(queries)
>>> print(job)
id:25, status:scheduled

set_optimization_level(optlevel)¶

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=None, which implies a value of ‘2’.

stat_report()¶

stat_reset()¶

version()¶

Obtains the current product version from the server.

Returns:	str Version number.

wait_for_jobs(jobs, timeout=None)¶

Wait for one a or more jobs. This function blocks until all job stop running.

Parameters:	jobs : Job, list One Job instance or a list of jobs. timeout : int Maximum number of seconds that the jobs should take before being automatically canceled. Optional. Default=None (no timeout).
Returns:	list List of jobs with completed queries.
Raises:	xgt_exception If any of the query(ies) 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.connect()
>>> ... create graph(s) ...
>>> 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)
>>> jobs = conn.wait_for_jobs([jb1, jb2])
>>> print(jobs[0])
id:31, status:completed
>>> print(jobs[1])
id:32, status:completed

xgt.service.connect(host='127.0.0.1', port=4367, local=False, debug=False, key_id='', secret_key='')¶

Connect to a running xGT server.

Parameters:	host : str IP address of the computer where the server is running. port : int Port where the server is listening on. local: boolean Use Unix domain sockets to connect to a server on the same machine. debug : boolean Run the server in debug mode. key_id : str AWS Access Key ID. secret_key : str AWS Secret Access Key corresponding to the AWS Access Key ID.
Returns:	Service An object representing the connection to the server.

Module contents¶

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:

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

exception xgt.xgt_exception(msg, trace='')¶

Bases: Exception

Exception to be thrown by xgt in error cases.

exception xgt.xgt_invalid_filepath(msg, trace='')¶: Bases: xgt.common.xgt_exception

exception xgt.xgt_not_supported(msg, trace='')¶: Bases: xgt.common.xgt_exception

class xgt.Job(data)¶

Bases: object

Represents a user-scheduled Job.

An instance of this object is created by job-scheduling functions like xgt.Service.run_job and xgt.Service.schedule_job.

A Job is used as a proxy for a job in the server and allows the user to monitor its execution, possibly cancel it, and learn about its status during and after execution.

Attributes:	`end_time` str: Date and time when the job finished running. `error` str: User-friendly error message describing the reason a job failed. `id` int: Identifier of the job. `start_time` str: Date and time when the job was scheduled. `status` str: Status of the job. `trace` str: Very detailed error message for a failed job.

end_time¶

str: Date and time when the job finished running.

This is a formatted string that has a resolution of seconds.

error¶: str: User-friendly error message describing the reason a job failed.

id¶

int: Identifier of the job.

A 64-bit integer value that uniquely identifies a job. It is automatically incremented for each scheduled job over the lifetime of the xgtd server process.

start_time¶

str: Date and time when the job was scheduled.

This is a formatted string that has a resolution of seconds.

status¶

str: Status of the job.

The possible values are:

trace¶

str: Very detailed error message for a failed job.

This error message contains the friendly error message and a stack strace for the code that participated in the error.

class xgt.CustomDictionary¶

Bases: object

Examples

class xgt.Key(name, key)¶

Bases: object

Examples

>>> vtx = xgt.Key('Person', ['name', 'lastname'])
>>> print(vtx.name)
Person.name
>>> print(vtx.lastname)
Person.lastname

class xgt.Connection(host='127.0.0.1', port=4367, local=False, debug=False)¶

Bases: object

Connection to the server.

Parameters:	host : str IP address of the computer where the server is running. port : int Port where the server is listening on. debug : boolean Run the server in debug mode.

REST_VERSION = '1.0'¶

xgt.connect(host='127.0.0.1', port=4367, local=False, debug=False, key_id='', secret_key='')¶

Connect to a running xGT server.

Parameters:	host : str IP address of the computer where the server is running. port : int Port where the server is listening on. local: boolean Use Unix domain sockets to connect to a server on the same machine. debug : boolean Run the server in debug mode. key_id : str AWS Access Key ID. secret_key : str AWS Secret Access Key corresponding to the AWS Access Key ID.
Returns:	Service An object representing the connection to the server.

class xgt.Service(host='127.0.0.1', port=4367, local=False, debug=False, key_id='', secret_key='')¶

Bases: xgt.connection.Connection

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. debug : boolean Run the server in debug mode. key_id : str Amazon Access Key ID. secret_key : str AWS Secret Access Key corresponding to the AWS Access Key ID.

Methods

`about`()	Obtains some statistics from the server.
`cancel_job`(jobid)	Cancel the execution of a job in the server.
`create`(obj)	Create a new graph or a table in the server.
`drop_graph`(name)	Drop a graph using its name.
`drop_table`(name)	Drop a table using its name.
`explain`(query)	This function is unsupported.
`format_explain`(query_explanation)	This function is unsupported.
`get_graph`(name)	Get a proxy object that allows interaction with the graph.
`get_graph_definition`(name)	Get a textual representation of the graph.
`get_graphs`()	Get a list of graph names present in the server.
`get_job`(jobid)	Get a Job object that represents the state of a job in the server at the point in time of the invocation of this function.
`get_job_status`(jobid)	Get the status of a job.
`get_jobs`()	Get a list of job IDs initiated from the client interface.
`get_table`(name)	Get a proxy object that allows interaction with the table.
`get_tables`()	Get a list of table names present in the server.
`run_job`(queries[, optlevel, timeout])	Run one a or more TQL queries as a single job.
`schedule_job`(queries[, optlevel])	Schedule one a or more TQL queries as a single job.
`set_optimization_level`(optlevel)	Set the optimization level for TQL queries.
`version`()	Obtains the current product version from the server.
`wait_for_jobs`(jobs[, timeout])	Wait for one a or more jobs.

stat_report
stat_reset

about()¶

Obtains some statistics from the server.

Returns:	dict High level statistics relevant to xgtd.

Examples

>>> conn = xgt.connect()
>>> print(conn.about())
{'version': '0.15.0',
 'platform': 'singlenode',
 'localities': 1,
 'workerthreads': 4,
 'currentmemory': '25.45MB',
 'peakmemory': '25.45MB',
 'totalmemory': '11.82GB'}

cancel_job(jobid)¶

Cancel the execution of a job in the server.

Parameters:	jobid : int Job id obtained using the xgt.Service.get_jobs function.
Returns:	Job Information for the canceled job.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> print(conn.cancel_job(18))
id:18, status:completed

create(obj)¶

Create a new graph or a table in the server.

Parameters:	obj : Graph, Table Instance of Graph or Table with the new graph or table definition.

drop_graph(name)¶

Drop a graph using its name.

Parameters:	name : str Graph name.

drop_table(name)¶

Drop a table using its name.

Parameters:	name : str Table name.

explain(query)¶: This function is unsupported.

format_explain(query_explanation)¶: This function is unsupported.

get_graph(name)¶

Get a proxy object that allows interaction with the graph.

Parameters:	name : str Graph name.
Returns:	GraphProxy Proxy to the graph.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> g = conn.get_graph('Company')
>>> print(str(g))
{
    'vertices': [{
        'name': 'Employee',
        'key': ['PersonID'],
        'schema': [
            ['PersonID', 'int'],
            ['Name', 'text'],
            ['PostalCode', 'int']]
    }],
    'name':
    'Company',
    'edges': [{
        'source': 'Employee',
        'target': 'Employee',
        'name': 'ReportsTo',
        'schema': [
            ['EmpID', 'int'],
            ['BossID', 'int'],
            ['StartDate', 'date'],
            ['EndDate', 'date']]
    }]
}

get_graph_definition(name)¶

Get a textual representation of the graph.

Parameters:	name : str Graph name.

get_graphs()¶

Get a list of graph names present in the server.

Returns:	list Names of graphs present in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> print(conn.get_graphs())
['Company']

get_job(jobid)¶

Get a Job object that represents the state of a job in the server at the point in time of the invocation of this function.

Parameters:	jobid : int Job id obtained using the xgt.Service.get_jobs function.
Returns:	Job State of a job in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> j = conn.get_job(18)
>>> print(j)
id:18, status:completed

get_job_status(jobid)¶

Get the status of a job.

Parameters:

jobid : int: Job id obtained using the xgt.Service.get_jobs function.

Returns:

str

Status of the job.

The possible values are:

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
>>> print(conn.get_job_status(18))
completed

get_jobs()¶

Get a list of job IDs initiated from the client interface.

Returns:	list A list of integer job IDs.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) and run queries ...
>>> print(conn.get_jobs())
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]

get_table(name)¶

Get a proxy object that allows interaction with the table.

Parameters:	name : str Table name.
Returns:	TableProxy Proxy to the table.

Examples

>>> conn = xgt.connect()
>>> ... create graph and run queries ...
>>> t = conn.get_table('Employee_table')
>>> print(str(t))
{
    'name': 'Employee_table',
    'schema': [
        ['PersonID', 'int'],
        ['Name', 'text'],
        ['PostalCode', 'int']]
}

get_tables()¶

Get a list of table names present in the server.

Returns:	list Table names present in the server.

Examples

>>> conn = xgt.connect()
>>> ... create graph and run queries ...
>>> print(conn.get_tables())
['Employee_table', 'ReportsTo_table', 'Result1']

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

Run one a or more TQL queries as a single job. This function blocks until the job stops running.

If a list of queries is provided each query will be executed one at a time.

Parameters:	queries : str, list One TQL query string or a list of TQL query strings. 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:	list List of jobs with completed queries.
Raises:	xgt_exception If any of the query(ies) 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.connect()
>>> ... create graph(s) ...
>>> job = conn.run_job('MATCH (a:Employee) RETURN a.PersonID INTO Result1')
>>> print(job[0])
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(queries, optlevel=None)¶

Schedule one a or more TQL queries as a single job. This function returns immediately after scheduling the job.

If a list of queries is provided each query will be executed one at a time.

Parameters:	queries : str, list One TQL query string or a list of TQL query strings. 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:	Job A Job scheduled to run as soon as possible.
Raises:	xgt_exception If any of the query(ies) is not a string (str) or the query text is larger than 209,000 characters.

Examples

>>> conn = xgt.connect()
>>> ... create graph(s) ...
>>> queries = ['MATCH (a:Employee) RETURN a.PersonID INTO Result1',
               'MATCH (b:Employee) RETURN b.PersonID INTO Result2']
>>> job = conn.schedule_job(queries)
>>> print(job)
id:25, status:scheduled

set_optimization_level(optlevel)¶

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=None, which implies a value of ‘2’.

stat_report()¶

stat_reset()¶

version()¶

Obtains the current product version from the server.

Returns:	str Version number.

wait_for_jobs(jobs, timeout=None)¶

Wait for one a or more jobs. This function blocks until all job stop running.

Parameters:	jobs : Job, list One Job instance or a list of jobs. timeout : int Maximum number of seconds that the jobs should take before being automatically canceled. Optional. Default=None (no timeout).
Returns:	list List of jobs with completed queries.
Raises:	xgt_exception If any of the query(ies) 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.connect()
>>> ... create graph(s) ...
>>> 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)
>>> jobs = conn.wait_for_jobs([jb1, jb2])
>>> print(jobs[0])
id:31, status:completed
>>> print(jobs[1])
id:32, status:completed

class xgt.Graph(name)¶

Bases: object

Defines a new graph type, composed of vertex and edge types.

An instance of Graph is used by the Service.create() function to create a new graph in xGT.

Parameters:	name : str Graph name.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> ...
>>> conn.create(ng)

Attributes:	`edges` CustomDictionary: the Edge Types used in the graph. `name` str: Name of the graph. `vertices` CustomDictionary: the Vertex Types used in the graph.

Methods

add(obj) Adds a vertex or an edge object to the graph.

add(obj)¶

Adds a vertex or an edge object to the graph.

Parameters:	obj : Vertex, Edge An instance of the Vertex or Edge class.
Returns:	Graph The current Graph object, allowing chaining of methods.

edges¶

CustomDictionary: the Edge Types used in the graph.

Edges can be accessed either as a list using indices: `graph.edges[1]` or as an object using edge names as attributes: `graph.edges.edge_name`

name¶: str: Name of the graph.

vertices¶

CustomDictionary: the Vertex Types used in the graph.

Vertices can be accessed either as a list using indices: `graph.vertices[1]` or as an object using vertex names as attributes: `graph.vertices.vertex_name`

class xgt.Vertex(name, schema, key)¶

Bases: object

Defines a new vertex type.

Vertex objects capture the names and datatypes of properties on vertices, and they are required in order to define a new graph.

Parameters:	name : str Vertex type name. schema : list of tuples List of tuples associating property names with xGT data types. key : list of strings List of one or more property names that are used to uniquely identify vertices in the graph.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> v1 = xgt.Vertex(name   = 'Person',
...                 schema = [('id', xgt.INT),
...                           ('name', xgt.TEXT)],
...                 key    = ['id'])
>>> ng.add(v1)
>>> ...
>>> conn.create(ng)

Attributes:	`key` list: List of property names that identify a single vertex. `name` str: Name of the vertex type. `schema` list of tuples: List of name-type pairs.

key¶: list: List of property names that identify a single vertex.

name¶: str: Name of the vertex type.

schema¶: list of tuples: List of name-type pairs.

class xgt.Edge(name, schema, source, target)¶

Bases: object

Defines a new edge type.

Edge objects capture the names and datatypes of properties on edges, and they are required in order to define a new graph.

Parameters:

name : str: Edge type name.
schema : list of tuples: List of tuples associating property names with xGT data types.
source : list of tuples: Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the source of the edge.
target : list of tuples: Each tuple maps the name of an edge property to the name of a ‘key’ property of a vertex, which is used as the target of the edge.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_graph('Company')
>>> ng = xgt.Graph('Company')
>>> v1 = ...
>>> v2 = ...
>>> e1 = xgt.Edge(name   = 'WorksFor',
...               schema = [('srcid', xgt.INT),
...                         ('trgid', xgt.INT)],
...               source = [('srcid', v1.key.id)],
...               target = [('trgid', v2.key.id)])
>>> ng.add(v1).add(v2).add(e1)
>>> conn.create(ng)

Attributes:	`name` str: Name of the edge type. `schema` list of tuples: List of name-type pairs.

name¶: str: Name of the edge type.

schema¶: list of tuples: List of name-type pairs.

class xgt.Table(name, schema)¶

Bases: object

Used to define a new table.

An instance of Table can be passed to the conn.create() function to create a new table in xGT.

Parameters:	name : str Table name. schema : list List of property names and data types. [(‘col0’, xgt.INT), (‘col1’, xgt.TEXT), … ]

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> conn.drop_table('table01')
>>> nt = xgt.Table(name   = 'table01',
...                schema = [('col01', xgt.INT),
...                          ('col02', xgt.TEXT),
...                          ('col03', xgt.DATE)])
>>> conn.create(nt)

Attributes:	`name` str: Name of the table. `schema` list of tuples: List of name-type pairs.

name¶: str: Name of the table.

schema¶: list of tuples: List of name-type pairs.

class xgt.GraphProxy(conn, obj)¶

Bases: object

GraphProxy objects represent a graph structure held on the xGT server and can be used to retrieve information about graph data on it. These objects are returned by the Service.get_graph() method.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal graph structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> print(g.name)

Attributes:	`edges` CustomDictionary: Set of edges in the graph. `name` str: Name of the graph. `vertices` CustomDictionary: Set of vertices in the graph.

Methods

`num_edges`()	int: Total count of edges across all Edge Types contained by the Graph.
`num_vertices`()	int: Total count of vertices across all Vertex Types contained by the Graph.

edges¶: CustomDictionary: Set of edges in the graph.

name¶: str: Name of the graph.

num_edges()¶: int: Total count of edges across all Edge Types contained by the Graph.

num_vertices()¶: int: Total count of vertices across all Vertex Types contained by the Graph.

vertices¶: CustomDictionary: Set of vertices in the graph.

class xgt.VertexProxy(conn, obj)¶

Bases: object

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal vertex structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> v = g.vertices.Person          # Person is an existing vertex type
>>> print(v.name)

Attributes:	`name` str: Name of the vertex type. `schema` CustomDictionary: Set of vertex properties.

Methods

`get_data`([offset, length])	Returns vertex data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing vertex data starting at a given offset and spanning a given length.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_properties`()	int: Gets the number of properties of the vertex type.
`num_vertices`()	int: Gets the number of vertices of the vertex type.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

entity

entity()¶

get_data(offset=0, length=None)¶

Returns vertex data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing vertex data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> g = conn.get_graph('Company')
>>> g.vertices.Person.load('xgtd:///home/username/file.csv')

name¶: str: Name of the vertex type.

num_properties()¶: int: Gets the number of properties of the vertex type.

num_vertices()¶: int: Gets the number of vertices of the vertex type.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of vertex properties.

class xgt.EdgeProxy(conn, obj)¶

Bases: object

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal edge structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> g = conn.get_graph('Company')
>>> e = g.edges.WorksFor          # WorksFor is an existing edge type
>>> print(e.name)

Attributes:	`name` str: Name of the edge type. `schema` CustomDictionary: Set of edge properties. `source` str : Name of the source vertex. `target` str : Name of the target vertex.

Methods

`get_data`([offset, length])	Returns edge data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing edge data starting at a given offset and spanning a given length.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_edges`()	int: Gets the number of edges of the edge type.
`num_properties`()	int: Gets the number of properties of the edge type.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

entity

entity()¶

get_data(offset=0, length=None)¶

Returns edge data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing edge data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> g = conn.get_graph('Company')
>>> g.edges.WorksFor.load('xgtd:///home/username/file.csv')

name¶: str: Name of the edge type.

num_edges()¶: int: Gets the number of edges of the edge type.

num_properties()¶: int: Gets the number of properties of the edge type.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of edge properties.

source¶: str : Name of the source vertex.

target¶: str : Name of the target vertex.

class xgt.TableProxy(conn, obj)¶

Bases: object

TableProxy objects represent a table held on the xGT server and can be used to retrieve information about it. These objects are returned from a Connection object, not directly instantiated.

Parameters:	conn : Service An open connection to an xGT server. obj : json Internal table structure expressed in JSON objects.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> t = conn.get_table('table01')
>>> print(t.name)

Attributes:	`name` str: Name of the table. `schema` CustomDictionary: Set of table columns.

Methods

`get_data`([offset, length])	Returns table data starting at a given offset and spanning a given length.
`get_data_pandas`([offset, length])	Returns a Pandas DataFrame containing table data starting at a given offset and spanning a given length.
`get_definition`()	str: Gets the TQL command that could be used to recreate the table.
`insert`(data)	Inserts data rows.
`load`(paths[, headerMode])	Loads data from a CSV file in the path and the computer indicated by the path.
`num_cols`()	int: Gets the number of columns of the table.
`num_rows`()	int: Gets the number of rows of the table.
`save`(path[, offset, length, headers])	Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

get_data(offset=0, length=None)¶

Returns table data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	list of lists

get_data_pandas(offset=0, length=None)¶

Returns a Pandas DataFrame containing table data starting at a given offset and spanning a given length.

Parameters:	offset : int Position (index) of the first row to be retrieved. Optional. Default=0. length : int Maximum number of rows to be retrieved starting from the row indicated by offset. A value of ‘None’ means ‘all rows’ on and after the offset. Optional. Default=None.
Returns:	Pandas DataFrame

get_definition()¶: str: Gets the TQL command that could be used to recreate the table.

insert(data)¶

Inserts data rows. The properties of the new data must match the schema in both order and type.

Parameters:	data : list or Pandas dataframe Data represented by a list of lists of data items or by a Pandas Dataframe.

load(paths, headerMode=0)¶

Loads data from a CSV file in the path and the computer indicated by the path.

Parameters:

paths : list

Paths to the CSV files. Syntax for one CSV file path:

headerMode : str

Indicates if the files contain headers:: HeaderMode.NONE HeaderMode.IGNORE HeaderMode.NORMAL HeaderMode.STRICT

Optional. Default=HeaderMode.NONE.

Examples

>>> import xgt
>>> conn = xgt.connect()
>>> ...
>>> t = conn.get_table('table01')
>>> t.load('xgtd:///home/username/file.csv')

name¶: str: Name of the table.

num_cols()¶: int: Gets the number of columns of the table.

num_rows()¶: int: Gets the number of rows of the table.

save(path, offset=0, length=None, headers=False)¶

Writes the rows from the table to a CSV file in the path and the computer indicated by the path.

Parameters:

path : str: Path to the CSV file. Syntax for one CSV file path:

local to python: ‘<absolute path to csv file>’ xgtd computer: ‘xgtd://<absolute path to csv file>’ AWS s3: ‘s3://<absolute path to csv file>’ https site: ‘https://<absolute path to csv file>’ http site: ‘http://<absolute path to csv file>’ ftps server: ‘ftps://<absolute path to csv file>’
offset : int: Position (index) of the first row to be retrieved. Optional. Default=0.
length : int: Maximum number of rows to be retrieved. Optional. Default=None.
headers : boolean: Indicates if headers should be added. Optional. Default=False.

schema¶: CustomDictionary: Set of table columns.

class xgt.DataTable(columns, data)¶

Bases: object

Aggregate object containing data shaped as columns and rows returned from an xGT server. Instances of this class are returned by the get_data() method in VertexProxy, EdgeProxy, and TableProxy.

Attributes:	`columns` List of column names `values` List of data rows expressed as a list of lists.

columns¶: List of column names

values¶: List of data rows expressed as a list of lists.

class xgt.DataTableValues(data)¶

Bases: object

A list of rows of data from a DataTable. An instance of this class is created by DataTable to represent the data portion (without column names) of a data set.

Methods

tolist

tolist()¶

xgt package¶

Submodules¶

xgt.common module¶

xgt.connection module¶

xgt.experimental module¶

xgt.graph module¶

xgt.service module¶

Module contents¶

Main Features¶

Example¶

Table Of Contents

Search

scheduled	The state after the job has been created, but before it has started running.
running	The job is being executed.
completed	The job finished successfully.
canceled	The job was canceled.
failed	The job failed. When the job fails the error and trace properties are populated.