AgensGraph Files

Highlights

• PostgreSQL 18.6 base. All PostgreSQL 18 features (asynchronous I/O, uuidv7(), virtual generated columns, OAuth authentication, skip scan for B-tree indexes) and every PostgreSQL security fix up to 18.6.
• GQL (ISO/IEC 39075) clauses: LET, FOR, FILTER, NEXT, FINISH, INSERT, and ORDER BY / OFFSET / LIMIT as standalone clauses.
• Subqueries: CALL { ... }, OPTIONAL CALL, EXISTS { }, COUNT { }, COLLECT { } / ARRAY { }, VALUE { } and x IN { }.
• Procedure calls: CALL func(args) YIELD ... for table-returning functions.
• Typed property columns: store chosen properties of a label in typed columns, with typed indexes.
• Faster graph queries: Upto 100x faster. Better row estimates for variable-length patterns, label pruning, skipped scans for unused pattern endpoints, and id-based comparison, grouping and counting of vertices and edges.
• Security: Cypher writes now enforce row-level security policies, and fixed-length patterns now apply the row-level security and privileges of labels they do not name.
• pg_dump: label constraints, label columns and Cypher views now dump and restore correctly.

New features

GQL and Cypher clauses

• LET x = expr. Add a variable and keep all existing ones. Can start a query. MATCH (p:person) LET next_age = p.age + 1 RETURN p.name, next_age
• FOR x IN <list> [WITH OFFSET [AS i]]. Expand a list into rows. FOR x IN [10, 20, 30] WITH OFFSET AS i RETURN x, i
• FILTER [WHERE] <condition>. Filter rows at any point.
• NEXT. Feed one query's result into the next: Q1 NEXT Q2. Set operations on either side, and WITH, FILTER, ORDER BY, OFFSET, LIMIT after NEXT.
• FINISH. Run a query for its side effects and return no rows.
• INSERT. GQL synonym for CREATE.
• ORDER BY, SKIP / OFFSET, LIMIT as standalone clauses. OFFSET is a synonym for SKIP. MATCH (p:person) ORDER BY p.age DESC LIMIT 1 RETURN p.name
• RETURN ALL, WITH ALL, and ALL in aggregates (count(ALL x)).
• CALL func(args) YIELD col [AS alias], ... | YIELD *. Call a table-returning function from Cypher. MATCH (p:person) CALL generate_series(1, 3) YIELD generate_series AS n RETURN p.name, n
• OPTIONAL CALL. Keep an input row with nulls when the call returns nothing.

Subqueries

• CALL { ... } with import lists CALL (x, y) { ... }, CALL () { ... }, CALL (*) { ... }.
• EXISTS { ... }, COUNT { ... }, COLLECT { ... } / ARRAY { ... }, VALUE { ... }. The body can be a pattern, a MATCH query or an SQL SELECT. MATCH (p:person) RETURN p.name, COUNT { MATCH (p)-[:knows]->() } AS out
• x [NOT] IN { <subquery> }.
• ORDER BY, SKIP and LIMIT inside read subqueries.

Expressions and functions

• XOR operator.
• exists(n.prop): true when the property is not null.
• NULLIF(a, b); IS [NOT] UNKNOWN.
• CURRENT_GRAPH, CURRENT_PROPERTY_GRAPH (SQL and Cypher). SQL value functions such as CURRENT_DATE and CURRENT_USER in Cypher.
• size() of a list, string or map; length() of a map.
• cardinality() for lists, maps and paths.
• toInteger(), toFloat(); casts to keyword type names: ::int, ::bigint, ::numeric(10,2), ::varchar, ::boolean.
• Unary - and + on properties: RETURN -n.score.
• Nodes, relationships and paths in list literals: [n, m].
• IN on vertices, edges and ids: v IN collect(u), id(u) IN [...].
• UNION / INTERSECT / EXCEPT of differently typed branches (RETURN true UNION RETURN 'x').
• ORDER BY can use a RETURN / WITH alias inside an expression: RETURN m.embedding AS e ORDER BY e <=> $1.

Typed property columns

Store chosen properties of a label in typed columns. The property map stays the source of the data, and the column is kept in step with it.

:::sql
CREATE VLABEL person (age int GENERATED, name text GENERATED);
CREATE PROPERTY INDEX ON person (age);       -- typed index on the column
ALTER VLABEL person ADD COLUMN score numeric GENERATED;

• Cypher reads use the typed column in WHERE, ORDER BY, GROUP BY, DISTINCT, aggregates, IN lists, map constraints and variable-length patterns, and can use its index.
• A write whose value does not fit the column type fails, and the error names the label.
• Works with label inheritance and ALTER VLABEL / ALTER ELABEL ... ADD | DROP COLUMN. Kept by pg_dump and pg_upgrade.
• New catalog ag_label_property. New setting enable_property_promotion (default on).
• Limits: no char(n) / varchar(n); no column collation.

Schema, tools and administration

• New setting enable_graph_ddl (default off): allows ALTER TABLE to reshape a label.
• A label owner who is not a superuser can add label constraints, and can restore a dump of their own graph.
• DROP INDEX drops a property index. CREATE INDEX ... ((properties.'k')) builds the same index as CREATE PROPERTY INDEX.
• \dGi lists property indexes on typed columns.
• graphid input supports soft errors: pg_input_is_valid() and COPY ... ON_ERROR work on graphid columns.
• pg_identify_object() returns the name of a graph.
• LICENSE (Apache 2.0) and NOTICE files added.

Performance

• Variable-length patterns
• Expand each hop through the edge label's start / end index instead of a full scan.
• Estimate result size from edge-label statistics, so joins above a traversal get a good plan.
• Look up vertices by id through the primary key index.
• Release memory per hop; build edge and vertex arrays only when the query reads them.
• Cache a traversal from a start node chosen by a constant.
• Pattern planning
• Skip scans for pattern endpoints the query never reads, e.g. the () in (a)-[r]->(). New setting enable_graph_endpoint_elision (default on).
• Test an unread labelled endpoint by an id range instead of a join.
• With auto_gather_graphmeta = on, scan only labels that an unlabelled node or edge can connect to (also for DELETE).
• Scan only the matching label for a constant id() filter.
• Run exists(pattern) and EXISTS { } as one semi-join instead of once per row.
• Skip uniqueness checks between relationships whose labels cannot overlap.
• Compute length(), nodes() and relationships() of a fixed-length path from the pattern.
• Vertices and edges
• Compare, order, group and count by id; ORDER BY n and a = b can use the id index.
• Sort aggregate results (ORDER BY count(*)) and RETURN aliases by native value. A vector index can supply the order for RETURN n.emb <=> $1 AS d ORDER BY d LIMIT k.
• Writes
• SET of many properties on a label with many child labels no longer slows planning exponentially (#790).
• DELETE builds only the elements it removes.

Bug fixes

Fixes for problems present in 2.17.0.

Crashes

• SET on an element from an OPTIONAL MATCH that did not match.
• Two write clauses joined by WITH where the first matches an edge pattern.
• Cypher CREATE / SET / MERGE on a label with a column added or dropped by ALTER TABLE (crash or corrupt value).
• SET ending a query when enable_multiple_update = off.
• SET on a row updated concurrently, on a label with a BEFORE UPDATE row trigger.
• An aggregate inside a list comprehension (#793); now an error.
• A pattern variable with the same name as a label column in scope.
• A property constraint on a variable-length relationship that refers to another variable; now an error.
• cardinality() or array_ndims() on a list.
• head(), last() and tail() on some lists.
• CREATE PROPERTY INDEX on a non-string subscript (tags[0]).
• SET p.x = exists((p)-[]->()); now an error.

Wrong results

• A SET that waited on a concurrent update overwrote it (lost update).
• A variable-length pattern under a hash join, hashed aggregate or LIMIT returned the first start vertex's result for every start vertex (#806).
• DETACH DELETE on a parent vertex label left edges of its child labels (with auto_gather_graphmeta = on).
• DETACH DELETE left edges written by SQL, COPY or replication (with auto_gather_graphmeta = on).
• toStringList(), toIntegerList(), toFloatList() read bigint / real elements wrongly and returned empty lists for one element.
• get_last_graph_write_stats() reported counts from an earlier statement after a write with RETURN.

More fixes that change results (comparison operators, min() / max(), list predicates, negative indices, write visibility, LIMIT after a write, DELETE ... RETURN) are listed in What changed from 2.17.

Errors on valid queries

• "attempted to update invisible tuple" when write clauses are chained through WITH.
• "aggregate must exist solely" for an aggregate inside an expression: round(avg(x), 1).
• collect(NULL) and collect('text') (#629).
• RETURN n.age AS a ORDER BY a * -1 and RETURN n AS m ORDER BY m.id (variable does not exist).
• RETURN -n.id (operator does not exist).
• ORDER BY / DISTINCT / GROUP BY on a cast property such as n.name::text (could not determine which collation to use).
• A write on the inner side of a nested loop (unrecognized node type).
• label() and property access on elements taken from collect().
• [n] list of nodes or relationships (graph object cannot be list element).
• A Cypher write in a read-only transaction reported cannot execute ???.

pg_dump, restore and upgrade

• A label's ordinary columns were left out of the dump, and the restore failed.
• A label's CHECK constraints (including ASSERT ... IS NOT NULL) were not dumped.
• A label's unique constraint was dumped without its name, so a restore renamed it.
• Exclusion constraints on labels made pg_dump fail or write wrong statements; \dGv failed on them.
• A view over a Cypher query did not restore (.'name'::text did not parse).
• A property index over a string subscript was dumped without quotes and restored as a different index.
• A non-superuser could not restore a dump of their own graph; label primary keys were lost.

Downloads

Item	Where
Binaries	agensgraph-v2.18.6.0-build.tar.gz (attached): x86-64 Linux, built on Rocky Linux 10 (glibc 2.38+), installs to /agensgraph-18 · SHA-256 9b9e4f429bda0ae21a4ddf3c516817463854374290310ddd3e6b96c5d840c01c
Source	Source code (tar.gz) / (zip) below, generated by GitHub from the v2.18.6.0 tag
Docker	skaiworldwide/agensgraph:v2.18.6.0-<variant>: bookworm, trixie, alpine3.23, alpine3.24, rocky9, rocky10
Python driver	agensgraph-python 2.0.0 (Python 3.11+)
AI integrations	agensgraph-ai
Documentation	Manual · Upgrading to 2.18 · GQL conformance

Before you upgrade

[!IMPORTANT] A 2.17 data directory does not start on 2.18. Upgrade with dump and reload, or with pg_upgrade (see Upgrading from 2.17). Some 2.17 queries now fail or return different results. Check your application before upgrading.

• What changed from 2.17: every change that can break a working 2.17 query.
• Check your application first: the checklist.
• Upgrading to 2.18: pg_upgrade and dump and reload, step by step.
• PostgreSQL 18 migration notes.

Upgrading from 2.17

[!WARNING] Dump with the 2.18.6.0 pg_dump / pg_dumpall, not the 2.17 one. The 2.17 pg_dump drops label CHECK constraints (ASSERT ... IS NOT NULL) and fails on columns named with the new reserved words.

• Route 1: pg_upgrade
• Route 2: dump and reload
• After the upgrade
• A worked example: a real pg_upgrade run, step by step.

Contributors

• @MuhammadTahaNaveed
• @skjeong-afk

Thanks to the people who reported issues fixed in this release: @ljhhuxiaoba, @w158937299, @kadinwu, @zihaozeng0021, @choeoe.

Full changelog: v2.17.0...v2.18.6.0