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.
How it works
Section titled “How it works”-
Define your data source — point to S3 Tables, Databricks, Snowflake, OpenSearch, or any Athena-accessible source
-
Create a graph — SessionManager provisions a Neptune Analytics instance
-
Import data — project your tabular data into graph form via Athena SQL queries
-
Analyze — run graph algorithms (community detection, centrality, traversal) or explore with openCypher
-
Export results — write results back to S3 or persist as Iceberg tables
-
Destroy — tear down the graph when done (no ongoing cost)
Supported data sources
Section titled “Supported data sources”| 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.
Use cases
Section titled “Use cases”- 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
API overview
Section titled “API overview”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 blockOn 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.
Declaring the graph schema
Section titled “Declaring the graph schema”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.
Instance management
Section titled “Instance management”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.
Notebooks
Section titled “Notebooks”- SessionManager comprehensive demo — full create → import → analyze → export → destroy workflow
- S3 import/export demo — import from and export to S3