Helm7

Apache AGE, and an alternative: your own tables as the graph

Apache AGE is a PostgreSQL extension that adds the openCypher graph query language, so you can store and query graphs next to your relational data. It is the right choice when you want Cypher inside Postgres and your host lets you install it. If your relationships already live in tables and foreign keys, an alternative is to treat those tables as the graph and walk them with recursive SQL.

Checked against current documentation on 16 November 2026.

What Apache AGE is

AGE stands for A Graph Extension. It is an Apache project, licensed under Apache 2.0. Its GitHub page describes it as an extension for PostgreSQL that lets you use a graph database on top of an existing relational database, and says it supports Postgres 11 to 18. You can run openCypher queries alongside ordinary SQL. See the Apache AGE repository.

openCypher is the graph query language AGE speaks. You describe a pattern of nodes and edges, and the database finds every match. For questions such as "who is within three hops of Ada", that is often shorter than the SQL equivalent.

CREATE EXTENSION age;
LOAD 'age';
SET search_path = ag_catalog, "$user", public;

SELECT create_graph('social');

SELECT * FROM cypher('social', $$
    CREATE (:Person {name: 'Ada'})-[:KNOWS]->(:Person {name: 'Grace'})
$$) AS (result agtype);

SELECT * FROM cypher('social', $$
    MATCH (a:Person {name: 'Ada'})-[:KNOWS*1..3]->(b:Person)
    RETURN b.name
$$) AS (name agtype);
AGE in use. Cypher runs inside a cypher() function call in ordinary SQL, and results come back as the agtype type. The setup lines follow AGE's README: the extension must be loaded on every connection.

That wrapping is worth noticing. The Cypher is a string inside SQL, and you declare the result columns after it. Results come back as agtype, AGE's own value type, so your driver or your code needs to handle that.

How AGE stores a graph

AGE keeps graphs in tables, but not yours. The AGE manual says each graph gets its own Postgres schema, which is recorded in a table called ag_graph. Creating a graph also creates two parent tables there, one for vertices and one for edges. Every new vertex label or edge label gets its own table, and a catalogue table called ag_label tracks them. A Cypher CREATE makes these tables for you.

The manual recommends running no DML or DDL commands in a graph's reserved namespace. In practice, you work through Cypher and let AGE manage the tables.

This design has a consequence. The graph is its own set of tables. Your customers table and your orders table are not in it unless you load them. If your application data is already relational, you either keep a graph copy in step with it, or you move the relationships into AGE and treat it as the source of truth for them. Neither is wrong, but both are work.

Can you run it where your database lives?

An extension has to be installed on the database server, so a managed host decides for you. Microsoft documents Apache AGE as an extension on Azure Database for PostgreSQL. You add it to two server parameters, azure.extensions and shared_preload_libraries, and run CREATE EXTENSION. Microsoft notes that once it is preloaded, you should not run LOAD 'age', because that gives a privilege error. The server restarts when you save the change. See the Azure AGE overview.

On other hosts, check. When checked on 16 November 2026, the AWS list of extensions for RDS for PostgreSQL did not include age in its tables for versions 16 to 19. Lists change, so look at your own provider's current page before you plan around it. If you run your own Postgres, you can build and install AGE yourself, at the cost of owning the upgrades.

Version support is the other thing to check. AGE's README lists Postgres 11 to 18. A host that moves to a newer major version before AGE supports it can leave you waiting. Ask which AGE version matches which Postgres version on your provider.

When AGE is the right choice

  • You want Cypher, and you want it inside Postgres rather than in a second database. Your team already thinks in patterns of nodes and edges.
  • Your graph is its own thing, such as a knowledge graph, a fraud network or a recommendation graph, and not a view over tables you already have.
  • Your questions are pattern matches with variable-length paths, which is where Cypher reads far better than SQL.
  • You want graph and relational data to share one transaction, one backup and one connection pool.
  • Your host supports it, or you run Postgres yourself and are happy to manage the extension.

If you want large-scale graph algorithms such as community detection across a very big graph, check whether AGE's feature set covers them before you commit. Neo4j documents a Graph Data Science library with these built in. A dedicated graph database may be the better home for that workload.

A short checklist before you choose

  1. 1Write down five real questionsTake the graph questions your product needs to answer. Count the hops in each. If most are one to four hops from a known row, recursive SQL will cope. If several are open-ended patterns, lean towards Cypher.
  2. 2Check where your data livesIf the relationships are already foreign keys, AGE means a second copy or a migration. If the graph is new data with no tables behind it, AGE has no such cost.
  3. 3Check your hostLook at your provider's current extension list and the Postgres versions AGE supports there. Do this before you design anything around it.
  4. 4Check your permissions modelIf you use row level security today, work out how the same rules will apply to graph data. With your own tables they apply as they are. With a separate graph, you rebuild them.
  5. 5Try the smaller option firstA recursive query on your own tables takes an afternoon to try, and you can always move to AGE or Neo4j later if the questions outgrow it.

None of these steps rules AGE out. They make sure you pick it because you need Cypher, not because "graph" sounded like it needed a graph product.

The alternative: your tables are already a graph

Rows are nodes. Foreign keys and join tables are edges. A recursive common table expression walks them. PostgreSQL 14 added the SQL-standard CYCLE clause, which stops a walk from looping. The details are in can Postgres be your graph database.

-- The same question as the Cypher above, on ordinary tables.
-- Everyone within three hops of Ada, loops cut.
WITH RECURSIVE reach(id, depth) AS (
    SELECT f.followee_id, 1
    FROM follows f
    JOIN person p ON p.id = f.follower_id
    WHERE p.name = 'Ada'
  UNION ALL
    SELECT f.followee_id, r.depth + 1
    FROM follows f
    JOIN reach r ON f.follower_id = r.id
    WHERE r.depth < 3
) CYCLE id SET is_cycle USING path
SELECT p.name, min(r.depth) AS hops
FROM reach r
JOIN person p ON p.id = r.id
WHERE NOT r.is_cycle
GROUP BY p.name
ORDER BY hops, p.name;
It runs on stock Postgres, with no extension, using the person and follows tables from the Postgres graph guide. It is longer than the Cypher, and it needs no new infrastructure.
Apache AGE and recursive SQL compared
QuestionApache AGERecursive SQL on your tables
Query languageopenCypher inside cypher(), plus SQLSQL only
Where the data livesIn AGE graph tables, separate from your tablesIn the tables you already have
Extension neededYesNo
Managed host supportVaries by provider, so checkEverywhere Postgres runs
Long pattern matchesConciseVerbose
Short walks from a known rowConciseFine
Permissions you already wroteSeparate from your tablesRow level security applies as it is

The honest trade is this. AGE buys you a better language for graph patterns. The tables approach buys you no new moving parts and no copy of your data. If most of your graph questions are one to four hops from a known row, the second is usually enough. If they are long, branching patterns, the first earns its keep.

How Helm7 handles it

Helm7 takes the tables route. Its relationships switch does not use Apache AGE. It reads foreign keys from your Postgres catalogue, and walks them with one recursive query that uses the CYCLE clause. It keeps no second copy of your data.

For links that are not real columns, it adds two things in a schema inside your database. Virtual foreign keys describe a column that points at another table without a constraint. Labelled edges link any row to any other, for relationships such as "duplicate of" or "mentions". A traversal is capped at 4 hops, 50 neighbours per row per hop, 500 rows and a 5 second timeout, and it runs as your app's role, so row level security still applies.

database_edge_upsert
{ "productId": "prd_...", "databaseId": "DATABASE_ID",
  "from": { "table": "tickets", "pk": "881" },
  "to":   { "table": "tickets", "pk": "412" },
  "label": "duplicate_of" }

database_graph_traverse
{ "productId": "prd_...", "databaseId": "DATABASE_ID",
  "start": { "table": "tickets", "pk": "881" },
  "steps": [ { "via": "edge:duplicate_of", "dir": "both" } ] }
Link two rows with a labelled edge, then follow that edge in either direction. The via value names the relationship: edge:<label> for a labelled edge.

This is a good fit for apps that want to follow relationships they already store. It is not a drop-in replacement for Cypher. If you need Cypher, choose AGE on a host that supports it, or Neo4j. For search by meaning on top of the same tables, see semantic search with pgvector, and the databases page for every switch. Agent memory on Postgres shows both ideas used together.

Common questions

  • What is Apache AGE?

    A PostgreSQL extension, licensed under Apache 2.0, that adds graph storage and the openCypher query language. You run Cypher inside a cypher() function call in ordinary SQL, so graph and relational queries share one database.

  • Which Postgres versions does Apache AGE support?

    The project's README lists Postgres 11, 12, 13, 14, 15, 16, 17 and 18. Check which AGE release matches which Postgres version on your host.

  • Is Apache AGE available on managed Postgres?

    On some hosts. Microsoft documents it for Azure Database for PostgreSQL. The AWS RDS extension tables for versions 16 to 19 did not list it when checked on 16 November 2026. Look at your own provider's current list.

  • Can I do graph queries in Postgres without AGE?

    Yes. Rows are nodes and foreign keys are edges, and a WITH RECURSIVE query walks them. Add the CYCLE clause, available since PostgreSQL 14, to stop loops, and a depth limit to stop huge walks.

  • Does Helm7 use Apache AGE?

    No. Helm7's relationships switch reads your foreign keys, adds optional virtual foreign keys and labelled edges, and walks them with recursive SQL. It does not offer Cypher.

Run your entire app stack, end to end, from $12 a month.

App, Postgres, auth, storage, jobs and domains on one platform, planned and priced before anything changes.

More guides