Skip to content
nx-neptune
Blog

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”

  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)

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.

from nx_neptune.session_manager import SessionManager


session = SessionManager(
    graph_id="my-graph",
    region="us-west-2",
    iam_role_arn="arn:aws:iam::123456789012:role/NeptuneRole",
    s3_import_path="s3://my-bucket/import/",
    s3_export_path="s3://my-bucket/export/",
)


# Create graph, import data, run algorithms, export, destroy

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”