Graphite Query API Reference¶

This page documents API reference for QueryResult class, which provides a complete interface to query on your database with Pythonic methods. See engine.query to learn how you can start query. See Query Engine Tutorials for more information.

graphite.QueryResult ¶

QueryResult(graph_engine: GraphiteEngine, nodes: set[Node], edges: set[Relation] | None = None)

Represents a query result that can be chained

Parameters:

graph_engine (GraphiteEngine) –

Graphite engine instance
nodes (set[Node]) –

including nodes
edges (set[Relation] | None, default: None ) –

including edges

Methods:

avg –

Average value of a field in result
both –

Traverse both directions
count –

Count nodes
distinct –

Get distinct nodes (remove duplicates)
exclude –

Removes result of given query from current nodes and relations
first –

Get first node by ID or given field
get –

Get all nodes
group_by –

Group nodes by field
ids –

Get node IDs
incoming –

Traverse incoming relations
intersect –

Just keeps shared nodes and relations between current and given queries
limit –

Limit number of results (just nodes)
max –

Maximum value of a field in result nodes
min –

Minimum value of a field in result nodes
order_by –

Order nodes by field
outgoing –

Traverse outgoing relations
paginate –

Limit number of results to specified page
relations –

Get all relations
remove –

Remove current result nodes
remove_relations –

Remove current result relations
set_val –

Change result nodes' values
sum –

Sum of a field values in nodes
traverse –

Traverse relations from current nodes
union –

Merge query results (nodes and relations)
validate –

Removes invalid nodes and relations (remove additional items compared to engine)
where –

Filter nodes based on condition
with_fields –

Filter nodes with given fields
with_type –

Filter nodes based on type

Functions¶

avg ¶

avg(field: str) -> float

Average value of a field in result

Note: This query skips non-numeric values.

Parameters:

field (str) –

field name

Returns:

float –

average of field

Raises:

TypeError –

If there isn't any numeric value in given field

both ¶

both(relation_type: str | None = None) -> QueryResult

Traverse both directions

Parameters:

relation_type (str | None, default: None ) –

optional relation type for valid traverses

Returns:

QueryResult –

a new query with result nodes and traversed relations

count ¶

count() -> int

Count nodes

Returns:

int –

number of nodes

distinct ¶

distinct() -> QueryResult

Get distinct nodes (remove duplicates)

Returns:

QueryResult –

a new query with distinct nodes and original relations

exclude ¶

exclude(query: QueryResult) -> QueryResult

Removes result of given query from current nodes and relations

Parameters:

query (QueryResult) –

query to exclude

Returns:

QueryResult –

a new query with excluded nodes and relations

first ¶

first(order_by_field: str | None = None, descending: bool = False) -> Node | None

Get first node by ID or given field

Parameters:

order_by_field (str | None, default: None ) –

optional field to order before slicing
descending (bool, default: False ) –

sort results in descending order before slicing

Returns:

Node | None –

first node or None

get ¶

get() -> set[Node]

Get all nodes

Returns:

set[Node] –

set of nodes

group_by ¶

group_by(field: str) -> dict[Any, set[Node]]

Group nodes by field

Parameters:

field (str) –

field name

Returns:

dict[Any, set[Node]] –

dict of nodes grouped by field value

ids ¶

ids() -> set[str]

Get node IDs

Returns:

set[str] –

list of node IDs

incoming ¶

incoming(relation_type: str | None = None) -> QueryResult

Traverse incoming relations

Parameters:

relation_type (str | None, default: None ) –

optional relation type for valid traverses

Returns:

QueryResult –

a new query with result nodes and traversed relations

intersect ¶

intersect(query: QueryResult) -> QueryResult

Just keeps shared nodes and relations between current and given queries

Parameters:

query (QueryResult) –

query to intersect

Returns:

QueryResult –

a new query with intersected nodes and relations

limit ¶

limit(n: int, order_by_field: str | None = None, descending: bool = False) -> QueryResult

Limit number of results (just nodes)

Note: Before slicing, nodes will be sorted by IDs or given field.

Parameters:

n (int) –

number of results to return
order_by_field (str | None, default: None ) –

optional field to order results by it before slicing
descending (bool, default: False ) –

sort results in descending order before slicing

Returns:

QueryResult –

a new query with all relations and limited nodes

max ¶

max(field: str) -> float

Maximum value of a field in result nodes

Parameters:

field (str) –

field name

Returns:

float –

maximum value

Raises:

TypeError –

If there isn't any numeric value in given field

min ¶

min(field: str) -> float

Minimum value of a field in result nodes

Parameters:

field (str) –

field name

Returns:

float –

minimum value

Raises:

TypeError –

If there isn't any numeric value in given field

order_by ¶

order_by(by_field: str, descending: bool = False) -> list[Node]

Order nodes by field

Parameters:

by_field (str) –

field name
descending (bool, default: False ) –

whether to sort by ascending or descending

Returns:

list[Node] –

a list of sorted nodes

outgoing ¶

outgoing(relation_type: str | None = None) -> QueryResult

Traverse outgoing relations

Parameters:

relation_type (str | None, default: None ) –

optional relation type for valid traverses

Returns:

QueryResult –

a new query with result nodes and traversed relations

paginate ¶

paginate(page: int, per_page: int, order_by_field: str | None = None, descending: bool = False) -> QueryResult

Limit number of results to specified page

Note: Before slicing, nodes will be sorted by IDs or given field.

Parameters:

page (int) –

page number (from 0)
per_page (int) –

number of results in each page
order_by_field (str | None, default: None ) –

optional field to order results by it before slicing
descending (bool, default: False ) –

sort results in descending order before slicing

Returns:

QueryResult –

a new query with all relations and paged nodes

relations ¶

relations() -> set[Relation]

Get all relations

Returns:

set[Relation] –

set of relations

remove ¶

remove() -> QueryResult

Remove current result nodes

Note: Just valid nodes will be removed from engine.

Note: This query mutates nodes in-place and changes will be applied to engine directly.

Returns:

QueryResult –

A new query with remaining valid edges and no nodes

remove_relations ¶

remove_relations() -> QueryResult

Remove current result relations

Note: Just valid relations will be removed from engine.

Note: This query mutates relations in-place and changes will be applied to engine directly.

Returns:

QueryResult –

A new query with current nodes and no relations

Raises:

NotFoundError –

if any relations not found in engine

set_val ¶

set_val(**values: Any) -> QueryResult

Change result nodes' values

Note: Field validation happens before any mutation.

Note: This query mutates nodes in-place and changes will be applied to engine directly.

Note: This query raises NotFoundError for nodes without compatible fields, use .with_fields() to ensure all fields are valid.

Parameters:

**values (Any, default: {} ) –

field=value pairs

Returns:

QueryResult –

self

Raises:

NotFoundError –

if any field was invalid for any node

sum ¶

sum(field: str) -> float

Sum of a field values in nodes

Note: This query skips non-numeric values.

Parameters:

field (str) –

field name

Returns:

float –

sum of field

traverse ¶

traverse(relation_type: str | None = None, direction: Direction = OUTGOING) -> QueryResult

Traverse relations from current nodes

Note: Invalid nodes will be removed while traversing relations.

Parameters:

relation_type (str | None, default: None ) –

optional relation type for valid traverses
direction (Direction, default: OUTGOING ) –

traverse direction

Returns:

QueryResult –

a new query with result nodes and traversed relations

Raises:

NotFoundError –

if relation_type is invalid for engine

union ¶

union(query: QueryResult) -> QueryResult

Merge query results (nodes and relations)

Parameters:

query (QueryResult) –

query to merge

Returns:

QueryResult –

a new query with merged nodes and relation

validate ¶

validate() -> QueryResult

Removes invalid nodes and relations (remove additional items compared to engine)

Returns:

QueryResult –

A new query with valid nodes and relations

where ¶

where(condition: str | Callable[[Node], bool]) -> QueryResult

Filter nodes based on condition

Parameters:

condition (str | Callable[[Node], bool]) –

condition string or lambda callable

Returns:

QueryResult –

new query with nodes filtered based on condition

Raises:

ConditionError –

if fail on executing condition

with_fields ¶

with_fields(*fields: str) -> QueryResult

Filter nodes with given fields

Parameters:

*fields (str, default: () ) –

fields to filter

Returns:

QueryResult –

a new query with nodes filtered based on fields

with_type ¶

with_type(node_type: str, include_parent_types: bool = True) -> QueryResult

Filter nodes based on type

Note: This query uses engine.is_node_from_type() when include_parent_types is True. So invalid nodes will be ignored in this situation.

Parameters:

node_type (str) –

node type to filter
include_parent_types (bool, default: True ) –

whether to include parent types or not

Returns:

QueryResult –

a new query with nodes filtered based on type