TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Graph Search and Management

Functions for use of graph datbases. More...

Functions

int TdbGraphAddVertex (TdbHandle *recordControl, const char *recordName, const char *label, TdbHandle referenceRecord)
 Create a simple in-graph vertex record.
 
int TdbGraphAnalysisSnapshot (int *context, int *count, int mode)
 Returns path count statistics from an on-going analysis.
 
int TdbGraphClosePathAnalysis (int **context)
 Terminate a graph path analysis operation and release any resources allocated to it.
 
int TdbGraphFind (int *resultSet, int sourceSet, int edgeSet, int targetSet, int exclusionSet, const char *condition)
 Locate the direct relationships between two sets of records.
 
int TdbGraphGetPath (int *context, char **edge, double *weight, char **database, int *recordId)
 Returns information on a path found by a graph analysis operation.
 
int TdbGraphNextPath (int *context, char **database, int *recordId)
 Advances to the next path from a completed analysis result.
 
int TdbGraphPathAnalysisStep (int *context)
 Perform one iteration of a graph path analysis operation.
 
int TdbGraphRecAssoc (TdbHandle *recordControl, const char *recordName, const char *edgeName, TdbHandle sourceRecord, TdbHandle targetRecord, double weight)
 Create a graph edge between two existing TRIP records.
 
int TdbGraphResolve (int *resultSet, int mode, int edgeSet, const char *database)
 Create a search set of the vertices associated by the edges in a graph search set.
 
int TdbGraphStartPathAnalysis (int **context, int algorithm, int maxDepth, int originSet, int edgeSet, int destinationSet, boolean reverse, const char *condition)
 Initialize a graph path analysis operation.
 
int TdbGraphTransitive (int *resultSet, int maxDepth, boolean reverse, boolean allEdges, int edgeSet, int sourceSet, int targetSet, const char *condition)
 Perform a transitive search in a graph datanase.
 

Detailed Description

Functions for use of graph datbases.

The graph functions provides access to manipulation and querying of TRIP graph databases.

Function Documentation

◆ TdbGraphAddVertex()

int TdbGraphAddVertex ( TdbHandle *  recordControl,
const char *  recordName,
const char *  label,
TdbHandle  referenceRecord 
)

Create a simple in-graph vertex record.

Parameters
recordControl[IN/OUT] Supply a record control set with write permissions to the graph database in which to create the vertex, or pass a pointer to a NULL record control in order to use the graph database currently open for search. The parameter may also be set to NULL (in contrast to a pointer to a variable holding NULL) if the vertex is to be committed by this function and the record control is not required as output. On output, this parameter receives the record control was supplied or (in case a pointer to a NULL variable was supplied) created by this function. If the parameter was set to NULL on input, nothing is returned. In case a record control is returned, the caller is responsible for its release.
recordName[IN] Pass the record name to assign the vertex record to create, or an empty string in order to automatically generate a unique ID if a record name is not already defined.
label[IN] The label to assign the vertex record. This label is required but does not necessarily have to be unique.
referenceRecord[IN] Optional. Record control referring to another record that this in-graph record will reference. Such reference records can be used to hold additional data for the vertex that do not fit within the defined structure of a graph database.
Returns
1 or other odd value on success, even value on error

Description

This function creates a simple in-graph vertex record, optionally by referencing another (non-graph) record with additional information.

Unless the recordControl parameter is set to NULL, the caller will be responsible for committing the record using TdbPutRecord() and for the release of the record control using TdbDeleteRecordControl().

Privileges Required

The current TRIPsystem user needs write access to the graph database in which the vertex record is to be created.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()

◆ TdbGraphAnalysisSnapshot()

int TdbGraphAnalysisSnapshot ( int *  context,
int *  count,
int  mode 
)

Returns path count statistics from an on-going analysis.

Parameters
contextContext handle referring to an on-going graph path analysis.
countOutput parameter. Receives the number of paths found so far.
modePass non-zero to retrieve the count of candidate paths and zero to retrieve the count of completed paths.
Returns
1 or other odd value on success, even value on error

Description

This function reports the current analysis state in terms of counts of candidate paths (for non-zero mode) and completed paths (if mode is set to zero).

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphClosePathAnalysis()

int TdbGraphClosePathAnalysis ( int **  context)

Terminate a graph path analysis operation and release any resources allocated to it.

Parameters
contextContext handle referring to the graph path analysis to close.
Returns
1 or other odd value on success, even value on error

Description

This function terminates a graph path analysis operation as initialized by TdbGraphStartPathAnalysis() function. Failure to call this function after a completed path analysis will cause memory leaks.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphFind()

int TdbGraphFind ( int *  resultSet,
int  sourceSet,
int  edgeSet,
int  targetSet,
int  exclusionSet,
const char *  condition 
)

Locate the direct relationships between two sets of records.

Parameters
resultSetThe resulting search set, consisting of a set of edges from the graph database
sourceSetThe set of vertex records that the edges to locate have as origin. Pass 0 (zero) to indicate that all vertices are to be included in the search. This set can be from any database, graph or otherwise.
edgeSetA set of edge records from the current graph database, indicating the sub-graph to query. Pass 0 (zero) to use all edges in the graph database.
targetSetThe set of vertex records that the edges to locate have as destination. Pass 0 (zero) to indicate that all vertices are to be included in the search. This set can be from any database, graph or otherwise.
exclusionSetA set of edge records to explicitly not include in the search result. Pass 0 (zero) to indicate that no exclusion set is to be used.
conditionAn extra CCL condition to apply to the graph edges. Must be specified without the command keyword (e.g. FIND). If no extra condition is needed, pass an empty string.
Returns
1 or other odd value on success, even value on error

Description

The TdbGraphFind() function queries a graph database for direct (non-transitive) relationships between any two records. The database currently open for search must be a graph database.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphGetPath()

int TdbGraphGetPath ( int *  context,
char **  edge,
double *  weight,
char **  database,
int *  recordId 
)

Returns information on a path found by a graph analysis operation.

Parameters
contextContext handle referring to a completed graph path analysis.
edgeOutput parameter. Receives a pointer to the name of the next edge in the path.
weightOutput parameter. Receives the weight value for the edge.
databaseOutput parameter. Receives a pointer to the name of the database in which the current edge's destination vertex is stored.
recordIdOutput parameter. Receives the record ID number for the current edge's destination vertex.
Returns
1 or other odd value on success, even value on error

Description

This function reports info on an edge and its destination vertex from a path and advances the location one step. This function is called repatedly until all the info on the current path has been returned. A call to the TdbGraphNextPath() function is required to advance to the next path.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 No more data is available on the current path.
See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphNextPath()

int TdbGraphNextPath ( int *  context,
char **  database,
int *  recordId 
)

Advances to the next path from a completed analysis result.

Parameters
contextContext handle referring to a completed graph path analysis.
databaseOutput parameter. Receives a pointer to the name of the database in which the start vertex of the path is stored.
recordIdOutput parameter. Receives the record ID number for the start vertex of the path.
Returns
1 or other odd value on success, even value on error

Description

This function advances the context to report the next path from a completed analysis result and returns information on the first vertex of the path. To read data for the rest of the path, use the TdbGraphGetPath() function.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 No more paths are available in the analysis context.
See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphPathAnalysisStep()

int TdbGraphPathAnalysisStep ( int *  context)

Perform one iteration of a graph path analysis operation.

Parameters
contextContext handle referring to the graph path analysis for which to execute another iteration.
Returns
1 or other odd value on success, even value on error

Description

This function executes a single iteration of a graph path analysis. An iteration involves finding edges level "down" into the graph and evaluate the paths available so far. Execute this function repeatedly while returns 1 or any other success code. The error code 226 (no hits) is returned when the analysis is completed.

The analysis is initialized by a call to the TdbGraphStartPathAnalysis() function. Use this function to find any path or the shortest path between two sets of vertices. Execute the analysis by calling TdbGraphPathAnalysisStep() until it reports that the analysis is complete. To examine intermediary states during analysis, call the TdbGraphAnalysisSnapshot() function. To examine the results of a completed analysis, use the TdbGraphNextPath() and TdbGraphGetPath() functions. When all done, release the analysis context by calling the TdbGraphClosePathAnalysis() function.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
226 No hits! The graph analysis is completed.
See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphRecAssoc()

int TdbGraphRecAssoc ( TdbHandle *  recordControl,
const char *  recordName,
const char *  edgeName,
TdbHandle  sourceRecord,
TdbHandle  targetRecord,
double  weight 
)

Create a graph edge between two existing TRIP records.

Parameters
recordControl[IN/OUT] Supply a record control set with write permissions to the graph database in which to create the edge, or pass a pointer to a NULL record control in order to use the graph database currently open for search. The parameter may also be set to NULL (in contrast to a pointer to a variable holding NULL) if the edge is to be committed by this function and the record control is not required as output. On output, this parameter receives the record control was supplied or (in case a pointer to a NULL variable was supplied) created by this function. If the parameter was set to NULL on input, nothing is returned. In case a record control is returned, the caller is responsible for its release.
recordName[IN] Pass the record name to assign the edge record to create, or an empty string in order to automatically generate a unique ID if a record name is not already defined.
edgeName[IN] Name of the edge to create
sourceRecord[IN] Record control referring to the record to use as source vertex
targetRecord[IN] Record control referring to the record to use as target vertex
weight[IN] Receives the weight value for the edge.
Returns
1 or other odd value on success, even value on error

Description

This function creates a graph edge record that associates two existing TRIP records. Unless the recordControl parameter is set to NULL, the caller will be responsible for committing the record using TdbPutRecord() and for the release of the record control using TdbDeleteRecordControl().

Privileges Required

The current TRIPsystem user needs write access to the graph database in which the edge record is to be created.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphAddVertex()

◆ TdbGraphResolve()

int TdbGraphResolve ( int *  resultSet,
int  mode,
int  edgeSet,
const char *  database 
)

Create a search set of the vertices associated by the edges in a graph search set.

Parameters
resultSetThe resulting search set, consisting of a set of vertex records.
modeIndicates what to resolve. Pass either GRAPH_RESOLVE_SOURCE (1) to resolve the origin records of the edges, or GRAPH_RESOLVE_TARGET (2) to resolve the destination records of the edges.
edgeSetA search set with edge records from a graph database. The vertex records to resolve are the ones that these edges associate.
databaseRestrict resolution to vertex records in this database only. Pass an empty string to resolve all records regardless of database.
Returns
1 or other odd value on success, even value on error

Description

The TdbGraphResolve() resolves an edge set ( as produced by a function such as TdbGraphFind() ) into a set of vertex records. The resulting set is formed from either the origins of the edges or the destinations of the edges.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphTransitive()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphStartPathAnalysis()

int TdbGraphStartPathAnalysis ( int **  context,
int  algorithm,
int  maxDepth,
int  originSet,
int  edgeSet,
int  destinationSet,
boolean  reverse,
const char *  condition 
)

Initialize a graph path analysis operation.

Parameters
contextOutput parameter. Receives a handle to the initialized analysis.
algorithmDetermine how the path analysis is to be performed on a general level. Valid values are GRAPH_PATH_ALL (1) to find all possible routes, and GRAPH_PATH_SHORTEST (2) that locates the shortest (or least expensive) route.
maxDepthDetermine how far away from the vertices in the origin set that the analysis is allowed to traverse.
originSetA set of vertex records that are to be used as starting points for the analysis.
edgeSetThe edge set to query. Pass 0 (zero) to use all all the edges in the current graph database.
destinationSetA set of vertex records that are to be used as destination points for the analysis.
reversePass false to perform the analysis in the defined direction of the edges, or true to perform the analysis in reverse (from destination to origin).
conditionAn extra CCL condition to apply to the graph edges. Must be specified without the command keyword (e.g. FIND). If no extra condition is needed, pass an empty string.
Returns
1 or other odd value on success, even value on error

Description

The TdbGraphStartPathAnalysis() function prepares the TRIP kernel for a graph path analysis operation. Use this function to find any path or the shortest path between two sets of vertices. Execute the analysis by calling TdbGraphPathAnalysisStep() until it reports that the analysis is complete. To examine intermediary states during analysis, call the TdbGraphAnalysisSnapshot() function. To examine the results of a completed analysis, use the TdbGraphNextPath() and TdbGraphGetPath() functions. When all done, release the analysis context by calling the TdbGraphClosePathAnalysis() function.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphTransitive()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()

◆ TdbGraphTransitive()

int TdbGraphTransitive ( int *  resultSet,
int  maxDepth,
boolean  reverse,
boolean  allEdges,
int  edgeSet,
int  sourceSet,
int  targetSet,
const char *  condition 
)

Perform a transitive search in a graph datanase.

Parameters
resultSetThe resulting search set, consisting of a set of edges from the graph database.
maxDepthThe maximum traversal depth to which to perform the search.
reversePass true to perform the search in the opposite to the defined direction of the edges. Pass false to follow edges in their defined direction.
allEdgesPass true return a set of all traversed edges, and false to return a set that only consists of the most distant edges found.
edgeSetThe edge set to query. Pass 0 (zero) to use all all the edges in the current graph database.
sourceSetThe set of vertex records at which the transitive search is to start.
targetSetThe set of vertex records to which to limit found edges to. If specified, only edges that have these vertices as destination (if reverse is false) or as origin (if reverse is true) will be considered. Note that this set restricts all the vertices processed by the transitive search - not only the vertices at the very end of the search. Pass 0 (zero) to use all possible vertices.
conditionAn extra CCL condition to apply to the graph edges. Must be specified without the command keyword (e.g. FIND). If no extra condition is needed, pass an empty string.
Returns
1 or other odd value on success, even value on error

Description

The TdbGraphTransitive() function queries a graph database for relationships such that zero or more vertices may have to be traversed to get from origin to destination. The database currently open for search must be a graph database.

Since

This function was introduced in TRIP version 7.1-0.

Return Codes

The number of steps this function performs is such that a significant number of return codes may be expected. They are therefore not listed here. Please refer to the error codes list in this reference manual for explanations to any code returned.

See also
TdbGraphFind()
TdbGraphResolve()
TdbGraphStartPathAnalysis()
TdbGraphPathAnalysisStep()
TdbGraphClosePathAnalysis()
TdbGraphAnalysisSnapshot()
TdbGraphNextPath()
TdbGraphGetPath()
TdbGraphRecAssoc()
TdbGraphAddVertex()