Ultipa graph algorithms can be executed with both GQL and UQL through Ultipa Manager, Ultipa CLI, or by integrating Ultipa Drivers into your applications. Drivers are available for Java, Python, Go, Node.js, and C#.
Algorithm Results
The results of an algorithm's execution include primary results and optionally, statistical summaries.
- Primary results deliver the algorithm’s core outputs, such as node rankings, pairwise similarities, or calculated metrics.
- Statistical summaries, when available, offer aggregated insights, including averages, sums, or distribution details, to support further analysis of the primary results.
Execution Modes
Algorithms are run using one of the execution modes: File Writeback, DB Writeback, Stats Writeback, Full Return, Stream Return, and Stats Return.
File Writeback
The algorithm runs as a job in this mode with primary results written to files, and statistical summaries saved to the job when available, facilitating later access. This is useful for handling large outputs without returning data directly to the client, especially when offline storage or later processing is required.
CALL algo.<algoName>.write("<projectName>", {
params: {
...
},
return_params: {
file: {
<filename_item1>: "<fileName1>",
<filename_item2?>: "<fileName2?>",
...
}
}
})
algo(<algoName>).params({
project: "<projectName>",
...
}).write({
file: {
<filename_item1>: "<fileName1>",
<filename_item2?>: "<fileName2?>",
...
}
})
Details
- You can specify the output file extension (like
.csv
or.txt
) or leave it unspecified, in which case the system may use a default or a generic format.
DB Writeback
The algorithm runs as a job in this mode, writing certain columns from its primary results directly to designated node properties within the database for permanent storage, and statistical summaries saved to the job when available. This allows data to be readily accessible for future queries or analyses.
CALL algo.<algoName>.write("<projectName>", {
params: {
...
},
return_params: {
db: {
property: "<propertyName>"
}
}
})
algo(<algoName>).params({
project: "<projectName>",
...
}).write({
db: {
property: "<propertyName>"
}
})
Details
DB writeback applies to all nodes in the graph, writing results to specified properties without needing label (schema) definitions.
- If a property doesn’t exist for a label, it will be created.
- If a property does exist for a label, existing values are overwritten.
- Writeback fails for certain labels only if there is a mismatch in data type between existing properties and new results.
- For nodes with algorithm results, those values are stored in the properties; nodes without results receive a default, such as 0 or an empty string, depending on the result type.
Stats Writeback
The algorithm runs as a job in this mode. The statistical summaries from the execution are saved along with the job.
CALL algo.<algoName>.write("<projectName>", {
params: {
...
},
return_params: {
stats: {
<stats1?>: <boolean?>,
<stats2?>: <boolean?>,
...
}
}
})
algo(<algoName>).params({
project: "<projectName>",
...
}).write({
stats: {
<stats1?>: <boolean?>,
<stats2?>: <boolean?>,
...
}
})
Details
- You can leave
stats
empty to save all statistical summaries to the job. Alternatively, you can specify individual summary items withinstats
, setting them totrue
orfalse
to save only the desired summaries.
Full Return
The algorithm runs as a real-time process in this mode. The algorithm completes execution and then returns all results along with any statistical summaries in a single response to the client.
CALL algo.<algoName>("<projectName>", {
params: {
...
},
return_params: {}
}) YIELD <resultsAlias>, <statsAlias?>
RETURN <resultsAlias>, <statsAlias?>
exec{
algo(<algoName>).params({
...
}) as <resultsAlias>, <statsAlias?>
return <resultsAlias>, <statsAlias?>
} on <projectName>
Details
- For algorithms that produce statistical summaries, you can declare two aliases: the first for primary results, and the second for the statistical summaries. If an algorithm doesn’t generate statistical summaries, only a single alias can be declared for its results.
Stream Return
The algorithm runs as a real-time process in this mode. The primary results are streamed progressively to the client as they are generated. This mode optimizes resource usage and grants quicker access to results, beneficial for applications needing immediate feedback.
CALL algo.<algoName>("<projectName>", {
params: {
...
},
return_params: {type: "stream"}
}) YIELD <resultsAlias>
RETURN <resultsAlias>
exec{
algo(<algoName>).params({
...
}).stream() as <resultsAlias>
return <resultsAlias>
} on <projectName>
Details
- The stream return mode doesn't produce any statistical summaries.
Stats Return
The algorithm runs as a real-time process in this mode. The algorithm completes execution and then returns any statistical summaries to the client.
CALL algo.<algoName>("<projectName>", {
params: {
...
},
return_params: {type: "stats"}
}) YIELD <statsAlias>
RETURN <statsAlias>
exec{
algo(<algoName>).params({
...
}).stats() as <statsAlias>
return <statsAlias>
} on <projectName>
Running HDC or Distributed Algorithms
All Ultipa graph algorithms are available in the HDC version, and some are also offered in the distributed version. When both versions are available for an algorithm (e.g., Louvain), they may have different parameter sets.
The HDC and distributed algorithm versions also differ in their support for the execution modes:
Execution Mode | HDC Algorithm | Distributed Algorithm |
---|---|---|
File Writeback | Yes | Yes |
DB Writeback | Yes | Yes |
Stats Writeback | Yes | No |
Full Return | Yes | No |
Stream Return | Yes | No |
Stats Return | Yes | No |
Each projection type is designed to run specific algorithms: HDC projections for HDC algorithms and distributed projections for distributed algorithms. The selection of algorithm version depends on the type of projection specified for execution.