Change Password

Input error
Input error
Input error
Submit
v2.x

Background

Ultipa Graph Middleware, Ultipa Graph Mid-end or Ultipa Graph Platform are all referring to the same thing: Ultipa Graph System or Ultipa Graph Database, both of which are often shortened as Ultipa Graph.

Ultipa Graph is a set of ultra-high-performance graph computing service framework and storage infrastructure.

The Ultipa Graph product matrix contains the followings:

  • World's fastest real-time graph computing engine
  • High-performance, high-availability, persistent storage services
  • Knowledge graph system that are easy to consume and with great visualization and interpretability
  • Feature-rich CLI toolkit
  • High-performance and flexible Import/Export toolkit
  • Easy-to-deploy Docker images
  • SDKs that support mainstream programming languages, and API
  • Super-easy-to-use Graph Query Language: uQL (Ultipa Query Language)

Ultipa Graph supports a rich collection of query methods, loads of ultra high performance graph algorithms, and real-time processing against large amounts of data. One salient feature of Ultipa Graph is that most of the previous T+1 operations are implemented and realized as real-time or T+0 operations, which will save a huge amount of time and effort from the user's perspective. The mission of Ultipa is to empower real-time connection finding for all.

What is UQL

UQL (or uQL) is Ultipa Graph's uniquely high performance query and management language. It's succinct, easy to use (requires minimal cognitive loading), and allows users to query, delete, modify, update, extend, and manage various aspects of Ultipa graph databases and tasks. Users can invoke uQL via Ultipa CLI, Manager or SDK.

Note: The int'l standard of GQL will not be released until mid 2023, uQL will stay compatible.

Terminologies

Name Description
UQL (uQL) Ultipa Query Language, the Ultipa Graph query and database/system management language
Node In graph theory, a node is formally called a 'vertex'. In Ultipa Graph, we call vertex 'node' for simplicity.
Edge Edge usually connects a pair of nodes, or in special cases connects a node to itself. There are directed edge and un-directed edge (un-directed edge is usually a matter concerning how a search against the edge is conducted). Edges in Ultipa Graph are directed.
Direction (In) For an edge pointing from node A to node B, the edge is called an 'In' edge of node B, and is written as either A→B or B←A.
Direction (Out) For an edge pointing from node A to node B, the edge is called an 'Out' edge of node A, and is written as either A→B or B←A.
Path Path is a series of connected nodes and edges, for instance, A→B←C←D→E is a path. In its most simplistic form, an edge is the shortest possible path.
Direction (Left) In a given path A→B←C←D→E, the direction of leftward-pointing edges is Left, such as B←C and C←D.
Direction (Right) In a given path A→B←C←D→E, the direction of rightward-pointing edges is Right, such as A→B and D→E.
Property Data properties within Ultipa Graph system, which are node properties and edge properties.
GraphSet A graphset comprises a set of nodes, edges and their properties, plus settings, privileges and algorithmic operations that can be done against the graphset. In an Ultipa Graph system, multiple graphsets can be included.
Subgraph Subgraph is part of the whole graphset. The result of any query against the whole graphset is considered as a subgraph.
Instance Ultipa Graph system is usually comprised of 1 to multiple instances, and each instance carries the role of a leader or a follower in a cluster environment. An instance can function on its own or communicate and share data with other instances.
Meta-Data In a graph dataset (or database), meta-data refers to the nodes and edges that jointly form the 'skeleton' of the graph.
Filter Filter is frequently used during graph queries for screening meta-data against the value of their properties. Refer to chapter Filter Mechanism for details.
Index Ultipa Graph offers accelerated search against meta-data. Ultipa has general index which is comparable to indexes used in traditional databases, and full-text index which is comparable to keyword searches by web-based search engines.
Fulltext Index Full-text index is to help accelerate text-based searches. Ultipa supports prefix-based fulltext indexing.
LTE Load-to-Engine, which is a way of acceleration used by Ultipa Graph for in-memory meta-data property computing.
UFE Unload-from-Engine, which is the opposite process of LTE.
ULTIPA ID ( _id ) This is the unique id of the meta-data, an integer within int64 assigned (automatically generated) by the Ultipa system.
Original ID ( _o ) This is the original (and supposedly unique) id of nodes before they are imported into Ultipa Graph system. The maximum length of Original ID is 128 bytes. In any extreme case, data longer than 128B will be truncated.
BFS Breadth First Search is a commonly used graph traversal method in graph theory. It starts from the subject node and traverses its neighborhood by visiting its nearest neighbors first, say, its 1st-hop neighbors, then, 2nd-hop neighbors, so on and so forth.
DFS Depth First Search is another way of traversing the graph as illustrated in the above diagram. It will try to reach the designated depth first before reaching shallower depth and will do so recursively until either the entire graph has been visited or the results are satisfying.
Path Query Path queries are commonly used when traversing a graph to find relevant paths connecting two (groups of) nodes that form a subgraph. Path queries may be implemented with BFS or DFS.
Shortest Path Shortest Path is a special kind of path query. Regular shortest path is always implemented with BFS. Weighted shortest path, or least-weighted path, which sums the weight of all edges, can be implemented with either DFS or BFS, depending on the underpinning data-structure or code-engineering mechanism.
K-Hop K-hop is a typical and fundamental graph operation (or query). K-hop, or K-hop neighbors, simply means all nodes that are at least K-step away from the subject node; in another word, the shortest paths between these nodes and the subject node have K steps! For instance, a node's 1-hop dataset contains all nodes that are directly connected with it. By definition, K-hop should always be implemented with BFS, not DFS.
Template Templates are leveraged by template-based query for graph querying, an Ultipa inventive query method that is far more flexible than regular path or k-hop query, as it configures the path as a series of sub-paths hence allows powerful and sophisticated filtering logics to be defined. For more information about template-based query, refer to chapter Template-Based Query.
Graph Algorithm Graph Algorithms in Ultipa Graph system are encapsulated (for easy operations) and meant to be running extremely fast compared to any other graph system. Most graph algorithms run in real-time or near-time fashion instead of costing T+1 or longer waiting time. Ultipa offers a rich collection of algorithms, amounting to over 35 and continuously growing. Ranging from centrality, ranking, propagation, community detection, graph-embedding, etc. For more information about Graph Algorithms, refer to the algorithm handbook.
Graph Embedding Graph Embedding is loosely defined as a subset of graph algorithms including, but not limited to, random walk, node2vec, struc2vec, LINE and others.
* If the contents are annotated with *, the relevant feature is being developed.
Experimental feature, use with caution.

Specification

The goal of uQL is to help any Ultipa Graph user to master the gist of Ultipa Graph systems with ease and celerity. uQL follows the below usage specification, and this section is dedicated to helping the readers to understand the basic frameworks of uQL.

Chaining & Functional Style

All uQLs use functional chaining style, such as a().b().c().d()…

Note: uQL is case-sensitive!

Why does Ultipa not use Cypher or SQL like format as its query language?

  • Cypher or SQL are NOT suitable for high-dimensional data and their combinations, such as paths, nodes, edges, properties and collection operations;
  • Cypher or SQL are NOT capable of, and NOT efficient in path-query, template-based search or whole graph traversals;
  • Cypher or SQL languages are NOT intuitive, and require lots of cognitive loading when doing sophisticated queries (such as layers of encapsulation and table joins…)

Features of uQL:

  • Supports multiple dimensional (heterogeneous) data;
  • Supports subgraph paths, node-edge, properties, table and other advanced data structures;
  • Easy to do dynamic and real-time graph pruning;
  • Easy to write, use or comprehend, requires minimal cognitive loading;
  • Chaining style is naturally a path that's easy for human comprehension;
  • Hot-pluggable algorithms, highly extensible;
  • Super high performance.

Query Mechanism

The lifecycle of a uQL is like below:

  • An Ultipa system user sends the uQL to the system that offers Ultipa services;
  • Ultipa services interprets and optimizes the uQL, and sends it further to the high-performance graph computing (and storage) engine;
  • The engine returns matching results back to the user.

Commands, Parameters and Returns

uQL is comprised of 4 types of components:

Component Type Description
Command Be used in all uQLs and appears only once in each uQL
Parameter Be used in most uQLs
Configuration Be used in algorithmic uQLs
Return Be used in query uQLs

camelCase Style Commands

camelCase style commands are commonly used in uQL. Such as:

Command Description
createIndex() Create index
showIndex() Show existing index
showTask() Show current tasks

Most uQL commands other than meta-data related follow the camelCase style.

Combinational Commands

Commands combined with a parameter are combinational commands to operate against meta-data and their properties. Such as:

Command Description
find().nodes() Find nodes
show().node_property() Show node properties
delete().edges() Delete edges

For details on meta-data related operations, please refer to chapters Instance, GraphSet and Property and chapter Meta-Data.

Parameters

A uQL may contain one or more parameters or no parameter. The order of parameters in the uQL will not affect the functionality of most of uQLs except template-based query, even though the are still illustrated in seemingly regular order for better understanding. Such as:

uQL Parameters
find().nodes(<filter>).limit(<int>) nodes(), limit()
ab().src(<id>).dest(<id>).depth(<int>).direction(<dir>) src(), dest(), depth(), direction()
showTask() (none)

Configurations

Configurations, often in the form of parameter settings, are used by Ultipa Algorithms to govern how the algorithm will be executed. They can be considered as parameters at a deeper level.

Configuration items and their values are encapsulated in params() and written as an object. Such as:

uQL Configuration Items
algo(degree).params({id: <id>, edge_property_name: <string>}) id, edge_property_name
algo(page_rank).params({loop_num:<int>, damping:<float>}) loop_num, damping
algo(degree_all) (none)

Returns

A return parameter specifies what particular information of a query is to be returned. Such as:

uQL Return
find().nodes(<filter>).select(<property>) select()
t().n(<alias><filter>).e(<filter>).n(<filter>).return(<alias>) return()

Operations not requiring a return parameter, e.g. CUD (Create/Update/Delete), usually has operational status returned by the system.

Ultipa Filters

Ultipa filter doesn't come in the form of any aforementioned uQL components but is frequently used by uQL parameters to screen the meta-data during the operation, against meta-data properties.

Similar to configurations, Ultipa filter writes its items (the properties to be filtered against) and their criteria as an object. Such as:

uQL Filter Items
find().edges({_from_id: <int>, name: <string>}).select(<property>) _from_id, name
delete().nodes({balance: {$gt: <double>}}) balance

For details on uQL's filter mechanism, please refer to chapter Filter Mechanism.

Reserved Words

uQL has a bunch of reserved keywords that are used, oftentimes, implicitly by Ultipa Graph system.

There are 2 types of reserved keywords:

  1. Reserved Property Name
  2. Reserved Template Alias Name

Reserved Property Name

Properties like _o, _id _from_id, _to_id are reserved properties.

Reserved Properties Description
_o Original ID, a string less than 128 bytes, which is the original ID of nodes before data gets imported into Ultipa Graph system
_id Node's ID or edge's ID, a number within iny64, which is generated by Ultipa automatically and mapping to _o
_from_o the _o of the edge's starting node
_to_o the _o of the edge's ending node
_from_id the _id of the edge's starting node
_to_id the _id of the edge's ending node
#.... Any property whose name starts with '#' is a system-generated property. For instance, the Louvain community detection graph algorithm will automatically write back and create (or upsert) a node property called #louvain
~.... Any filter item with '~' attaching in the front is a reference to property that has been set as fulltext index. For instance, in filter { ~nodeDesc: "Graph Ultipa" } the ~nodeDesc is a reference to the fulltext index nodeDesc

Reserved Alias Name

Reserved Alias Description
prev_n The previous node in the recursive logic in a template query operation
prev_e The previous edge in the recursive logic in a template query operation