Skip to content

Session Manager

The SessionManager API manages the full lifecycle of a Neptune Analytics graph for data lake analytics: create → import → analyze → export → destroy.

This is the primary interface for the “Graph Over Data Lake” workflow — run graph algorithms on data that lives in your data lake without moving it permanently into a graph database.

  1. Define your data source — point to S3 Tables, Databricks, Snowflake, OpenSearch, or any Athena-accessible source

  2. Create a graph — SessionManager provisions a Neptune Analytics instance

  3. Import data — project your tabular data into graph form via Athena SQL queries

  4. Analyze — run graph algorithms (community detection, centrality, traversal) or explore with openCypher

  5. Export results — write results back to S3 or persist as Iceberg tables

  6. Destroy — tear down the graph when done (no ongoing cost)

Source Connector Demo
Amazon S3 Tables Native Athena SQL Notebook
Amazon S3 Vectors Custom Athena connector Notebook
Databricks Unity Catalog JDBC-based Athena connector Notebook
Snowflake Athena Snowflake connector Notebook
Amazon OpenSearch Athena OpenSearch connector Notebook
Any Athena source 25+ federated connectors —

For data already in S3-compatible formats (CSV, Parquet), Neptune Analytics also supports native S3 import without Athena.

  • Fraud detection — project financial transactions as a graph, run Louvain to identify fraud rings
  • Product recommendation — project product catalogs with vector embeddings, run similarity search

The SessionManager class is in nx_neptune/session_manager.py.

SessionManager(session_name=None, cleanup_task=None) takes only a session name and an optional cleanup task. It uses the AWS credentials and default region from your environment, and the caller identity of those credentials as the S3 import/export role. S3 locations are passed to the methods that use them.

async with is the recommended form: the create methods are async, so your code is already running inside an event loop, and __aexit__ awaits the cleanup on that same loop.

from nx_neptune.session_manager import CleanupTask, SessionManager
async with SessionManager.session("my-session", CleanupTask.STOP) as session:
graph = await session.get_or_create_graph()
await session.import_from_csv(graph, "s3://my-bucket/import/")
# ... run algorithms ...
await session.export_to_csv(graph, "s3://my-bucket/export/")
# the cleanup task runs here, on the way out of the block

On exit, the configured CleanupTask runs over the session’s AVAILABLE graphs and is awaited to completion, so leaving the block can take minutes:

Task On exit
STOP Stops each graph. Storage still bills, compute does not.
RESET Empties each graph, without taking a snapshot.
DESTROY Deletes each graph.
unset Nothing — the graphs keep running and billing.

A graph in any other status, STOPPED included, is skipped with a warning. STOP, RESET and DESTROY each require a session_name. Without a with or async with block nothing is cleaned up.

Instead of hand-writing the Athena SELECT statements that alias source columns into Neptune’s load format (~id/~label for vertices, ~from/~to/~label for edges), you can declare the mapping with the standard SQL/PGQ (SQL:2023) CREATE PROPERTY GRAPH DDL. import_from_graph_schema translates the DDL into those projection queries and runs the same Athena → S3 → Neptune import path as import_from_table:

DDL = """
CREATE PROPERTY GRAPH financial
VERTEX TABLES (
accounts AS customer KEY (name) LABEL customer PROPERTIES (name)
)
EDGE TABLES (
transactions
SOURCE KEY (nameOrig) REFERENCES customer
DESTINATION KEY (nameDest) REFERENCES customer
LABEL transfer
PROPERTIES (step, CAST(amount AS DOUBLE) AS amount, isFraud)
)
"""
graph = await session.get_or_create_graph()
await session.import_from_graph_schema(
graph, s3_location, DDL, catalog=catalog, database=database
)

Property types are read from the Athena catalog, and CAST overrides them. Omitting PROPERTIES exposes all columns. See Property Graph Schema for the full syntax, type rules and required permissions.

For explicit control over Neptune Analytics instance lifecycle (create, start, stop, delete), see the instance management module:

Configuration settings are handled through the NeptuneConfig class in nx_plugin/config.py.