apache/age

GitHub: apache/age

Apache AGE 是一个 PostgreSQL 扩展，为关系型数据库添加 openCypher 图查询能力，实现 SQL 与图数据的统一存储和处理。

Stars: 4602 | Forks: 503

is a leading multi-model graph database

关系型数据库的图处理与分析

What is Apache AGE?

[Apache AGE](https://age.apache.org/#) 是一个 PostgreSQL 扩展，允许用户在现有的关系型数据库之上利用图数据库。AGE 是 A Graph Extension 的首字母缩写，其灵感来源于 Bitnine 的 AgensGraph（PostgreSQL 的一个多模型数据库分支）。该项目的基本原理是创建一个单一存储，同时处理关系和图数据模型，以便用户可以使用标准的 ANSI SQL 以及当今最流行的图查询语言之一 openCypher。目前对内聚、易于实现的多模型数据库有着强烈的需求。作为 PostgreSQL 的扩展，AGE 不仅支持 PostgreSQL 的所有功能和特性，同时还提供了图模型。

Overview

Apache AGE 是： - **强大**：为已经非常流行的 PostgreSQL 数据库添加了图数据库支持：PostgreSQL 被 Apple、Spotify 和 NASA 等组织使用。 - **灵活**：允许您执行 openCypher 查询，使复杂的查询更容易编写。它还支持同时查询多个图。 - **智能**：允许您执行图查询，这是许多高级 Web 服务的基础，例如欺诈检测、主数据管理、产品推荐、身份与关系管理、体验个性化、知识管理等。

Features

- **Cypher 查询**：支持图查询语言 - **混合查询**：启用 SQL 和/或 Cypher - **查询**：支持多个图 - **分层**：图标签组织 - **属性索引**：支持顶点和边 - **完整的 PostgreSQL**：支持 PG 功能

Documentation

请参阅我们最新的 [Apache AGE 文档](https://age.apache.org/age-manual/master/index.html) 以了解安装、功能、内置函数和 Cypher 查询。

Pre-Installation

根据每个操作系统安装以下必备库。从源代码构建 AGE 依赖于以下 Linux 库（下面显示的是 Ubuntu 软件包名称）： - **CentOS** ``` yum install gcc glibc glib-common readline readline-devel zlib zlib-devel flex bison ``` - **Fedora** ``` dnf install gcc glibc bison flex readline readline-devel zlib zlib-devel ``` - **Ubuntu** ``` sudo apt-get install build-essential libreadline-dev zlib1g-dev flex bison ```

Installation

Apache AGE 旨在易于安装和运行。它可以通过 Docker 和其他传统方式进行安装。

Install PostgreSQL

您需要安装兼容 AGE 版本的 Postgres，目前 AGE 支持 Postgres 11、12、13、14、15、16、17 和 18。支持最新版本已列入 AGE 的路线图。

通过包管理器安装

您可以使用您的操作系统提供的包管理器来下载 PostgreSQL。
``` sudo apt install postgresql ```

从源代码安装

您可以下载 Postgres 源代码并安装您自己的 Postgres 实例。您可以在Postgres 官方网站上阅读有关如何为不同版本从源代码安装的说明。

Install AGE on Linux and MacOS

克隆 GitHub 仓库或下载官方发布版本。运行 pg_config 实用程序并检查 PostgreSQL 的版本。目前，仅支持 PostgreSQL 版本 11、12、13、14、15、16、17 和 18。如果您使用的是任何其他版本的 Postgres，您将需要安装 PostgreSQL 版本 11、12、13、14、15、16、17 或 18。
``` pg_config ``` 在 Apache AGE 的源代码目录中运行以下命令来构建和安装该扩展。 ``` make install ``` 如果您的 Postgres 安装路径不在 PATH 变量中，请在参数中添加该路径： ``` make PG_CONFIG=/path/to/postgres/bin/pg_config install ```

Run using Docker

获取 docker 镜像

``` docker pull apache/age ```

创建 AGE docker 容器

``` docker run \ --name age \ -p 5455:5432 \ -e POSTGRES_USER=postgresUser \ -e POSTGRES_PASSWORD=postgresPW \ -e POSTGRES_DB=postgresDB \ -d \ apache/age ```

进入 PostgreSQL 的 psql：

``` docker exec -it age psql -d postgresDB -U postgresUser ```

Post Installation

对于您启动的每个 AGE 连接，您都需要加载 AGE 扩展。 ``` CREATE EXTENSION age; ``` ``` LOAD 'age'; ``` ``` SET search_path = ag_catalog, "$user", public; ```

Using AGE with Non-Autocommit Clients (psycopg, JDBC, etc.)

如果您从**不**默认启用 autocommit 的数据库客户端使用 AGE（最常见的是 `psycopg` v3 或 JDBC），您必须了解 PostgreSQL 的事务语义如何应用于 AGE 的设置和类 DDL 函数。否则，您可能会看到图或标签看似创建成功，但从新连接中却不可见。这**不是** AGE 的 bug——这是 PostgreSQL 的标准行为。AGE 的类 DDL 函数会写入 catalog，而对 catalog 的写入只有在包含它的事务被提交后，才会对其他会话可见。 ### 哪些是事务性的，哪些不是 | 语句 | 作用域 | 需要提交才能在其他地方可见吗？ | |---|---|---| | `LOAD 'age'` | 会话级（将 .so 加载到当前后端） | 否 | | `SET search_path = ag_catalog, "$user", public` | 会话级 | 否 | | `SELECT create_graph('g')` | **写入**到 `ag_graph` 并创建一个 schema | **是** | | `SELECT create_vlabel('g', 'L')` / `create_elabel(...)` | **写入**到 `ag_label` 并创建一个表 | **是** | | `SELECT drop_graph('g', true)` / `drop_label(...)` | **写入**到 catalog | **是** | | `SELECT load_labels_from_file(...)` / `load_edges_from_file(...)` | **写入**到 catalog 和数据 | **是** | | `cypher('g', $$ CREATE (:L {...}) $$)` | **写入**数据 | **是** | 在默认启用 autocommit 的客户端（例如 `psql`）中，每条语句都会自动提交，因此绝不会出现这个问题。在非 autocommit 客户端中，您运行的第一条语句会隐式打开一个事务，该事务将保持打开状态，直到您调用 `commit()`、`rollback()` 或关闭连接。 ### psycopg v3 —— “savepoint 陷阱” 常见的陷阱是，在 psycopg 中，当已经存在打开的事务时，`with connection.transaction():` 并**不会**启动一个新的顶级事务，而是会在现有的外部事务中创建一个**保存点**。释放保存点并不是提交，因此您的 `create_graph` 写入在显式提交外部事务之前，对其他会话保持不可见。 #### ❌ 损坏：图从新连接中不可见 ``` import psycopg params = {"host": "localhost", "port": 5432, "user": "postgres", "password": "pw", "dbname": "mydb"} # --- 首次连接 --- conn = psycopg.connect(**params) conn.execute("LOAD 'age'") # implicitly opens a txn conn.execute("SET search_path = ag_catalog, '$user', public") with conn.transaction(), conn.cursor() as cur: # <-- SAVEPOINT, not a real txn cur.execute("SELECT * FROM create_graph('my_graph')") # 外部事务在这里仍然 OPEN conn.close() # outer transaction is rolled back on close → my_graph is gone # --- 新连接 --- conn = psycopg.connect(**params) conn.execute("LOAD 'age'") conn.execute("SET search_path = ag_catalog, '$user', public") with conn.cursor() as cur: cur.execute("SELECT name FROM ag_graph;") # 'my_graph' is NOT in the results ``` #### ✅ 修复 1：在设置后显式 `commit()` ``` conn = psycopg.connect(**params) conn.execute("LOAD 'age'") conn.execute("SET search_path = ag_catalog, '$user', public") conn.commit() # <-- closes the implicit outer txn with conn.transaction(), conn.cursor() as cur: cur.execute("SELECT * FROM create_graph('my_graph')") # 此事务块现在是顶层并在退出时提交 conn.close() ``` #### ✅ 修复 2：在连接上启用 autocommit ``` conn = psycopg.connect(**params, autocommit=True) conn.execute("LOAD 'age'") conn.execute("SET search_path = ag_catalog, '$user', public") conn.execute("SELECT * FROM create_graph('my_graph')") # commits immediately conn.close() ``` 您还可以在运行时使用 `conn.set_autocommit(True)` 切换 autocommit。 ### JDBC 根据 JDBC 规范，JDBC 连接也默认设置为 autocommit **true**，但许多框架（Spring 等）会将其关闭。如果您通过 JDBC 运行 AGE 的类 DDL 调用，可以执行以下任一操作： ``` connection.setAutoCommit(true); // ... LOAD 'age'; SET search_path ...; SELECT create_graph(...); ``` 或者保持关闭 autocommit 并在类 DDL 调用后显式提交： ``` stmt.execute("LOAD 'age'"); stmt.execute("SET search_path = ag_catalog, \"$user\", public;"); stmt.execute("SELECT create_graph('my_graph');"); connection.commit(); // make the graph visible to other sessions ``` ### 经验法则

Quick Start

要创建图，请使用位于 ag_catalog 命名空间中的 create_graph 函数。 ``` SELECT create_graph('graph_name'); ``` 要创建带有标签和属性的单个顶点，请使用 CREATE 子句。 ``` SELECT * FROM cypher('graph_name', $$ CREATE (:label {property:"Node A"}) $$) as (v agtype); ``` ``` SELECT * FROM cypher('graph_name', $$ CREATE (:label {property:"Node B"}) $$) as (v agtype); ``` 要在两个节点之间创建边并设置其属性： ``` SELECT * FROM cypher('graph_name', $$ MATCH (a:label), (b:label) WHERE a.property = 'Node A' AND b.property = 'Node B' CREATE (a)-[e:RELTYPE {property:a.property + '<->' + b.property}]->(b) RETURN e $$) as (e agtype); ``` 并查询连接的节点： ``` SELECT * from cypher('graph_name', $$ MATCH (V)-[R]-(V2) RETURN V,R,V2 $$) as (V agtype, R agtype, V2 agtype); ```

Language Specific Drivers

开始使用 Apache AGE 非常简单。您可以轻松选择您的平台并将相关的 SDK 整合到您的代码中。

内置

- [Go 驱动程序](./drivers/golang) - [Java 驱动程序](./drivers/jdbc) - [NodeJs 驱动程序](./drivers/nodejs) - [Python 驱动程序](./drivers/python)

社区驱动的驱动程序

- [Apache AGE Rust 驱动程序](https://github.com/Dzordzu/rust-apache-age.git) - [Apache AGE .NET 驱动程序](https://github.com/Allison-E/pg-age)

Graph Visualization Tool for AGE

Apache AGE Viewer 是 Apache AGE 的用户界面，提供数据的可视化和探索功能。这个 Web 可视化工具允许用户输入复杂的图查询，并以图形和表格的形式探索结果。 Apache AGE Viewer 得到了增强，能够处理大量的图数据，并通过各种图算法发现洞察力。 Apache AGE Viewer 将成为 Apache AGE 的图数据管理和开发平台，以支持多种关系型数据库：。 **这是一个可视化工具。** 安装 AGE 扩展后，您可以使用此工具来访问可视化功能。 ![Viewer gdb, and graph](/img/agce.gif)

Video Links

您还可以从这些视频中获取帮助。 - 在 [Windows](https://www.youtube.com/watch?v=ddk8VX8Hm-I&list=PLGp3huJbWNDjgwP7s99Q-9_w1vxpjNHXG) 上安装 - 在 [MacOS](https://www.youtube.com/watch?v=0-qMwpDh0CA) 上安装

Contributing

您可以通过向[此仓库](https://github.com/apache/age)发送 pull request 来改进正在进行的工作或发起新的工作。此外，您可以通过访问 [Apache AGE 官方网站 - 开发者指南](https://age.apache.org/contribution/guide)，从代码审查流程中学习如何合并 pull request，并了解从代码风格合规性到文档编写的知识。请将所有的意见和建议发送至用户邮件列表：users@age.apache.org。

标签：PostgreSQL扩展, 代码示例, 多云安全, 多模型数据库, 多线程, 客户端加密, 数据分析, 数据库, 测试用例, 请求拦截