agentsclimarketplace

Apache age

Skill synapseradio/ai-skills/skills/tech/apache-age

Apache AGE graph database extension for PostgreSQL — Cypher query syntax, agtype data types, hybrid SQL+Cypher patterns (CTEs, JOINs, parameter passing), graph schema modeling (vertices, edges, labels, properties), and performance optimization (indexing, EXPLAIN, batch loading). Use when writing Cypher queries, designing graph schemas, combining graph traversal with relational SQL, or optimizing AGE query performance — all within PostgreSQL via the AGE extension.From its SKILL.md

Install
npx -y skills add synapseradio/ai-skills --skill apache-age

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.1 KB, as published. Nobody here has run it

Apache AGE

Quick Start

CREATE EXTENSION IF NOT EXISTS age;
LOAD 'age';
SET search_path = ag_catalog, "$user", public;
SELECT create_graph('my_graph');

SELECT * FROM cypher('my_graph', $$
  CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})
  RETURN a, b
$$) AS (a agtype, b agtype);

Reference Loading

PrincipleReferenceWhen to Load
The Wrapper Contractthe-wrapper-contract.mdMANDATORY for first-time AGE users. Load for cypher() mechanics, search_path, parameters, unsupported features
agtype Is Everythingagtype-is-everything.mdLoad when casting agtype to SQL types, debugging type errors, or handling nulls
Hybrid Is the Pointhybrid-is-the-point.mdMANDATORY before writing any SQL+Cypher query. CTEs, JOINs, mutation guards, multi-graph
Schema Is Storageschema-is-storage.mdLoad when designing graph schema, choosing labels/properties, or modeling relationships
Nothing Is Automaticnothing-is-automatic.mdMANDATORY before performance work. Indexes, EXPLAIN, batch loading, when to use SQL instead

Do NOT load:

  • schema-is-storage.md for pure query questions (no schema design involved)
  • nothing-is-automatic.md for schema design unless indexing is the concern
  • the-wrapper-contract.md for users already familiar with cypher() mechanics

Freedom calibration:

  • Low freedom (follow exactly): cypher() wrapper syntax, AS column lists, search_path, index DDL, mutation CTE guards
  • Medium freedom (adapt to context): graph modeling, hybrid query composition, performance tuning
  • High freedom (choose freely): property naming, schema partitioning, application-layer validation

Think in AGE

  • Every Cypher query is a SQL function call — plan the SQL wrapper first, then the Cypher inside it
  • agtype is the only type that crosses the boundary — cast explicitly at every SQL touchpoint
  • Graphs are PostgreSQL schemas — labels are tables, vertices and edges are rows with agtype property blobs
  • Nothing exists until you create it — no default indexes, no property constraints, no type enforcement
  • Hybrid is the value proposition — when a query is pure aggregation or pure OLTP, drop to SQL (it's ~15x faster for aggregation per Issue #2194)

Critical Gotchas

1. Always define a column list

cypher() returns SETOF record — PostgreSQL requires an explicit column list:

SELECT * FROM cypher('g', $$ MATCH (n) RETURN n $$) AS (n agtype);

2. Terminal clauses need a dummy column

CREATE, SET, DELETE at the end of a query return no rows, but the column list is still mandatory:

SELECT * FROM cypher('g', $$
  CREATE (:Person {name: 'Alice'})
$$) AS (v agtype);
-- Returns 0 rows

3. SET = replaces all properties; use += to merge

-- Replaces ALL properties with just {age: 30}
SET n = {age: 30}

-- Merges {age: 30} into existing properties
SET n += {age: 30}

4. CREATE/SET/REMOVE not allowed in JOINs

Mutations inside a JOIN cause errors. Wrap in a CTE instead:

WITH new_vertex AS (
  SELECT * FROM cypher('g', $$ CREATE (p:Person {name: 'Alice'}) RETURN p $$) AS (v agtype)
)
SELECT * FROM new_vertex;

5. search_path must include ag_catalog

SET search_path = ag_catalog, "$user", public;
-- Or fully qualify: SELECT * FROM ag_catalog.cypher(...)

NEVER

  • NEVER omit the AS column list — cypher() returns SETOF record, PostgreSQL demands it
  • NEVER use SET n = {...} when you mean SET n += {...} — = replaces ALL properties silently
  • NEVER put CREATE/SET/REMOVE inside a JOIN — wrap in CTE; mutations break PostgreSQL transaction handling
  • NEVER use unbounded [:REL*] — paths explode at scale (7s → 7min on 1.5M vertices, Issue #195)
  • NEVER assume indexes exist — AGE creates none by default; use EXPLAIN inside Cypher to verify
  • NEVER compare agtype to SQL types without casting — agtype can only cast to varchar among string types (not json/text, Issues #1225, #1996)
  • NEVER query without a label — scans entire _ag_label_vertex parent table
  • NEVER use multiple labels on one vertex — AGE supports exactly zero or one (by design, Discussion #109)
  • NEVER build maps with 50+ fields — agtype_build_map() hits the 100-argument PostgreSQL function limit (Issue #1840)
  • NEVER pass null to agtype functions without checking — some null inputs crash the server (Issues #1956, #1303)

Common Recipes

1-hop neighbors with SQL JOIN

SELECT u.email, friend.name::varchar AS friend_name
FROM users u
JOIN (
  SELECT * FROM cypher('social', $$
    MATCH (p:Person)-[:KNOWS]->(f:Person)
    WHERE p.userId = 1042
    RETURN p.userId, f.name
  $$) AS (user_id agtype, name agtype)
) g ON u.id = g.user_id::int;

MERGE upsert

SELECT * FROM cypher('g', $$
  MERGE (p:Person {email: '[email protected]'})
  ON CREATE SET p.created_at = timestamp(), p.login_count = 1
  ON MATCH SET p.login_count = p.login_count + 1
  RETURN p
$$) AS (p agtype);

UNWIND bulk create

SELECT * FROM cypher('g', $$
  UNWIND [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}] AS attrs
  CREATE (p:Person {name: attrs.name, age: attrs.age})
  RETURN p.name
$$) AS (name agtype);

Bounded path search

SELECT * FROM cypher('g', $$
  MATCH (a:Person {name: 'Alice'})-[:KNOWS*1..3]->(b:Person)
  RETURN DISTINCT b.name
  LIMIT 100
$$) AS (name agtype);

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.