Query

3.1 UQL Query

  • Composite a valid uQL statement for the custom query:
from ultipa import Connection,ULTIPA_REQUEST
conn = Connection(host='host:port', username="root", password="root")
ret = conn.uql("find().nodes().limit(10).select(*)")
print(ret.toJSON())
ret = conn.uql("find().edges().limit(10).select(*)")
print(ret.toJSON())
  • Below are methods encapsulated for different query purposes.

3.2 Node Query

from ultipa import Connection,ULTIPA_REQUEST
conn = Connection(host='host:port', username="root", password="root")
ret = conn.searchNode(ULTIPA_REQUEST.SearchNode())
print(ret.toJSON())

3.3 Edge Query

from ultipa import Connection,ULTIPA_REQUEST
conn = Connection(host='host:port', username="root", password="root")
ret = conn.searchEdge(ULTIPA_REQUEST.SearchEdge())
print(ret.toJSON())

3.4 A-to-B Path Query

  • A-to-B path query is to query the paths satisfying a depth restriction between two nodes in the current graphset. The returned paths can be all the paths with depth below a fixed number, or the paths with the shortest depth among all paths found.

  • The supported parameters are:

    name type rule description
    src int >0, required The Ultipa ID of the starting node
    dest int >0, required The Ultipa ID of the ending node
    depth int >0, <30, defaults 1 The maximum depth of path
    shortest string / The edge property used as weight factor for calculating path weight
    limit int >0, defaults 1 The number of results to return
    select []string / A list of node & edge properties to return
    select_node_properties []string / A list of node properties to return
    select_edge_properties []string / A list of edge properties to return
    node_filter filter Ultipa filter Filter on all nodes (except the starting node and ending node)
    edge_filter filter Ultipa filter Filter on all edges
    path_ascend str / The edge property ascending along the path
    path_descend str / The edge property descending along the path
    direction str left,right Filter on edge direction
    turbo / / Enable turbo acceleration mode
    no_circle / / Dismiss the paths with circles
    osrc str Cannot be used with src The original ID of the starting node
    odest str Cannot be used with dest The original ID of the ending node
  • Example: Find the path between node (_id = 12) and node (_id = 21) whose depth is no greater than 3, and return 5 results:

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    ret =  conn.searchAB(ULTIPA_REQUEST.SearchAB(src=12,dest=21,depth=3,limit=5))
    print(ret.toJSON())
    

3.5 K-Hop Query

  • K-Hop query searches for neighbor nodes that can be reached in the shortest K steps from a node, and returns the neighbor nodes and statistical data (the number of all nodes found). For example, K-Hop query can be used to calculate the number of neighbors that can be reached on the 3rd step from a node and return all or part of the results.

  • The supported parameters are:

    name type rule description
    src int >0, required The Ultipa ID of the starting node
    depth int >0, <30, defaults 1 The depth of query
    limit int >0, defaults 1 The number of results to return
    select []string / A list of node & edge properties to return
    select_node_properties []string / A list of node properties to return
    select_edge_properties []string / A list of edge properties to return
    node_filter filter Ultipa filter Filter on all nodes (except the starting node)
    edge_filter filter Ultipa filter Filter on all edges
    direction str left,right Filter on edge direction
    osrc str Cannot be used with src The original ID of the starting node
  • Example: Find the 1-step neighbor of node (id = 12), return 10 results and the total:

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    ret =  conn.searchKhop(ULTIPA_REQUEST.Searchkhop(src=12,depth=1,limit=10))
    print(ret.toJSON())
    

3.6 Spread Query

  • Spread query is to spread from a specific node in BFS fashion for its neighborhood information, and return all the meta-data in the shortest paths. It has the same parameters with K-Hop query.

  • Example: Spread from node (id = 12), return all the nodes and edges of 10 results within 3 steps:

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    ret =  conn.nodeSpread(ULTIPA_REQUEST.NodeSpread(src=12,depth=3,limit=10))
    print(ret.toJSON())
    

3.7 Auto-net Query

  • Auto-net query is to find the paths between two gourps of node in two modes:

    • Find the paths from N nodes to themselves, pair by pair.
    • Find the paths from N nodes to M nodes, pair by pair.
  • The two modes of automatic networking share the same parameters as follows:

    name type rule description
    srcs []int >0, required The Ultipa ID of the starting nodes
    dests []int >0 The Ultipa ID of the ending nodes (for mode 2)
    depth int >0, Defaults 1 The depth of query
    limit int >0, Defaults 1 The number of results to return
    select []string / A list of node & edge properties to return
    select_node_properties []string / A list of node properties to return
    select_edge_properties []string / A list of edge properties to return
    shortest / / To return the shortest path
    node_filter filter Ultipa filter Filter on all nodes (except the starting node)
    edge_filter filter Ultipa filter Filter on all edges
    turbo / / Enable turbo acceleration mode
    no_circle / / Dismiss the paths with circles
  • Example: Form a network using nodes ( id = [12,21,30,40]), search depth = 3, limit to 2 paths between each pair of nodes, return 'name' and 'age':

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    ret = conn.autoNet(ULTIPA_REQUEST.AutoNet(srcs=[12,21,30,40],depth=3,
                                          limit=2,select=['name','age']))
    print(ret.toJSON())
    

3.8 Template Query

  • Template query abstracts a sub-graph according to certain matching rules, and returns part or all of the result. The user can specify what starting nodes to start from, what edges and nodes to pass, and how to filter each step. Eventually the defined ending nodes are reached.

  • Template query allows the sub-graph to be precisely trimmed according to business needs. The concept of 'alias' is introduced to facilitate the flexibility of template query.

    • The [command] of template query is t(), where t is the abbreviation of template.

    • The [Parameter] and [Return] of the template query are slightly different. This part will be divided into subsections to describe the usage.

  • The parameters supported by the template are:

    name type rule description
    limit int >0 ,Required The number of paths to return
    n Node template / See the node template chapter for details
    e Edge template / See the edge template chapter for details
  • Example: Search for 1-step paths from node to node, return 5 results and all the nodes and edges in the paths:

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    item1 = ULTIPA_REQUEST.TemplateNodeItem(name=ULTIPA_REQUEST.TNodeItem.n, alias='n1')
    item2 = ULTIPA_REQUEST.TemplateEdgeItem(name=ULTIPA_REQUEST.TEdgeItem.e, alias='e')
    item3 = ULTIPA_REQUEST.TemplateNodeItem(name=ULTIPA_REQUEST.TNodeItem.n, alias='n2')
    req = ULTIPA_REQUEST.Template(alias='p', items=[item1, item2, item3], 
    		limit=5,_return=['p', 'n1', 'e', 'n2'])
    ret = conn.template(request=req)
    print(ret.data.toJSON())
    
  • Rewrite above command using method conn.uql:

    from ultipa import Connection,ULTIPA_REQUEST
    conn = Connection(host='host:port', username="root", password="root")
    ret = conn.uql("t(p).n(n1).e(e).n(n2).limit(5).return(p,n1,e,n2)")
    print(ret.toJSON())