TRIPsystem Kernel API 8.3
|
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. | |
Functions for use of graph datbases.
The graph functions provides access to manipulation and querying of TRIP graph databases.
int TdbGraphAddVertex | ( | TdbHandle * | recordControl, |
const char * | recordName, | ||
const char * | label, | ||
TdbHandle | referenceRecord | ||
) |
Create a simple in-graph vertex record.
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. |
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().
The current TRIPsystem user needs write access to the graph database in which the vertex record is to be created.
This function was introduced in TRIP version 7.1-0.
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.
int TdbGraphAnalysisSnapshot | ( | int * | context, |
int * | count, | ||
int | mode | ||
) |
Returns path count statistics from an on-going analysis.
context | Context handle referring to an on-going graph path analysis. |
count | Output parameter. Receives the number of paths found so far. |
mode | Pass non-zero to retrieve the count of candidate paths and zero to retrieve the count of completed paths. |
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).
This function was introduced in TRIP version 7.1-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGraphClosePathAnalysis | ( | int ** | context | ) |
Terminate a graph path analysis operation and release any resources allocated to it.
context | Context handle referring to the graph path analysis to close. |
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.
This function was introduced in TRIP version 7.1-0.
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.
int TdbGraphFind | ( | int * | resultSet, |
int | sourceSet, | ||
int | edgeSet, | ||
int | targetSet, | ||
int | exclusionSet, | ||
const char * | condition | ||
) |
Locate the direct relationships between two sets of records.
resultSet | The resulting search set, consisting of a set of edges from the graph database |
sourceSet | The 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. |
edgeSet | A 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. |
targetSet | The 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. |
exclusionSet | A 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. |
condition | An 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. |
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.
This function was introduced in TRIP version 7.1-0.
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.
int TdbGraphGetPath | ( | int * | context, |
char ** | edge, | ||
double * | weight, | ||
char ** | database, | ||
int * | recordId | ||
) |
Returns information on a path found by a graph analysis operation.
context | Context handle referring to a completed graph path analysis. |
edge | Output parameter. Receives a pointer to the name of the next edge in the path. |
weight | Output parameter. Receives the weight value for the edge. |
database | Output parameter. Receives a pointer to the name of the database in which the current edge's destination vertex is stored. |
recordId | Output parameter. Receives the record ID number for the current edge's destination vertex. |
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.
This function was introduced in TRIP version 7.1-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | No more data is available on the current path. |
int TdbGraphNextPath | ( | int * | context, |
char ** | database, | ||
int * | recordId | ||
) |
Advances to the next path from a completed analysis result.
context | Context handle referring to a completed graph path analysis. |
database | Output parameter. Receives a pointer to the name of the database in which the start vertex of the path is stored. |
recordId | Output parameter. Receives the record ID number for the start vertex of the path. |
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.
This function was introduced in TRIP version 7.1-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | No more paths are available in the analysis context. |
int TdbGraphPathAnalysisStep | ( | int * | context | ) |
Perform one iteration of a graph path analysis operation.
context | Context handle referring to the graph path analysis for which to execute another iteration. |
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.
This function was introduced in TRIP version 7.1-0.
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. |
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.
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. |
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().
The current TRIPsystem user needs write access to the graph database in which the edge record is to be created.
This function was introduced in TRIP version 7.1-0.
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.
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.
resultSet | The resulting search set, consisting of a set of vertex records. |
mode | Indicates 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. |
edgeSet | A search set with edge records from a graph database. The vertex records to resolve are the ones that these edges associate. |
database | Restrict resolution to vertex records in this database only. Pass an empty string to resolve all records regardless of database. |
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.
This function was introduced in TRIP version 7.1-0.
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.
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.
context | Output parameter. Receives a handle to the initialized analysis. |
algorithm | Determine 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. |
maxDepth | Determine how far away from the vertices in the origin set that the analysis is allowed to traverse. |
originSet | A set of vertex records that are to be used as starting points for the analysis. |
edgeSet | The edge set to query. Pass 0 (zero) to use all all the edges in the current graph database. |
destinationSet | A set of vertex records that are to be used as destination points for the analysis. |
reverse | Pass false to perform the analysis in the defined direction of the edges, or true to perform the analysis in reverse (from destination to origin). |
condition | An 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. |
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.
This function was introduced in TRIP version 7.1-0.
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.
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.
resultSet | The resulting search set, consisting of a set of edges from the graph database. |
maxDepth | The maximum traversal depth to which to perform the search. |
reverse | Pass true to perform the search in the opposite to the defined direction of the edges. Pass false to follow edges in their defined direction. |
allEdges | Pass true return a set of all traversed edges, and false to return a set that only consists of the most distant edges found. |
edgeSet | The edge set to query. Pass 0 (zero) to use all all the edges in the current graph database. |
sourceSet | The set of vertex records at which the transitive search is to start. |
targetSet | The 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. |
condition | An 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. |
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.
This function was introduced in TRIP version 7.1-0.
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.