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