1. Summary

Query methods are used to perform graph searches. The available methods are listed below.

pyvgx.Graph Query Methods Description

Global Search

Perform a global arc search or vertex search

pyvgx.Graph.VerticesType()

Return a list of names of all vertices of the given type

pyvgx.Graph.HasVertex()

Check if a vertex exists in the graph

pyvgx.Graph.GetVertex()

Return a pyvgx.Vertex instance for the named vertex

pyvgx.Graph.VertexIdByAddress()

Return the identifier of vertex at memory address

pyvgx.Graph.Neighborhood()

Perform a graph neighborhood search

pyvgx.Graph.OpenNeighbor()

Return a neighbor of a vertex

pyvgx.Graph.Adjacent()

Check if vertex is adjacent to other vertices

pyvgx.Graph.Aggregate()

Perform aggregation of neighborhood arc values

pyvgx.Graph.ArcValue()

Return the value of a specific arc

pyvgx.Graph.Degree()

Return the vertex degree, with optional conditions

pyvgx.Graph.Inarcs()

Return the inarc of a vertex

pyvgx.Graph.Outarcs()

Return the outarcs of a vertex

pyvgx.Graph.Initials()

Return vertices for which anchor is a terminal

pyvgx.Graph.Terminals()

Return vertices for which anchor is an initial

pyvgx.Graph.Search()

Perform a neighborhood search and print the result as human readable text

2. Global Search

Perform a global graph search using either pyvgx.Graph.Arcs() or pyvgx.Graph.Vertices().

2.1. pyvgx.Graph.Arcs()

Perform a global arc search in the graph.

2.2. pyvgx.Graph.Vertices()

Perform a global vertex search in the graph.

Both methods share a common parameter syntax.

2.2.1. Syntax

pyvgx.Graph.Arcs( ... ) -> result_object
pyvgx.Graph.Vertices( ... ) -> result_object

parameters:
[ condition[, vector[, result[, fields[, select[, rank[, sortby[, memory[, offset[, hits[, timeout[, limexec ] ] ] ] ] ] ] ] ] ] ] ]

Arguments can be supplied positionally or as keywords.

2.2.2. Parameters

Parameter Type Default Description

condition

Vertex condition

None

Vertex must meet this condition to be included in result

vector

<vector> or Python list

[]

Probe vector to use when condition includes similarity criteria

result

Result specification

pyvgx.R_STR

Control the overall format of the returned result

fields

Field specification

pyvgx.F_ID

Control which fields are included in the result

select

Select specification

None

Advanced specification of returned fields

rank

Rank specification

None

Define how to rank results when sortby=pyvgx.S_RANK

sortby

Sort specification

pyvgx.S_NONE

Determine how returned results are sorted

memory

Memory Object or int

4

General purpose array of numerical elements for use by expression evaluators

offset

int

0

Start result listing at this offset

hits

int

-1

Number of hits to include in result. The default is -1 which returns all results.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

2.2.3. Return Value

This method returns a search result object. The format of this object is either a list or a dictionary. The format is defined by the result parameter. See result specification for details.

2.2.4. Remarks

Arc and vertex search are global graph operations, which means they are not restricted to a particular graph neighborhood. Matching and retrieval of every arc or vertex in the graph is possible, but comes at the cost of longer execution time. These methods also block other threads from performing operations on the graph while executing, unless the graph is in readonly mode.

It is possible to reduce the overall system impact of global queries by restricting searches to a specific vertex type using the type filter within the condition parameter.

2.2.5. Example

from pyvgx import *
g = Graph( "graph" )

# Return all vertices in the graph
g.Vertices()

# Return all arcs in the graph
g.Arcs()

# Return 10 products sorted by identifier
g.Vertices( hits=10, sortby=S_ID, condition={ 'type':'product' } )

# Return all products and include their name and
# "color" properties in the result
g.Vertices( condition={ 'type':'product' }, fields=F_ID|F_PROP, select="color" )

# Return all relationships originating at initial
# vertices of type "person"
g.Arcs( condition={ 'type':'person' } )

# Return all relationships of type "knows" involving
# initial and/or terminal of type "person"
g.Arcs( condition={ 'arc':('knows',D_ANY), 'type':'person' } )

3. pyvgx.Graph.VerticesType()

Perform a global search for a specific vertex type in the graph.

3.1. Syntax

pyvgx.Graph.VerticesType( type ) -> list

3.2. Parameters

Parameter Type Default Description

type

str

Only vertices of this type are returned

3.3. Return Value

This method returns a list of identifier strings of all vertices in the graph of the specified type.

3.4. Remarks

Use type=None or type="__vertex__" to return typeless vertices, i.e. vertices created without a specific type.

3.5. Example

from pyvgx import *
g = Graph( "graph" )

# Return all person vertices in the graph
g.VerticesType( "person" )

4. pyvgx.Graph.HasVertex()

Check if a vertex exists in the graph.

4.1. Syntax

pyvgx.Graph.HasVertex( id ) -> bool

4.2. Parameters

Parameter Type Default Description

id

<str>

The vertex identifier to look up.

4.3. Return Value

This method returns True if the vertex exists, or False if the vertex does not exist.

4.4. Remarks

It is also possible to use the built-in Python __contains__ syntax to perform the same operation:

name in g
# is equivalent to
g.HasVertex( name )

4.5. Example

import pyvgx
g = pyvgx.Graph( "graph" )
g.CreateVertex( "A" )                # Create vertex A
print( g.HasVertex( "A" ) )           # True
print( g.HasVertex( "B" ) )          # False

5. pyvgx.Graph.GetVertex()

Return a pyvgx.Vertex object in readonly mode.

5.1. Syntax

pyvgx.Graph.GetVertex( id ) -> pyvgx.Vertex

5.2. Parameters

Parameter Type Default Description

id

<str>

The identifier of the vertex to return

5.3. Return Value

If the vertex exists in the graph a new pyvgx.Vertex wrapper object for the vertex is created and returned in readonly mode. If the vertex does not exist an exception is raised.

5.4. Remarks

It is also possible to use the built-in Python __getitem__ syntax to perform the same operation:

V = g[ name ]
# is equivalent to
V = g.GetVertex( name )

5.5. Example

import pyvgx
g = pyvgx.Graph("graph")
g.CreateVertex( "A" )             # Create but do not open A
B = g.NewVertex( "B" )            # Create and open B writable

# Get the wrapper object for A but do not acquire it.
# No guarantees for the consistency of A.
A = g.GetVertex( "A" )

6. pyvgx.Graph.VertexIdByAddress()

Return the identifier of vertex at memory address.

6.1. Syntax

pyvgx.Graph.VertexIdByAddress( address ) -> identifier

6.2. Parameters

Parameter Type Default Description

address

<int>

The memory address of vertex whose identifier will be returned

6.3. Return Value

If the given address contains a valid vertex object its identifier string is returned, otherwise KeyError is raised.

6.4. Remarks

It is possible for queries to return addresses of vertices instead of identifiers. Such queries may be constructed to limit the number of locks required to render the result. This method allows a vertex name to be resolved by its address.

6.5. Example

import pyvgx
g = pyvgx.Graph("graph")
g.Connect( "X", "to", "A" )             # X -> A
g.Connect( "X", "to", "B" )             # X -> B
g.Connect( "X", "to", "C" )             # X -> C
r = g.Neighborhood( "X", fields=F_ADDR, result=R_SIMPLE )
g.VertexIdByAddress( r[0] )             # 'A'
g.VertexIdByAddress( r[1] )             # 'B'
g.VertexIdByAddress( r[2] )             # 'C'

7. pyvgx.Graph.Neighborhood()

Perform a graph neighborhood search around a specific vertex id.

7.1. Syntax

pyvgx.Graph.Neighborhood( id[, arc[, pre[, filter[, post[, neighbor[, vector[, collect[, navigation[, result[, fields[, select[, rank[, sortby[, aggregate[, memory[, offset[, hits[, timeout[, limexec ] ] ] ] ] ] ] ] ] ] ] ] ] ] ] ] ] ] ] )

Arguments can be supplied positionally or as keywords.

7.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

Neighborhood search starts at this vertex.

arc

<arc_filter>

(None, pyvgx.D_OUT)

Arcs incident on id must match this filter.

pre

<expression>

None

Pre-filter executed before neighborhood traversal, and must evaluate to a positive number for the query to continue. Will not be executed if the neighborhood is empty.

filter

<expression>

None

Filter executed for each traversed arc in the neighborhood, and must evaluate to a positive number in order to match.

post

<expression>

None

Post-filter executed after neighborhood traversal and only if pre matched. The expression return value is ignored.

neighbor

<vertex_condition>

*

Arcs incident on id must be connected to a neighbor vertex matching this filter.

vector

<vector> or Python list

[ ]

Use this probe vector for similarity matching when neighbor includes similarity filters.

collect

<bool> or <arc_filter>

pyvgx.C_COLLECT

Control how neighborhood arcs are collected and returned in the result.

navigation

<bool> or <dict>
See Navigation

False

Enable navigation search mode and specify navigation behavior

result

<result_format>

pyvgx.R_STR

Specify the overall format of the returned result.

fields

<result_fields>

pyvgx.F_ID

Simple specification of fields to be included in the returned result list.

select

<select_statement>

None

Advanced specification of fields to be included in the returned result list, allowing inclusion of vertex properties and evaluation of expressions.

rank

<ranking_formula>

None

Specify an expression to compute dynamic rank scores when sortby=pyvgx.S_RANK

sortby

<sort_specification>

pyvgx.S_NONE

Control the ordering of returned results.

aggregate

See Aggregation

None

Perform value aggregation rather than returning individual arcs and values.

memory

<memory_object> or int

4

Supply a general purpose array of numeric elements for use with expression evaluators in filter, rank, and select.

offset

<int>

0

Start the result listing at this offset in the returned result.

hits

<int>

-1

Set the maximum number of hits to return in the result. A negative number will return all results.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.
Parameters arc, filter, neighbor and collect have the same meaning as the correspondingly named entries within the 'traverse':{…​} section of <vertex_condition>. These four parameters define arc matching, traversal and collection in the immediate neighborhood.

However, the default values of arc and collect for the immediate neighborhood differ from those of the generic <vertex_condition>. The immediate neighborhood arc parameter defaults to D_OUT while the 'arc': entry in <vertex_condition> defaults to D_ANY. The immediate neighborhood collect parameter defaults to True while the 'collect': entry in <vertex_condition> defaults to C_NONE.
For syntax consistency between <vertex_condition> and this methods’s arc, filter, neighbor and collect parameters it may be helpful to submit these parameters using Python **kwargs. The kwargs dictionary is then a proper subset of <vertex_condition>.
Example:
>>> condition = { 'arc':D_ANY), 'filter':"next.arc.type == 'friend' && next.arc.value == 100", 'neighbor':{ 'type':'person' }, 'collect':("called", D_OUT) }
>>> g.Neighborhood( "me", hits=10, **condition )

7.3. Return Value

This method returns a list of search results or a dictionary containing a list of search results along with other meta information. See Result Format for details.

7.4. Remarks

The Neighborhood() method is a powerful graph search tool, allowing arbitrary and practically unlimited graph traversal. For a full understanding of how to match, traverse, and collect relationships across a graph, study the descriptions of evaluation order, filter, adjacent, traverse, and collect.

7.4.1. Overview

A neighborhood search starts at the specified vertex id (anchor) and radiates outwards via its arcs to its immediate neighbors. If requested, the search may continue from all neighbors along their arcs to reach farther into the graph. Separate conditions for vertices and arcs are specified at each level (distance) from the anchor. A simple neighborhood query only traverses the anchor’s arcs to its immediate neighbors.

Filters can be used to control which arcs are traversed. Filters can apply to arcs and the neighbors pointed to by those arcs. By default traversal is greedy. Arc filters restrict traversal based on relationship types, arc values, etc. Neighbor vertex filters restrict traversal based on vertex attributes, properties, and possibly nested traversal to their neighbors, which again may have separate arc and vertex filters, and so on.

For an arc to be traversed it must first satisfy any filter applied directly to the arc, then any filter applied to the neighbor pointed to (the terminal). If filters are nested, then the terminal’s own arcs and neighbors will have to match their filters. This is a depth-first process, in the sense that for any arc to be traversed its entire chain of filters must be matched. However, the matching process is executed shallow-to-deep, such that a miss may be declared sooner rather than later. This means, for instance, that if an arc filter declares a miss on the relationship type it will not proceed to the neighbor vertex to evaluate its filters. But it also means an arc cannot be declared a match until all cascading filters have been satisfied.

Arc filters are specified using the arc parameter. Neighbor vertex filters are specified using the neighbor parameter. The latter has a rich set of constraints for matching and controlling nested traversal.

Navigation search is enabled with the navigation parameter. This special traversal mode performs automatic discovery of the anchor’s extended neighborhood, and can potentially be configured to explore the entire graph via a few simple controls. This mode is primarily used for vector search, where an underlying proximity graph connects mutually similar vertices to form a traversable landscape. Such a network of vector-endowed vertices allows the search to discover paths to graph regions containing items most closely resembling a probe condition (vector.)

Once an arc has been declared a match it may be collected into the result set according to the collection rules at the neighborhood level at which the arc is being evaluated. Normally collection is controlled by the collect parameter, which by default is True (pyvgx.C_COLLECT) at the anchor’s level, and False (pyvgx.C_NONE) at nested levels. Queries with nested conditions may be configured to collect at some levels (distance from anchor) and not at others. The levels that do not require collection act as hit/miss filters only. Beyond the last level that requires collection filters will only execute until a hit is declared. For levels that require collection all arcs are visited (and possibly traversed) since all arcs are candidates for collection at this level.

Collecting an arc means to collect that arc’s attributes (i.e. relationship and value) and the terminal’s attributes and properties. The fields and select parameters control which elements are gathered into the result list. If collection occurs at more than one level (in a nested query) the collected items are entered into the same flat output list. It is possible to include a result field indicating the item’s distance from the anchor vertex.

The result parameter controls the data type returned by the neighborhood query. The outer container for collected items is always a list. Items can be formatted as strings, tuples, dicts, or numbers. If meta information is requested (with pyvgx.R_COUNTS or pyvgx.R_TIMING) the item container list is wrapped in a dict along with the requested metas.

Result lists can be ordered by any attribute or vertex property, or according to user-defined ranking formulas.

A timeout can be specified for neighborhood queries. It represents an upper limit for how long the query is allowed to run before terminating the query and raising an exception.

When limexec is False (the default) the timeout deadline is considered only whenever a blocking condition is encountered, i.e. when waiting to acquire a vertex. If no vertex acquisition blocks after the timeout deadline has been reached the query is allowed to run to completion. A timeout in this case raises pyvgx.AccessError.

In contrast, when limexec is True the timeout deadline is continually monitored, terminating the query after the timeout deadline has been reached even if progress is being made without blocking. A timeout in this case raises pyvgx.SearchError.

7.4.2. Basic Neighborhood Query

Simple neighborhood queries start at an anchor vertex and returns the anchor’s neighbors with optional filters applied and optional fields collected.

Collect the names of all neighbors of anchor vertex
g.Neighborhood(
    id = anchor_name  # Start search here
)
Restrict search by arc’s relationship type
g.Neighborhood(
    id = anchor_name,
    arc = ("likes", D_OUT) # Require specific relationship
)
Further restrict search by terminal condition
g.Neighborhood(
    id = anchor_name,
    arc = ("likes", D_OUT),  # Require specific relationship
    neighbor = {"id": "A*"}  # and some neighbor restriction
)
Control what fields are returned and their format
g.Neighborhood(
    id = anchor_name,
    arc = ("likes", D_OUT),
    neighbor = {
        'id': "A*"
    },
    fields = F_VAL|F_ID,  # Return arc value and terminal id
    result = R_LIST       # as tuples
)

7.4.3. Nested Neighborhood Query

Nested neighborhood queries restrict their matches based on conditions reaching deeper into the graph. Nesting up to the 15th extended neighborhood is supported. Collection may be configured to occur at any level.

Return names of anchor’s terminals which are themselves connected to vertices meeting a certain condition
g.Neighborhood(
    id = anchor_name,
    neighbor = {  # terminal must be
        'traverse': { # connected to another
            'neighbor': { # neighbor satisfying
                'id': "B*" # a specific condition
            }
        }
    }
)
Further restrict the returned items to those who like someone who knows someone who visited some country
g.Neighborhood(
    id = anchor_name,
    arc = ("likes", D_OUT), # Restrict immediate neighborhood by relationship type
    neighbor = {
        'traverse': {
            'arc': ("knows", D_OUT), # Restrict next neighborhood by another relationship type
            'neighbor': {
                'id': "B*",
                'adjacent' : { # 3rd extended neighborhood
                    'arc': ("visited", D_OUT), # must have visited
                    'neighbor': {
                        'type': "country", # a country of
                        'id': "Elbonia" # this specific name
                    }
                }
            }
        }
    }
)
Perform item collection at another level of nesting
g.Neighborhood(
    id = anchor_name,
    collect = C_NONE, # Don't collect immediate neighbors
    arc = ("likes", D_OUT),
    neighbor = {
        'traverse': {
            'arc': ("knows", D_OUT),
            'neighbor': {
                'id': "B*",
                'collect': C_COLLECT, # Collect these neighbors
                'adjacent' : {
                    'arc': ("visited", D_OUT),
                    'neighbor': {
                        'type': "country",
                        'id': "Elbonia"
                    }
                }
            }
        }
    }
)

7.4.4. Aggregation

It is possible to perform value aggregation of collected arcs, rather than returning individual arcs. Arcs matching the arc filter criteria and sharing the same head vertex (i.e. have the same terminal) are collapsed into an aggregated arc with a value representing some aggregation of the individual arc values. Arcs will be aggregated even if they are collected from different neighborhoods in a nested traversal scenario, so long as their heads terminate at the same vertex.

To enable aggregation use the aggregate parameter:

g.Neighborhood(
    ...,
    aggregate = {
        'arc'       : <arc_postfilter>,
        'mode'      : <mode_spec>
    }
)
"""
where:
    <arc_postfilter ::= ( <relationship>, D_ANY, M_INTAGGR[, <condition>, <value> ] )
    or
    <arc_postfilter> ::= ( <relationship>, D_ANY, M_FLTAGGR[, <condition>, <value> ] )

<mode> ::= "first" | "max" | "min" | "average" | "count" | "sum" | "sqsum" | "product"
"""

The aggregation 'mode': <mode> determines how aggregated values are computed:

Mode Description

first

Only collect the first traversed arc from each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

max

Collect the maximum value arc from each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

min

Collect the minimum value arc from each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

average

Set the value of aggregated arcs to the average of all values of the arcs in each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

count

(DEFAULT) Set the value of the aggregated arcs to the number of arcs in each set of arcs sharing the same head vertex, regardless of value type

sum

Set the value of aggregated arcs to the sum of all values of the arcs in each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

sqsum

Set the value of aggregated arcs to the square-sum of all values of the arcs in each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

product

Set the value of aggregated arcs to the product of all values of the arcs in each set of arcs sharing the same head vertex and value type (integer and floating point arc values are aggregated separately)

The optional 'arc': <arc_postfilter> operates on the aggregated value, making it possible to perform aggregation among a large set of arcs sharing value types and head vertices and only returning those aggregations that satisfy certain value cutoff criteria. The default is 'arc':(), meaning no post filtering.

Post filters are not directional. Specify arc direction D_OUT for post filters.

Aggregated arc values lose the modifier types of their collected source arcs. Instead, aggregation values are separated into integer or floating point types. Arcs whose modifiers have an integer value are binned together and assigned a special aggregation modifier M_INTAGGR. Similarly, arcs with float values are assigned the aggregation modifier M_FLTAGGR. Arc post filters must use one of the aggregation modifiers. It is not possible to use a post filter that works on integer and floating point values at the same time. Note that 'mode': 'count' generates an integer type aggregation value.

Aggregation Modifier Represents

M_INTAGGR

M_STAT, M_LSH, M_INT, M_UINT, M_CNT, M_TMC, M_TMM, M_TMX

M_FLTAGGR

M_SIM, M_DIST, M_FLT, M_ACC

7.4.5. Navigation

Navigation search is a powerful feature for automatically exploring a graph to collect top matching items ranked by some scoring formula. A common use case is approximate nearest neighbor (ANN) search. Given a sufficiently connected proximity graph the built-in navigation algorithm can traverse its way towards the best matches using only a probe vector as search condition.

Approximate nearest neighbors (ANN) search
g.Neighborhood(
    id = start_node,
    hits = 10,
    navigation = {
        'vector': probe_vector
    }
)

See separate Neighborhood Navigation Query section for more details.

8. pyvgx.Graph.OpenNeighbor()

Acquire and return one of the neighbors of a given vertex.

8.1. Syntax

pyvgx.Graph.OpenNeighbor( id[, arc[, mode[, timeout]]] )

8.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

This is the vertex whose neighbor will be returned

arc

<arc_filter>

(None, pyvgx.D_OUT)

The first neighbor connected to id with an arc matching this filter will be returned

mode

chr

'r'

Access mode is one of:

'r' = Readonly

'a' = Writable (do not create)

timeout

int

Timeout specification

0

Timeout (in milliseconds) for vertex acquisition

8.3. Return Value

This method returns a pyvgx.Vertex object opened according to access mode. If no neighbor exists KeyError is raised. If acquisition of id or its neighbor cannot be performed within timeout pyvgx.AccessError is raised.

8.4. Remarks

At most one neighbor is returned by this method, and if multiple neighbors matching arc filter exist the returned neighbor is generally unknown which neighbor is returned. For this reason, the primary use case of this method is when uniquely associating a vertex with a neighbor using a special relationship.

Using this method to access special neighbors is more efficient than storing the identifiers of those neighbors in properties, because arcs take less space than properties and fewer Python steps are required to acquire the neighbor vertex.

8.5. Example

from pyvgx import *
g = Graph("graph")

g.Connect( "Alice", "knows", "Bob"  )
g.Connect( "Alice", "knows", "Charlie"  )
g.Connect( "Alice", "knows", "Dave"  )
g.Connect( "Alice", "special_friend", "Dave"  )
g.Connect( "Alice", "knows", "Eve"  )

# May return any of Alice's connections
Anyone = g.OpenNeighbor( "Alice" )

# Dave
Dave = g.OpenNeighbor( "Alice", "special_friend" )

9. pyvgx.Graph.Adjacent()

Test if a vertex has a neighbor, optionally matching arc and/or neighbor filters.

9.1. Syntax

pyvgx.Graph.Adjacent( id[, arc[, neighbor[, pre[, filter[, post[, memory[, timeout[, limexec ] ] ] ] ] ] ] ] )

9.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

This is the vertex whose adjacency to neighbors will be tested.

arc

<arc_filter>

(None, pyvgx.D_OUT)

Arcs incident on vertex id must match this filter.

neighbor

<vertex_condition>

*

Arcs incident on vertex id must be connected to a neighbor vertex matching this filter.

pre

<expression>

None

Pre-filter executed before neighborhood traversal, and must evaluate to a positive number for the query to continue. Will not be executed if the neighborhood is empty.

filter

<expression>

None

Filter executed for each traversed arc in the neighborhood, and must evaluate to a positive number in order to match.

post

<expression>

None

Post-filter executed after neighborhood traversal and only if pre matched, and must evaluate to a positive number in order to match.

memory

<memory_object> or int

4

Supply a general purpose array of numeric elements for use with expression evaluators in filter.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

9.3. Return Value

This method returns True if vertex id has at least one neighbor reachable via arc and matching the filter and neighbor conditions, otherwise False is returned. Additionally, if pre and post filters are used, both must return positive numbers, otherwise False is returned.

9.4. Remarks

This method ignores the use of 'collect' filter(s) in the neighbor filter’s <vertex_condition>. Since this method only tests adjacency no arcs arc collected, only tested.

9.5. Example

from pyvgx import *
g = Graph("graph")

g.Connect( "Alice", "knows", "Bob" )
g.Connect( "Alice", "likes", "coffee" )

g.Adjacent( "Alice" )       # True
g.Adjacent( "Bob" )         # False, arc direction is D_OUT by default
g.Adjacent( "Bob", D_ANY )  # True
g.Adjacent( "Alice", "likes", "Bob" )       # False
g.Adjacent( "Alice", "likes", "coffee" )    # True

10. pyvgx.Graph.Aggregate()

Compute the sum of all matching arc values and vertex degrees in one or more neighborhoods originating at the anchor vertex.

10.1. Syntax

pyvgx.Graph.Aggregate( id[, arc[, pre[, filter[, post[, collect[, neighbor[, result[, fields[, memory[, timeout[, limexec ] ] ] ] ] ] ] ] ] ] ] )

10.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

Aggregation starts at this vertex

arc

<arc_filter>

(None, pyvgx.D_OUT)

Arcs incident on vertex id must match this filter to contribute to aggregated sums (when collect is True), and to be traversed if neighbor extends aggregation into other neighborhoods.

pre

<expression>

None

Pre-filter executed before neighborhood traversal, and must evaluate to a positive number for the query to continue. Will not be executed if the neighborhood is empty.

filter

<expression>

None

Filter executed for each traversed arc in the neighborhood, and must evaluate to a positive number in order to match.

post

<expression>

None

Post-filter executed after neighborhood traversal and only if pre matched. The expression return value is ignored.

collect

<collect_constant>

pyvgx.C_COLLECT

Control whether arcs in the immediate neighborhood contribute to aggregated sums.

neighbor

<vertex_condition>

*

Arcs incident on vertex id must be connected to a neighbor vertex matching this filter. Aggregation continues in extended neighborhood if <vertex_condition> specifies 'collect': True.

result

<result_metas>

pyvgx.R_COUNTS

Control whether hit counts and/or search execution time are included in the result. The returned result is always a dictionary.

fields

<aggregation_fields>

pyvgx.F_NONE

Select the fields to aggregate. Fields available for aggregation are F_VAL, F_DEG, F_IDEG and F_ODEG. Other fields specified here will be ignored. Note that F_VAL requires the arc filter with a specific modifier.

memory

<memory_object> or int

4

Supply a general purpose array of numeric elements for use with expression evaluators in filter.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

10.3. Return Value

This method always returns a dictionary object. Aggregated values are returned in a dictionary like this:

<aggregation> ::= {
    'neighbors'         : <head_vertices>,
    'arcs'              : <traversed_arcs>,
    'predicator_value'  : <integer_sum> | <float_sum>,
    'degree'            : <head_vertices_degree_sum>,
    'indegree'          : <head_vertices_indegree_sum>,
    'outdegree'         : <head_vertices_outdegree_sum>
}

Keys 'neighbors' and 'arcs' are always included. Others depend on what is selected in the fields parameter.

If result contains R_TIMING <aggregation> is wrapped in an outer result dictionary like this:

<result_with_timing> ::= {
    'aggregation'   : <aggregation>,
    'time'          : {
        'search'        : <seconds>,
        'total'         : <seconds>
    }
}

10.4. Remarks

To enable aggregation of arcs (predicator values) the arc parameter is required and the filter must contain a specific modifier. Furthermore, if extending aggregation beyond the immediate neighborhood neighbor(s) must include 'arc' filter(s) with the same modifier as the one specified in the arc parameter. (If integer and floating point modifiers are mixed, the aggregated values are undefined.)

10.5. Example

from pyvgx import *
g = Graph( "graph" )

for n in range( 100 ):
    g.Connect( "Alice", ("called", M_INT, n), "person_%d" % n )
    g.Connect( "Alice", ("visited", M_INT, n/10), "person_%d" % n )

# How many times did Alice call somebody?
g.Aggregate(
    "Alice",
    arc    = ("called", D_OUT, M_INT),
    fields = F_VAL
) # -> {'neighbors': 100, 'predicator_value': 4950, 'arcs': 100}

# How many total interactions with those with whom she either called
# exactly once or twice or visited exactly once or twice?
g.Aggregate(
    "Alice",
    arc    = ("", D_OUT, M_INT, V_RANGE, (1,2)),
    fields = F_VAL
) # -> {'neighbors': 22, 'predicator_value': 33, 'arcs': 22}

11. pyvgx.Graph.ArcValue()

Return the value of a specific arc.

11.1. Syntax

pyvgx.Graph.ArcValue( initial, arc, terminal[, timeout[, limexec ] ] )

11.2. Parameters

Parameter Type Default Description

initial

<str> or pyvgx.Vertex instance

The tail of the arc whose value is returned

arc

<arc_filter>

The returned value will match this arc filter

terminal

<str> or pyvgx.Vertex instance

The head of the arc whose value is returned

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

11.3. Return Value

The returned value is an integer, float or None depending on the modifier type of the selected arc:

Modifier of Selected Arc Return Value Type

M_STAT

None

M_SIM, M_DIST, M_FLT, M_ACC

<float>

M_LSH, M_INT, M_UINT, M_CNT, M_TMC, M_TMM, M_TMX

<int>

If no matching arc is found pyvgx.SearchError is raised.

11.4. Remarks

This method will retrieve and return the value of the first arc found between initial and terminal matching the arc filter. If initial has a multiple arc to terminal it is generally undefined which of the individual arc values is returned unless arc specifies a unique relationship, direction and modifier.

11.5. Example

from pyvgx import *
g = Graph( "graph" )

g.Connect( "Alice", ("called",M_TMM,1544635200), "Bob" )
g.Connect( "Alice", ("called",M_CNT,17), "Bob" )
g.Connect( "Alice", ("visited",M_TMM,154552331), "Bob" )
g.Connect( "Alice", ("called",M_TMM,1544412231), "Charlie" )

# When did Alice last call Bob?
g.ArcValue( "Alice", ("called",D_OUT,M_TMM), "Bob" )

# How many times has Alice called Bob?
g.ArcValue( "Alice", ("called",D_OUT,M_CNT), "Bob" )

12. pyvgx.Graph.Degree()

Return the number of arcs incident on a vertex, optionally matching an arc filter.

12.1. Syntax

pyvgx.Graph.Degree( id[, arc[, filter[, timeout[, limexec ] ] ] ] )

12.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

The vertex whose degree is computed

arc

<arc_filter>

(None, pyvgx.D_ANY)

Arcs matching this filter contribute to the computed degree. The default is the standard definition of vertex degree, i.e. all outarcs and inarcs are counted.

filter

<expression>

None

Filter expression must evaluate to a positive number in order to match.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

12.3. Return Value

This method returns the number of arcs incident on vertex id matching arc and filter.

12.4. Example

from pyvgx import *
    g = Graph( "graph" )

for n in range( 10 ):
    g.Connect( "Alice", "friend", "person_%d" % n )

for n in range( 100 ):
    g.Connect( "Alice", "knows", "person_%d" % n )

# How many connections does Alice have?
g.Degree( "Alice", ("*",D_OUT) ) # -> 110

# Hom many friends does Alice have?
g.Degree( "Alice", ("friend",D_OUT) ) # -> 10

13. pyvgx.Graph.Inarcs()

Return the inbound arcs for a vertex.

13.1. Syntax

pyvgx.Graph.Inarcs( id[, hits[, timeout[, limexec ] ] ] )

13.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

Vertex whose inarcs are returned

hits

<int>

-1

Maximum number of inarcs to return. By default all inarcs are returned.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

13.3. Return Value

This method returns a list of arc tuples:

result ::= [
    ( D_IN, <relationship>, <modifier>, <value>, <anchor> ),
    ( D_IN, <relationship>, <modifier>, <value>, <anchor> ),
    ...
]

13.4. Remarks

All returned inarcs have direction D_IN and terminate at the id vertex.

The order of returned results is not defined.

13.5. Example

from pyvgx import *
g = Graph( "graph" )

for n in range( 1000 ):
    g.Connect( "person_%d" % n, "friend", "Alice" )

# Return five of Alice's friend connections
g.Inarcs( "Alice", hits=5 )

14. pyvgx.Graph.Outarcs()

Return the outbound arcs for a vertex.

14.1. Syntax

pyvgx.Graph.Outarcs( id[, hits[, timeout[, limexec ] ] ] )

14.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

Vertex whose outarcs are returned

hits

<int>

-1

Maximum number of outarcs to return. By default all outarcs are returned.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

14.3. Return Value

This method returns a list of arc tuples:

result ::= [
    ( D_OUT, <relationship>, <modifier>, <value>, <terminal> ),
    ( D_OUT, <relationship>, <modifier>, <value>, <terminal> ),
    ...
]

14.4. Remarks

All returned outarcs have direction D_OUT.

The order of returned results is not defined.

14.5. Example

from pyvgx import *
g = Graph( "graph" )

for n in range( 10 ):
    g.Connect( "Alice", "called", "person_%d" % n )

# Return five of Alice's calls to other people
g.Outarcs( "Alice", hits=5 )

15. pyvgx.Graph.Initials()

Return the identifiers of vertices with arc(s) to this anchor vertex.

15.1. Syntax

pyvgx.Graph.Initials( id[, pre[, filter[, post[, neighbor[, rank[, sortby[, memory[, hits[, timeout[, limexec ] ] ] ] ] ] ] ] ] ] )

15.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

The vertex whose initials are returned

pre

<expression>

None

Pre-filter executed before neighborhood traversal, and must evaluate to a positive number for the query to continue. Will not be executed if vertex has no inarcs.

filter

<expression>

None

Filter executed for each traversed arc in the neighborhood, and must evaluate to a positive number in order to match.

post

<expression>

None

Post-filter executed after neighborhood traversal and only if pre matched. The expression return value is ignored.

neighbor

<vertex_condition>

*

Returned initials must match this vertex filter

rank

<ranking_formula>

None

Specify an expression to compute dynamic rank scores when sortby=pyvgx.S_RANK

sortby

Sort specification

pyvgx.S_NONE

Determine how returned initials are sorted

memory

<memory_object> or int

4

Supply a general purpose array of numeric elements for use with expression evaluators in filter and rank.

hits

<int>

-1

The maximum number of initials to return. By default all initials are returned.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

15.3. Return Value

This method returns a list of vertex identifiers:

result ::= [
    <vertex_identifier_1>,
    <vertex_identifier_2>,
    <vertex_identifier_3>,
    ...
]

15.4. Example

from pyvgx import *
g = Graph( "graph" )

for n in range( 10 ):
    g.Connect( "person_%d" % n, "called", "Alice" )

# Return the id of everyone who called Alice, sorted by name
g.Initials( "Alice", sortby=S_ID )

16. pyvgx.Graph.Terminals()

Return the identifiers of this anchor’s terminal vertices.

16.1. Syntax

pyvgx.Graph.Terminals( id[, pre[, filter[, post[, neighbor[, rank[, sortby[, memory[, hits[, timeout[, limexec ] ] ] ] ] ] ] ] ] ] )

16.2. Parameters

Parameter Type Default Description

id

<str> or pyvgx.Vertex instance

The vertex whose terminals are returned

pre

<expression>

None

Pre-filter executed before neighborhood traversal, and must evaluate to a positive number for the query to continue. Will not be executed if vertex has no outarcs.

filter

<expression>

None

Filter executed for each traversed arc in the neighborhood, and must evaluate to a positive number in order to match.

post

<expression>

None

Post-filter executed after neighborhood traversal and only if pre matched. The expression return value is ignored.

neighbor

<vertex_condition>

*

Returned terminals must match this vertex filter

rank

<ranking_formula>

None

Specify an expression to compute dynamic rank scores when sortby=pyvgx.S_RANK

sortby

Sort specification

pyvgx.S_NONE

Determine how returned terminals are sorted

memory

<memory_object> or int

4

Supply a general purpose array of numeric elements for use with expression evaluators in filter and rank.

hits

<int>

-1

The maximum number of terminals to return. By default all terminals are returned.

timeout

int

Timeout specification

0

Timeout (in milliseconds) for internal vertex acquisition where required, or upper execution time limit when limexec is true.

limexec

boolean

False

When True, limits query execution time according to timeout even when not blocked on vertex acquisition.

16.3. Return Value

This method returns a list of vertex identifiers:

result ::= [
    <vertex_identifier_1>,
    <vertex_identifier_2>,
    <vertex_identifier_3>,
    ...
]

16.4. Example

from pyvgx import *
g = Graph( "graph" )

for n in range( 10 ):
    g.Connect( "Alice", "called", "person_%d" % n )

# Return the name of all people Alice called, sorted by name
g.Terminals( "Alice", sortby=S_ID )

17. pyvgx.Graph.Search()

Simplified version of pyvgx.Graph.Neighborhood() and pyvgx.Graph.Vertices() that renders a human-readable result listing to the selected output stream.

The same parameters are available with the exception of those controlling fields and result format.

When no anchor vertex is specified the behavior is that of pyvgx.Graph.Vertices(). When anchor is specified the behavior is that of pyvgx.Graph.Neighborhood().

17.1. Example

from pyvgx import *
g = Graph( "graph" )

for n in range(100):
    g.Connect( "Alice", "knows", "person_%d" % n )

# Equivalent to g.Vertices(), printing a human-readable result listing
g.Search()

# Equivalent to g.Neighborhood( "Alice", D_OUT, hits=5, sortby=S_ID )
# printing a human-readable result listing
g.Search( "Alice", D_OUT, hits=5, sortby=S_ID )

PYVGX