Skip to content
VioGraph Docs

Result Formats

Tutorial

Result Formats

Convert query results to DataFrames, CSV, Parquet, and more

25 min Intermediate
QueryResultPolarsPandasExportDataFrame

What You'll Learn

  • Query Methods - Choose between query, query_df, query_scalar, and query_one
  • Result Metadata - Inspect columns, types, row counts, and execution time
  • DataFrame Conversion - Convert results to Polars and Pandas DataFrames
  • File Export - Save results as CSV and Parquet files
1

Setup

Connect to the platform and provision tutorial resources

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running
# Cell 2 — Connect and provision
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)


from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]


print(f"Connected | {conn.query_scalar('MATCH (n) RETURN count(n)')} nodes")
2

Choosing the Right Query Method

Compare query, query_df, query_scalar, and query_one

# query() returns a full QueryResult with metadata and conversion methods
result = conn.query("MATCH (c:Customer) RETURN c.id AS id, c.id AS name LIMIT 5")
print(f"query()       -> {type(result).__name__}  ({result.row_count} rows)")


# query_df() returns a DataFrame directly (polars by default)
df = conn.query_df("MATCH (c:Customer) RETURN c.id AS id, c.id AS name LIMIT 5")
print(f"query_df()    -> {type(df).__name__}  ({len(df)} rows)")


# query_scalar() returns a single value
count = conn.query_scalar("MATCH (n) RETURN count(n)")
print(f"query_scalar() -> {type(count).__name__}  (value={count})")


# query_one() returns a single row as a dict, or None
row = conn.query_one("MATCH (c:Customer) RETURN c.id AS id, c.id AS name LIMIT 1")
print(f"query_one()   -> {type(row).__name__}  (keys={list(row.keys())})")
3

QueryResult Metadata

Inspect columns, types, row counts, and execution time

# Run a query and inspect the result metadata
result = conn.query(
    "MATCH (c:Customer) RETURN c.id AS id, c.id AS name, c.bk_sectr AS sector LIMIT 10"
)


print(f"Columns:        {result.columns}")
print(f"Column types:   {result.column_types}")
print(f"Row count:      {result.row_count}")
print(f"Execution time: {result.execution_time_ms} ms")
print(f"Length (len()): {len(result)}")
4

DataFrame Conversion

Convert results to Polars and Pandas DataFrames

# Convert QueryResult to a Polars DataFrame
polars_df = result.to_polars()
print("=== to_polars() ===")
print(f"Type: {type(polars_df).__module__}.{type(polars_df).__name__}")
print(polars_df)


# Convert QueryResult to a Pandas DataFrame
pandas_df = result.to_pandas()
print("\n=== to_pandas() ===")
print(f"Type: {type(pandas_df).__module__}.{type(pandas_df).__name__}")
print(pandas_df.head())
# query_df() with explicit backend selection
cypher = "MATCH (c:Customer) RETURN c.id AS id, c.id AS name LIMIT 5"


# Polars backend (default)
df_polars = conn.query_df(cypher, backend="polars")
print(f"backend='polars' -> {type(df_polars).__module__}.{type(df_polars).__name__}")


# Pandas backend
df_pandas = conn.query_df(cypher, backend="pandas")
print(f"backend='pandas' -> {type(df_pandas).__module__}.{type(df_pandas).__name__}")
5

Dictionary Access

Iterate rows, convert to dicts, and extract scalars

result = conn.query(
    "MATCH (c:Customer) RETURN c.id AS id, c.id AS name LIMIT 3"
)


# Iterate rows as dicts
print("=== Iteration (for row in result) ===")
for row in result:
    print(f"  {row}")


# to_dicts() returns a list of dicts
print(f"\n=== to_dicts() ===")
dicts = result.to_dicts()
print(f"  Type: {type(dicts).__name__}, length: {len(dicts)}")
print(f"  First: {dicts[0]}")
print(f"  Third: {dicts[2]}")


# scalar() extracts a single value from a single-column, single-row result
count_result = conn.query("MATCH (n) RETURN count(n) AS total")
print(f"\n=== scalar() ===")
print(f"  count_result.scalar() = {count_result.scalar()}")
6

File Export

Save query results as CSV and Parquet files

import os


# Query customer data for export
result = conn.query(
    "MATCH (c:Customer) RETURN c.id AS id, c.id AS name, c.bk_sectr AS sector LIMIT 100"
)


# Export to CSV
csv_path = "/tmp/customers_export.csv"
result.to_csv(csv_path)
csv_size = os.path.getsize(csv_path)
print(f"Exported CSV:     {csv_path} ({csv_size:,} bytes)")


# Export to Parquet
parquet_path = "/tmp/customers_export.parquet"
result.to_parquet(parquet_path)
parquet_size = os.path.getsize(parquet_path)
print(f"Exported Parquet: {parquet_path} ({parquet_size:,} bytes)")


print(f"\nCompression ratio: {csv_size / parquet_size:.1f}x (CSV/Parquet)")
7

Display

Auto-formatted Jupyter output with result.show()

# show() renders an auto-formatted table in Jupyter
result = conn.query(
    "MATCH (c:Customer) RETURN c.id AS id, c.id AS name, c.bk_sectr AS sector LIMIT 5"
)
result.show()

Key Takeaways

  • Use query() for full control over results, query_df() to go straight to a DataFrame
  • query_scalar() and query_one() are shortcuts for single-value and single-row results
  • QueryResult exposes columns, column_types, row_count, and execution_time_ms for metadata inspection
  • to_polars() and to_pandas() convert results into DataFrames for analysis
  • to_csv() and to_parquet() export results directly to files -- Parquet is significantly smaller
  • show() provides auto-formatted display in Jupyter notebooks