xgt.Connection¶
-
class
xgt.
Connection
(host='127.0.0.1', port=4367, flags=None)¶ Connection to the server with functionality to create, change, and remove graph structures and run jobs.
- Parameters
host (str) – IP address of the computer where the server is running.
port (int) – Port where the server is listening on for RPC calls.
flags (dict) –
Dictionary containing flags. Possible flags are:
- aws_access_key_idstr
Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string.
- aws_secret_access_keystr
Amazon Access Key ID, used for authentication when loading data files from S3 buckets. The default is an empty string.
- sslboolean
If true use ssl authentication for secure server channels. The default is False.
- ssl_root_dirstr
Path to the root folder for ssl certificates and private keys. Defaults to the user’s home directory.
- ssl_server_cnstr
Common name on the certificate of the server to connect to. The default is the hostname.
-
__init__
(host='127.0.0.1', port=4367, flags=None)¶ Initialize self. See help(type(self)) for accurate signature.
Methods
__init__
([host, port, flags])Initialize self.
call
(request, rpc_function)cancel_job
(job)Cancel the execution of a job in the server.
create_edge_frame
(name, schema, source, …)Create a new EdgeFrame in the server.
create_table_frame
(name, schema)Create a new TableFrame in the server.
create_vertex_frame
(name, schema, key)Create a new VertexFrame in the server.
drop_frame
(frame)Drop a VertexFrame, EdgeFrame, or TableFrame.
get_edge_frame
(name)Get an EdgeFrame object that allows interaction with a collection of edges.
get_edge_frames
([names, graph])Get a list of EdgeFrame objects present in the xGT server.
get_jobs
([jobids])Get a list of Job objects, each representing the state of the job on the server at the point in time of the invocation of this function.
Check whether the metrics cache is on and finished with updates.
get_table_frame
(name)Get a TableFrame object that allows interaction with a table present in the xGT server.
get_table_frames
([names])Get a list of TableFrame objects present in the server.
get_vertex_frame
(name)Get a VertexFrame object that allows interaction with a collection of vertices.
get_vertex_frames
([names])Get a list of VertexFrame objects present in the xGT server.
run_job
(query[, optlevel, timeout])Run a TQL query as a job.
schedule_job
(query[, optlevel])Schedule a TQL query as a job.
set_optimization_level
([optlevel])Set the optimization level for TQL queries.
wait_for_job
(job[, timeout])Wait for a job.
wait_for_metrics
([timeout])Wait until the metrics cache is finished with updates.
Attributes
Returns the amount of free memory available for user data on the xGT server.
Returns the maximum amount of memory available for user data on the xGT server.
Obtains the current product version from the server.
-
cancel_job
(job)¶ Cancel the execution of a job in the server.
A job can be canceled only if it is running and will have a status of canceled after its cancellation. A job that already had a status of completed or failed before invoking this function will keep that status after invoking this function.
- Parameters
job (Job, int) – A Job object or an integer job id to cancel.
- Returns
True if the job was cancelled. False if the job already had a status of completed or failed before invoking this function.
- Return type
bool
Examples
>>> conn = xgt.Connection() >>> ... create vertices and edges and run queries ... >>> print(conn.cancel_job(18)) id:18, status:completed >>> all_jobs = conn.get_jobs() >>> for j in all_jobs: >>> ... conn.cancel_job(j)
-
create_edge_frame
(name, schema, source, target, source_key, target_key)¶ Create a new EdgeFrame in the server.
An EdgeFrame represents a collection of edges held on the xGT server that share the same property names and types. The source vertex of each edge in an EdgeFrame must belong to the same VertexFrame. This source VertexFrame is identified by the source parameter of this function. The target vertex of each edge in an EdgeFrame must belong to the same VertexFrame. This target VertexFrame is identified by the target parameter.
For each edge in the EdgeFrame, its source vertex is identified by the edge property name given in the parameter source_key, which must be one of the properties listed in the schema. The edge target vertex is identified by the property name given in the parameter target_key, which must be one of the properties listed in the schema.
- Parameters
name (str) – Name of edge frame.
schema (list of pairs) – List of pairs associating property names with xGT data types. Each edge in the EdgeFrame will have these properties.
source (str or VertexFrame) – The name of a VertexFrame or a VertexFrame object. The source vertex of each edge in this EdgeFrame will belong to this VertexFrame.
target (str or VertexFrame) – The name of a VertexFrame or a VertexFrame object. The target vertex of each edge in this EdgeFrame will belong to this VertexFrame.
source_key (str) – The edge property name that identifies the source vertex of an edge. This is one of the properties from the schema.
target_key (str) – The edge property name that identifies the target vertex of an edge. This is one of the properties from the schema.
- Returns
Frame to the collection of edges.
- Return type
Examples
>>> import xgt >>> conn = xgt.Connection() >>> conn.create_vertex_frame( name = 'People', ... schema = [['id', xgt.INT], ... ['name', xgt.TEXT]], ... key = 'id') >>> conn.create_vertex_frame( name = 'Companies', ... schema = [['id', xgt.INT], ... ['size', xgt.TEXT], ... ['name', xgt.TEXT]], ... key = 'id') >>> conn.create_edge_frame( name = 'WorksFor', ... schema = [['srcid', xgt.INT], ... ['role', xgt.TEXT], ... ['trgid', xgt.INT]], ... source = 'People', ... target = 'Companies', ... source_key = 'srcid', ... target_key = 'trgid')
-
create_table_frame
(name, schema)¶ Create a new TableFrame in the server.
A TableFrame object represents a table held on the xGT server and can be used to retrieve information about it. The TableFrame schema describes the names and data types of table properties.
- Parameters
name (str) – Name of table.
schema (list of pairs) – List of pairs associating property names with xGT data types.
- Returns
Frame to the table.
- Return type
Examples
>>> import xgt >>> conn = xgt.Connection() >>> conn.create_table_frame( name = 'Table1', ... schema = [['id', xgt.INT], ... ['name', xgt.TEXT]])
-
create_vertex_frame
(name, schema, key)¶ Create a new VertexFrame in the server.
A VertexFrame represents a grouping or collection of vertices held on the xGT server, all sharing the same property names and types. This function creates a new frame of vertices on the xGT server and returns a VertexFrame representing it.
- Parameters
name (str) – Name of vertex frame.
schema (list of pairs) – List of pairs associating property names with xGT data types. Each vertex in the VertexFrame will have these properties.
key (str) – The property name used to uniquely identify vertices in the graph. This is the name of one of the properties from the schema and must be unique for each vertex in the frame.
- Returns
Frame to the collection of vertices.
- Return type
Examples
>>> import xgt >>> conn = xgt.Connection() >>> people = conn.create_vertex_frame( ... name = 'People', ... schema = [['id', xgt.INT], ... ['name', xgt.TEXT]], ... key = 'id')
-
drop_frame
(frame)¶ Drop a VertexFrame, EdgeFrame, or TableFrame.
- Parameters
frame (str, VertexFrame, EdgeFrame, or TableFrame) – A frame or the name of frame to drop on the xGT server.
- Returns
True if frame was found and dropped and False if frame was not found.
- Return type
bool
-
property
free_user_memory_size
¶ Returns the amount of free memory available for user data on the xGT server.
- Returns
Currently available user memory, in bytes.
- Return type
int
-
get_edge_frame
(name)¶ Get an EdgeFrame object that allows interaction with a collection of edges.
An EdgeFrame represents a collection of edges held on the xGT server and can be used to retrieve information about them. EdgeFrame.get_data_pandas() and EdgeFrame.get_data() are used to retrieve member edges. Edge edge in an EdgeFrame shares the same properties, described in EdgeFrame.schema.
- Parameters
name (str) – EdgeFrame name.
- Returns
Frame to the collection of edges.
- Return type
Examples
>>> conn = xgt.Connection() >>> ... create graph and run queries ... >>> e = conn.get_edge_frame('WorksFor') >>> print(str(e)) { 'name': 'WorksFor', 'source': 'People', 'target': 'Companies', 'schema': [ ['srcid', 'int'], ['trgid', 'int']], 'source_key' : 'srcid', 'target_key' : 'trgid' } >>> edges = e.get_data_pandas()
-
get_edge_frames
(names=None, graph=None)¶ Get a list of EdgeFrame objects present in the xGT server.
An EdgeFrame represents a collection of edges held on the xGT server and can be used to retrieve information about them. EdgeFrame.get_data_pandas() and EdgeFrame.get_data() are used to retrieve member edges. Edge edge in an EdgeFrame shares the same properties, described in EdgeFrame.schema.
- Parameters
names (list of strings or None) – If a list, the list of names of edge frames to retrieve. If None, all edge frames are returned.
- Returns
EdgeFrame objects present in the server.
- Return type
list
Examples
>>> conn = xgt.Connection() >>> print [f.name for f in conn.get_edge_frames()] ['RelatedTo', 'WorksFor']
-
get_jobs
(jobids=None)¶ Get a list of Job objects, each representing the state of the job on the server at the point in time of the invocation of this function.
- Parameters
jobids (list of ints) – A list of job ids for which to return Job objects. By default all jobs are returned.
- Returns
A list of Job objects, each representing the state of a job in the server.
- Return type
list
Examples
>>> conn = xgt.Connection() >>> ... create vertices and edges and run queries ... >>> all_jobs = conn.get_jobs() >>> for j in all_jobs: >>> ... print j id:6, status:completed id:7, status:completed id:8, status:running
-
get_metrics_status
()¶ Check whether the metrics cache is on and finished with updates. A status of metrics_complete is only valid for as long as no vertex or edge frames are modified or created.
- Returns
The status of metrics collection: metrics_completed, metrics_running, or metrics_off.
- Return type
str
Examples
>>> conn = xgt.Connection() >>> conn.get_metrics_status()
-
get_table_frame
(name)¶ Get a TableFrame object that allows interaction with a table present in the xGT server.
A TableFrame object allows for interaction with a table present in the xGT server. For example, a table may be created by a MATCH query and may contain query results. It may also be explicitly created with Connection.create_table_frame().
- Parameters
name (str) – Table name.
- Returns
Frame to the table.
- Return type
Examples
>>> conn = xgt.Connection() >>> ... create graph and run queries ... >>> t = conn.get_table_frame('EmployeeData') >>> print(str(t)) { 'name': 'EmployeeData', 'schema': [ ['person_id', 'int'], ['name', 'text'], ['postal_code', 'int']] } >>> qr1 = 'MATCH (a:EmployeeData) RETURN a.person_id INTO Results1' >>> conn.run_job(qr1) >>> results = conn.get_table_frame('Results1') >>> num_results = results.num_rows >>> results_data = results.get_data_pandas()
-
get_table_frames
(names=None)¶ Get a list of TableFrame objects present in the server.
A TableFrame object allows for interaction with a table present in the xGT server. For example, a table may be created by a MATCH query and may contain query results. It may also be explicitly created with Connection.create_table_frame().
- Parameters
names (list of strings or None) – If a list, the list of names of tables frames to retrieve. If None, all table frames are returned.
- Returns
TableFrame objects representing tables present in the server.
- Return type
list
Examples
>>> conn = xgt.Connection() >>> ... create graph >>> qr1 = 'MATCH (a:Employee) RETURN a.PersonID INTO Results1' >>> conn.run_job(qr1) >>> table_frames = conn.get_table_frames() >>> print [f.name for f in table_frames] ['Results1'] >>> results1_data = conn.get_table_frame('Results1').get_data_pandas()
-
get_vertex_frame
(name)¶ Get a VertexFrame object that allows interaction with a collection of vertices.
A VertexFrame represents a collection of vertices held on the xGT server and can be used to retrieve information about them. VertexFrame.get_data_pandas() and VertexFrame.get_data() are used to retrieve member vertices. Each vertex in a VertexFrame shares the same properties, described in VertexFrame.schema. Each vertex in a VertexFrame is uniquely identified by the property listed in VertexFrame.key.
- Parameters
name (str) – VertexFrame name.
- Returns
Frame to the collection of vertices.
- Return type
Examples
>>> conn = xgt.Connection() >>> v = conn.get_vertex_frame('People') >>> print(str(v)) { 'name': 'People', 'key': 'id', 'schema': [ ['id', 'int'], ['name', 'text']], } >>> print(str(v.num_vertices)) 101 >>> vertices = v.get_data_pandas()
-
get_vertex_frames
(names=None)¶ Get a list of VertexFrame objects present in the xGT server.
A VertexFrame represents a collection of vertices held on the xGT server and can be used to retrieve information about them. VertexFrame.get_data_pandas() and VertexFrame.get_data() are used to retrieve member vertices. Each vertex in a VertexFrame shares the same properties, described in VertexFrame.schema. Each vertex in a VertexFrame is uniquely identified by the property listed in VertexFrame.key.
- Parameters
names (list of strings or None) – If a list, the list of names of vertex frames to retrieve. If None, all vertex frames are returned.
- Returns
VertexFrame objects present in the server.
- Return type
list
Examples
>>> conn = xgt.Connection() >>> print [f.name for f in conn.get_vertex_frames()] ['Companies', 'People'] >>> print [f.num_vertices for f in conn.get_vertex_frames()] [3, 101]
-
property
max_user_memory_size
¶ Returns the maximum amount of memory available for user data on the xGT server.
- Returns
Maximum available user memory, in bytes.
- Return type
int
-
run_job
(query, optlevel=None, timeout=None)¶ Run a TQL query as a job. This function blocks until the job stops running.
- Parameters
queries (str) – One TQL query string.
optlevel (int) –
- The optimization level values are:
0: No optimization.
1: General optimization.
2: WHERE-clause optimization.
3: Degree-cycle optimization.
4: Query order optimization.
Optional. Default=None, which implies a value of ‘4’.
timeout (int) – Maximum number of seconds that the query should take before being automatically canceled. Optional. Default=None where an infinite value is assumed.
- Returns
A Job object for the query.
- Return type
- Raises
XgtError – If the query is not a string (str) or the query text is larger than 209,000 characters.
Examples
>>> conn = xgt.Connection() >>> ... create vertices and edges ... >>> job = conn.run_job('MATCH (a:Employees) RETURN a.person_id INTO Results1') >>> print(job) id:20, status:completed
>>> conn.run_job('MATCH (a) RETURN a.id INTO Results1') ... xgt.common.XgtValueError: Invalid column name: 'id'
-
schedule_job
(query, optlevel=None)¶ Schedule a TQL query as a job. This function returns immediately after scheduling the job.
- Parameters
query (str) – One TQL query string.
optlevel (int) –
- The optimization level values are:
0: No optimization.
1: General optimization.
2: WHERE-clause optimization.
3: Degree-cycle optimization.
4: Query order optimization.
Optional. Default=None, which implies a value of ‘4’.
- Returns
A Job object representing the job that has been scheduled.
- Return type
- Raises
XgtError – If the query is not a string (str) or the query text is larger than 209,000 characters.
Examples
>>> conn = xgt.Connection() >>> ... create vertices and edges ... >>> query = 'MATCH (a:Employees) RETURN a.person_id INTO Results1' >>> job = conn.schedule_job(query) >>> print(job) id:25, status:scheduled
-
property
server_version
¶ Obtains the current product version from the server.
- Returns
Version number.
- Return type
str
-
set_optimization_level
(optlevel=4)¶ Set the optimization level for TQL queries.
- Parameters
optlevel (int) –
- The optimization level values are:
0: No optimization.
1: General optimization.
2: WHERE-clause optimization.
3: Degree-cycle optimization.
4: Query order optimization.
Optional. Default is ‘2’.
-
wait_for_job
(job, timeout=None)¶ Wait for a job. This function blocks until the job stops running.
- Parameters
job (Job, int) – A Job object or an integer job id.
timeout (int) – Number of seconds each job is allowed to execute before being automatically cancelled. Optional. Default=None (no timeout).
- Returns
A Job object representing the state of the job on the server.
- Return type
- Raises
XgtError – If the query is not a string (str) or the query text is larger than 209,000 characters. If one or more query jobs failed.
Examples
>>> conn = xgt.Connection() >>> ... create vertices and edges ... >>> qr1 = 'MATCH (a:Employees) RETURN a.person_id INTO Results1' >>> jb1 = conn.schedule_job(qr1) >>> qr2 = 'MATCH (b:Employees) RETURN b.person_id INTO Results2' >>> jb2 = conn.schedule_job(qr2) >>> jb1 = conn.wait_for_job(jb1) >>> print(jb1) id:31, status:completed >>> jb2 = conn.wait_for_job(jb2) >>> print(jb2) id:32, status:completed
-
wait_for_metrics
(timeout=None)¶ Wait until the metrics cache is finished with updates. This function blocks until there are no more metrics to update or until metrics collection is turned off through the config or until the optional timeout is reached.
- Parameters
timeout (int) – Max number of seconds the function will block. Optional. Default=None (no timeout).
- Returns
Returns True if metrics collection was finished when the function returned. Returns False if metrics collection is not finished (if either metrics collection didn’t complete before the timeout or if metrics cache is off.)
- Return type
bool
Examples
>>> conn = xgt.Connection() >>> finished = conn.wait_for_metrics()