InstanceConnection

Reference

InstanceConnection

Query execution and data access

15 min Intermediate

ReferenceAPI

InstanceConnection

Returned by client.instances.connect(instance_id) or the convenience helper ctx.connect(), this object is the primary interface for querying a running graph instance.

It provides four query methods (query, query_df, query_scalar, query_one), rich result-conversion helpers on QueryResult, schema inspection, lock monitoring, and connection lifecycle management.

1

Setup

Connect to the platform

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst
print(f"Connected to {conn.name} | {conn.query_scalar('MATCH (n) RETURN count(n)')} nodes")

2

Query Methods

Execute Cypher queries in different modes

query(cypher, parameters, *, timeout, coerce_types) -> QueryResult

Execute a Cypher query and return a QueryResult with multiple conversion options. Results are iterable as dicts.

Parameter	Type	Default	Description
cypher	str	required	Cypher query string
parameters	dict[str, Any] | None	None	Query parameters
timeout	float | None	None	Override default timeout (seconds)
coerce_types	bool	True	Convert DATE/TIMESTAMP to Python types

Returns: QueryResult (iterable, convertible to DataFrame/NetworkX/CSV/Parquet).

Raises: RyugraphError on query failure; QueryTimeoutError on timeout.

# Basic query -- iterate rows as dicts
result = conn.query("MATCH (c:Customer) RETURN c.id, c.acct_stus LIMIT 5")
for row in result:
    print(f"  {row['c.id']} ({row['c.acct_stus']})")

# Get a real customer ID first
first_id = conn.query_scalar("MATCH (c:Customer) RETURN c.id LIMIT 1")

# Parameterized query
result = conn.query(
    "MATCH (c:Customer) WHERE c.acct_stus = $id RETURN c.id, c.acct_stus",
    parameters={"id": first_id},
)
for row in result:
    print(f"  {row['c.id']} ({row['c.acct_stus']})")

query_df(cypher, parameters, *, backend) -> DataFrame

Execute a query and return a Polars or Pandas DataFrame directly.

Parameter	Type	Default	Description
cypher	str	required	Cypher query string
parameters	dict[str, Any] | None	None	Query parameters
backend	str	"polars"	"polars" or "pandas"

Returns: polars.DataFrame (default) or pandas.DataFrame.

# DataFrame conversion (default: Polars)
df = conn.query_df("MATCH (c:Customer) RETURN c.id, c.acct_stus LIMIT 10")
print(df)

# Pandas backend
pdf = conn.query_df(
    "MATCH (c:Customer) RETURN c.id, c.acct_stus LIMIT 5",
    backend="pandas",
)
print(pdf)

query_scalar(cypher, parameters) -> Any

Execute a query that returns a single value.

Parameter	Type	Default	Description
cypher	str	required	Cypher returning one row, one column
parameters	dict[str, Any] | None	None	Query parameters

Returns: Single value (int, float, str, etc.).

Raises: ValueError if the result has more than one row or column.

# Scalar query
count = conn.query_scalar("MATCH (n) RETURN count(n)")
print(f"Total nodes: {count}")

query_one(cypher, parameters) -> dict | None

Execute a query and return the first row as a dict, or None if the result is empty.

Parameter	Type	Default	Description
cypher	str	required	Cypher query string
parameters	dict[str, Any] | None	None	Query parameters

Returns: dict[str, Any] or None.

# Get a real customer ID first
first_id = conn.query_scalar("MATCH (c:Customer) RETURN c.id LIMIT 1")

# Single-row lookup
customer = conn.query_one(
    "MATCH (c:Customer {id: $id}) RETURN c.id, c.acct_stus",
    parameters={"id": first_id},
)
if customer:
    print(f"Found: {customer}")
else:
    print("Not found")

3

Result Conversion

QueryResult output formats

The QueryResult returned by query() supports several conversion methods:

Method	Returns	Description
to_polars()	polars.DataFrame	Convert to Polars DataFrame
to_pandas()	pandas.DataFrame	Convert to Pandas DataFrame
to_networkx()	networkx.DiGraph	Build graph from node/edge results
to_csv(path)	None	Export to CSV file
to_parquet(path)	None	Export to Parquet file
to_dicts()	list[dict]	Convert to list of row dicts
scalar()	Any	Extract single scalar value
show()	display	Auto-select table or graph visualization

# Polars DataFrame
result = conn.query("MATCH (c:Customer) RETURN c.id, c.acct_stus LIMIT 5")
pl_df = result.to_polars()
print(pl_df)

# Pandas DataFrame
pd_df = result.to_pandas()
print(pd_df)

# List of dicts
rows = result.to_dicts()
for row in rows:
    print(row)

# Export to file
result.to_csv("/tmp/customers.csv")
result.to_parquet("/tmp/customers.parquet")
print("Exported to /tmp/customers.csv and /tmp/customers.parquet")

# Auto-visualization in Jupyter
# Tabular data -> interactive table; graph data -> pyvis network
result.show()

# Scalar extraction
count_result = conn.query("MATCH (n) RETURN count(n)")
print(count_result.scalar())

4

Schema & Status

Inspect the graph structure and connection state

get_schema() -> Schema

Return the graph schema with node labels, relationship types, and their properties.

Returns: Schema with node_labels, relationship_types, node_count, relationship_count.

schema = conn.get_schema()

print(f"Nodes: {schema.node_count:,}  Relationships: {schema.relationship_count:,}\n")

print("Node labels:")
for label, props in schema.node_labels.items():
    joined = ", ".join(props)
    print(f"  :{label}  ({joined})")

print("\nRelationship types:")
for rel_type, props in schema.relationship_types.items():
    joined = ", ".join(props) if props else "no properties"
    print(f"  [:{rel_type}]  ({joined})")

get_lock() -> LockStatus

Check whether the instance is locked by a running algorithm.

Returns: LockStatus with locked, holder_name, algorithm, execution_id, locked_at.

lock = conn.get_lock()
if lock.locked:
    print(f"Locked by {lock.holder_name}, running {lock.algorithm}")
else:
    print("Instance is unlocked")

status() -> dict

Get live instance status including resource usage.

Returns: dict with memory_usage, disk_usage, uptime, lock_status.

info = conn.status()
for key, val in info.items():
    print(f"  {key}: {val}")

Connection Properties

Property	Type	Description
id	int | None	Instance ID
name	str | None	Instance name
snapshot_id	int | None	Snapshot ID
current_status	str | None	Cached status string (use status() for live data)

print(f"ID:          {conn.id}")
print(f"Name:        {conn.name}")
print(f"Snapshot ID: {conn.snapshot_id}")
print(f"Status:      {conn.current_status}")

5

Connection Lifecycle

Open and close connections

close()

Close the underlying HTTP connection. After calling close(), further queries will fail.

Context Manager

InstanceConnection implements __enter__ / __exit__, so you can use it in a with block for automatic cleanup.

# Explicit close
tmp_conn = client.instances.connect(conn.id)
count = tmp_conn.query_scalar("MATCH (n) RETURN count(n)")
print(f"Nodes: {count}")
tmp_conn.close()

# Context manager -- connection closes automatically
with client.instances.connect(conn.id) as c:
    count = c.query_scalar("MATCH (n) RETURN count(n)")
    print(f"Nodes: {count}")
# c is closed here

Key Takeaways

• query() returns a QueryResult that is iterable as dicts and convertible to Polars, Pandas, NetworkX, CSV, and Parquet
• query_df() is a shortcut that returns a DataFrame directly (Polars by default)
• query_scalar() and query_one() simplify single-value and single-row lookups
• get_schema() reveals node labels, relationship types, and their properties
• Use the context manager (with) to ensure connections are closed automatically