Amazon Neptune 图存储

# 部署 Neptune 栈（大约需要 15-20 分钟）
# 将 203.0.113.25/32 替换为你自己的公网 IP（运行 `curl ifconfig.me` 查找）
# 或你的办公室/VPN CIDR。这会在网络层面限制谁能访问数据库——
# 除了短期的本地实验外，绝不要将其放宽到 0.0.0.0/0。
aws cloudformation create-stack \
  --stack-name semantica-neptune \
  --template-body file://neptune-setup.yaml \
  --parameters ParameterKey=ClientCidr,ParameterValue=203.0.113.25/32 \
  --capabilities CAPABILITY_NAMED_IAM

# 等待栈创建完成
aws cloudformation wait stack-create-complete --stack-name semantica-neptune

# 获取输出（端点、端口、凭证）
aws cloudformation describe-stacks --stack-name semantica-neptune \
  --query 'Stacks[0].Outputs' --output table

# 删除 CloudFormation 栈
aws cloudformation delete-stack --stack-name semantica-neptune

# 安装带 Neptune 支持的 Semantica
pip install semantica

# 所需依赖（自动安装）
pip install boto3 neo4j

# 安装 semantica 包
!pip install semantica

import os

# Neptune 集群配置 - 替换为你的值
# （从 CloudFormation 栈输出中获取这些值）
os.environ["NEPTUNE_ENDPOINT"] = "your-cluster.us-east-1.neptune.amazonaws.com"
os.environ["NEPTUNE_PORT"] = "8182"
os.environ["AWS_REGION"] = "us-east-1"

# 用于 IAM 认证的 AWS 凭证
# 选项 1：IAM 用户（来自 CloudFormation 模板的静态凭证）
# os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..."  # 来自 AwsAccessKeyId 输出
# os.environ["AWS_SECRET_ACCESS_KEY"] = "..."  # 来自 AwsSecretAccessKey 输出
# 注意：IAM 用户不需要 AWS_SESSION_TOKEN

# 选项 2：IAM 角色 / 临时凭证（例如 STS AssumeRole、EC2 实例角色）
# os.environ["AWS_ACCESS_KEY_ID"] = "ASIA..."  # 临时访问密钥
# os.environ["AWS_SECRET_ACCESS_KEY"] = "..."  # 临时秘密密钥
# os.environ["AWS_SESSION_TOKEN"] = "..."      # 临时凭证必需

print(f"Neptune Endpoint: {os.environ.get('NEPTUNE_ENDPOINT')}")
print(f"AWS Region: {os.environ.get('AWS_REGION')}")

import os
from semantica.graph_store import GraphStore

# 选项 1：使用 GraphStore 工厂（推荐）
neptune_store = GraphStore(
    backend="neptune",
    endpoint=os.environ.get("NEPTUNE_ENDPOINT"),
    port=int(os.environ.get("NEPTUNE_PORT", 8182)),
    region=os.environ.get("AWS_REGION", "us-east-1"),
    iam_auth=True,
)

# 连接到 Neptune
neptune_store.connect()
print("Connected to Amazon Neptune!")

# 用于无 IAM 认证的开发/测试环境
neptune_store_dev = GraphStore(
    backend="neptune",
    endpoint=os.environ.get("NEPTUNE_ENDPOINT"),
    port=int(os.environ.get("NEPTUNE_PORT", 8182)),
    region=os.environ.get("AWS_REGION", "us-east-1"),
    iam_auth=False,  # 为开发/测试禁用 IAM 签名
)
neptune_store_dev.connect()

# 使用自定义 ID 创建单个节点（id 在属性中）
alice = neptune_store.create_node(
    labels=["Person"],
    properties={"id": "alice", "name": "Alice", "age": 30, "role": "Engineer"}
)
print(f"Created node: {alice}")

# 使用自动生成的 UUID 创建节点（属性中无 id）
bob = neptune_store.create_node(
    labels=["Person"],
    properties={"name": "Bob", "age": 25, "role": "Designer"}
)
print(f"Created node with UUID: {bob['id']}")

# 使用自动生成的 ID 创建公司节点
acme = neptune_store.create_node(
    labels=["Company"],
    properties={"name": "Acme Corp", "industry": "Technology", "founded": 2010}
)
print(f"Created company: {acme}")

# 批量创建节点以获得更好的性能
# 在属性中包含 'id' 以使用自定义 ID
nodes_data = [
    {"labels": ["Person"], "properties": {"id": "charlie", "name": "Charlie", "age": 35}},
    {"labels": ["Person"], "properties": {"id": "diana", "name": "Diana", "age": 28}},
    {"labels": ["Location"], "properties": {"name": "San Francisco", "state": "CA"}},
]

created_nodes = neptune_store.create_nodes(nodes_data)
print(f"Created {len(created_nodes)} nodes in batch")

# 按 ID 获取特定节点
alice_node = neptune_store.get_node(node_id="alice")
print(f"Retrieved: {alice_node}")

# 按标签获取节点
people = neptune_store.get_nodes(labels=["Person"], limit=10)
print(f"Found {len(people)} Person nodes:")
for person in people:
    print(f"  - {person.get('properties', {}).get('name')}")

# 按属性获取节点
engineers = neptune_store.get_nodes(
    labels=["Person"],
    properties={"role": "Engineer"},
    limit=5
)
print(f"Found {len(engineers)} engineers")

# 更新节点属性（合并模式 - 默认）
updated_alice = neptune_store.update_node(
    node_id="alice",
    properties={"age": 31, "department": "AI Research"},
    merge=True
)
print(f"Updated Alice: {updated_alice}")

# 替换所有属性（merge=False）
# 警告：这会移除不在更新中的属性
replaced = neptune_store.update_node(
    node_id="charlie",
    properties={"name": "Charlie", "age": 36},
    merge=False
)

# 删除节点（使用 detach=True 同时删除关系）
deleted = neptune_store.delete_node(node_id="diana", detach=True)
print(f"Deleted diana: {deleted}")

# 不使用 detach（如果节点有关系则会失败）
# neptune_store.delete_node(node_id="alice", detach=False)

# 在 Alice 和 Acme 之间创建关系
works_at = neptune_store.create_relationship(
    start_node_id="alice",
    end_node_id=acme["id"],
    rel_type="WORKS_AT",
    properties={"since": 2020, "position": "Senior Engineer"}
)
print(f"Created relationship: {works_at}")

# 在人与人之间创建 KNOWS 关系
knows_rel = neptune_store.create_relationship(
    start_node_id="alice",
    end_node_id=bob["id"],
    rel_type="KNOWS",
    properties={"since": 2019}
)

# 获取某个节点的所有关系
alice_rels = neptune_store.get_relationships(node_id="alice", direction="both")
print(f"Alice has {len(alice_rels)} relationships")

# 仅获取出向关系
outgoing = neptune_store.get_relationships(node_id="alice", direction="out")

# 按关系类型过滤
works_rels = neptune_store.get_relationships(
    node_id="alice",
    rel_type="WORKS_AT",
    direction="out"
)
print(f"Alice's work relationships: {len(works_rels)}")

# 按 ID 删除特定关系
if works_at.get("id"):
    deleted = neptune_store.delete_relationship(rel_id=works_at["id"])
    print(f"Deleted relationship: {deleted}")

# 简单查询
results = neptune_store.execute_query(
    "MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age"
)
print("People in the graph:")
for record in results.get("records", []):
    print(f"  - {record.get('p.name')}: {record.get('p.age')} years old")

# 使用参数（更安全、更高效）
results = neptune_store.execute_query(
    "MATCH (p:Person) WHERE p.age > $min_age RETURN p.name, p.age",
    parameters={"min_age": 25}
)
print(f"People over 25: {len(results.get('records', []))}")

# 查找节点之间的关系
results = neptune_store.execute_query("""
    MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
    RETURN p.name as employee, c.name as company, r.since as start_year
""")
for record in results.get("records", []):
    print(f"{record['employee']} works at {record['company']} since {record['start_year']}")

# 计数和聚合
results = neptune_store.execute_query("""
    MATCH (p:Person)
    RETURN count(p) as total, avg(p.age) as avg_age, max(p.age) as max_age
""")
stats = results.get("records", [{}])[0]
print(f"Total: {stats.get('total')}, Avg Age: {stats.get('avg_age'):.1f}")

# 获取直接邻居（depth=1）
neighbors = neptune_store.get_neighbors(
    node_id="alice",
    direction="both",
    depth=1
)
print(f"Alice's direct neighbors: {len(neighbors)}")

# 获取最多 2 跳之外的邻居
extended = neptune_store.get_neighbors(
    node_id="alice",
    direction="out",
    depth=2
)
print(f"Nodes within 2 hops: {len(extended)}")

# 查找最短路径
path = neptune_store.shortest_path(
    start_node_id="alice",
    end_node_id="charlie",
    max_depth=5
)

if path:
    print("Path found!")
    print(f"  Length: {path.get('length')}")
    print(f"  Nodes: {len(path.get('nodes', []))}")
    print(f"  Relationships: {len(path.get('relationships', []))}")
else:
    print("No path found between nodes")

# 获取图统计信息
stats = neptune_store.get_stats()

print("Graph Statistics:")
print(f"  Total nodes: {stats.get('node_count', 'N/A')}")
print(f"  Total relationships: {stats.get('relationship_count', 'N/A')}")

print("\nNode labels:")
for label, count in stats.get('label_counts', {}).items():
    print(f"  - {label}: {count}")

print("\nRelationship types:")
for rel_type, count in stats.get('relationship_type_counts', {}).items():
    print(f"  - {rel_type}: {count}")

# 检查连接状态
status = neptune_store.get_status()
print(f"Connection status: {status}")

# 关闭连接
neptune_store.close()
print("Connection closed")

# 使用自定义 ID 创建节点（在属性中包含 'id'）
node = neptune_store.create_node(
    labels=["Person"],
    properties={"id": "my-custom-id", "name": "Test"}
)

# 使用自动生成的 UUID 创建节点（从属性中省略 'id'）
node = neptune_store.create_node(
    labels=["Person"],
    properties={"name": "Test"}
)

# 该 ID 在内部用于 id() 函数调用：
# MATCH (n) WHERE id(n) = 'my-custom-id' RETURN n