Apache AGE Documentation

repository·master·Indexed 26 days ago

https://github.com/apache/age

Apache AGE is a multi-model graph database extension for PostgreSQL that enables the use of both relational SQL and the openCypher graph query language within a single storage engine. It supports PostgreSQL versions 11 through 18 and provides drivers for Golang, Java (JDBC), Node.js, and Python, including integration with NetworkX for graph conversion.

Tokens
9.3K
Snippets
35
Records
60
Agent score
86%

What's inside Apache AGE

  1. Use Agtype in Java with JDBC

    master

    To work with Apache AGE graph data in Java, you must register the agtype data type with your PgConnection. This allows you to map AGE-specific types to the org.apache.age.jdbc.base.Agtype class.

    Steps to integrate:

    1. Connect to PostgreSQL using the standard JDBC driver.
    2. Unwrap the connection to a PgConnection object.
    3. Call connection.addDataType("agtype", Agtype.class).
    4. Configure the AGE extension by executing CREATE EXTENSION IF NOT EXISTS age;, LOAD 'age', and setting the search_path to ag_catalog, "$user", public;.
    5. Execute Cypher queries using the cypher() function and cast results to agtype.
    6. Retrieve results using rs.getObject(index, Agtype.class).
    import org.apache.age.jdbc.base.Agtype;
    import org.postgresql.jdbc.PgConnection;
    
    import java.sql.*;
    
    public class Sample {
        static final String DB_URL = "jdbc:postgresql://localhost:5432/demo";
        static final String USER = "postgres";
        static final String PASS = "pass";
    
        public static void main(String[] args) {
    
            // Open a connection
            try {
    
                PgConnection connection = DriverManager.getConnection(DB_URL, USER, PASS).unwrap(PgConnection.class);
                connection.addDataType("agtype", Agtype.class);
    
                // configure AGE
                Statement stmt = connection.createStatement();
                stmt.execute("CREATE EXTENSION IF NOT EXISTS age;");
                stmt.execute("LOAD 'age'");
                stmt.execute("SET search_path = ag_catalog, \"$user\", public;");
    
                // Run cypher
                ResultSet rs = stmt.executeQuery("SELECT * from cypher('demo_graph', $$ MATCH (n) RETURN n $$) as (n agtype);");
    
                while (rs.next()) {
    
                    // Returning Result as Agtype
                    Agtype returnedAgtype = rs.getObject(1, Agtype.class);
    
                    String nodeLabel = returnedAgtype.getMap().getObject("label").toString();
                    String nodeProp =  returnedAgtype.getMap().getObject("properties").toString();
    
                    System.out.println("Vertex : " + nodeLabel + ", \tProps : " + nodeProp);
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
  2. Install the Apache AGE Python driver

    master

    To install the Apache AGE Python driver, ensure you have Python 3.9 or higher and the necessary system dependencies installed. You can install the required Python packages via pip from the driver directory.

    # Install system dependencies
    sudo apt-get update
    sudo apt-get install python3-dev libpq-dev
    
    # Clone and enter the driver directory
    git clone https://github.com/apache/age.git
    cd age/drivers/python
    
    # Install required Python packages
    pip install -r requirements.txt
    
    # Or build from source
    pip install .
  3. Post-Installation: Load the AGE extension

    master

    For every new connection to AGE, you must load the extension and set the search path to include ag_catalog.

    CREATE EXTENSION age;
    LOAD 'age';
    SET search_path = ag_catalog, "$user", public;
  4. Configure Apache AGE in PostgreSQL

    master

    Before using the Golang driver, ensure the Apache AGE extension is loaded and configured in your PostgreSQL instance by running the following SQL commands:

    CREATE EXTENSION age;
    LOAD 'age';
    SET search_path = ag_catalog, "$user", public;
    CREATE EXTENSION age;
    LOAD 'age';
    SET search_path = ag_catalog, "$user", public;
  5. Install AGE pre-requisite libraries

    master

    Before building Apache AGE from source, install the following essential libraries based on your operating system:

    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
  6. Install the Apache AGE Golang driver

    master

    You can install the driver using go get or by building from source.

    Using Go get:

    go get github.com/apache/age/drivers/golang

    Using Go modules: Add the following to your go.mod file (replace {version} with the latest version):

    require github.com/apache/age/drivers/golang {version}

    Building from source: On Linux or OSX:

    cd age/drivers/golang
    ./install.sh

    On Windows: Run install.bat in the driver directory.

    Prerequisites:

    • Java 11 or greater
    • Go 1.18 or greater
    • ANTLR 4.11.1 or greater
    • The module relies on the standard database/sql API and antlr4-python3.
    go get github.com/apache/age/drivers/golang
  7. Install Apache AGE from source

    master

    To install Apache AGE on Linux or MacOS, follow these steps:

    1. Clone the repository or download an official release.
    2. Verify your PostgreSQL version using pg_config. AGE supports PostgreSQL versions 11, 12, 13, 14, 15, 16, 17, and 18.
    3. Run make install in the source directory.

    If pg_config is not in your PATH, specify the path manually.

    pg_config
    make install
    # Or if pg_config is not in PATH:
    make PG_CONFIG=/path/to/postgres/bin/pg_config install
  8. Build the AGE JDBC driver from source

    master

    To build the AGE AGType parser and driver for Java, you need the gradle build tool, the postgres JDBC driver, antlr4-4.9.2-complete, common-lang3, and commons-text-1.6. Ensure any JAR files are unzipped before use.

    After a successful build, the resulting JAR file is located at age/drivers/jdbc/lib/build/libs/lib.jar. Add this JAR to your Java project's classpath.

    git clone https://github.com/apache/age.git
    cd age/drivers/jdbc
    
    gradle assemble
  9. Initialize nodejs-pg-age with a PostgreSQL client

    master

    To use Apache AGE types in a Node.js application using the pg driver, you must initialize the connection by calling setAGETypes(client, types) immediately after connecting. This enables the driver to correctly parse and handle agtype data returned from AGE queries.

    import {types, Client, QueryResultRow} from "pg";
    import {setAGETypes} from "../src";
    
    const config = {
        user: 'postgres',
        host: '127.0.0.1',
        database: 'postgres',
        password: 'postgres',
        port: 25432,
    }
    
    const client = new Client(config);
    await client.connect();
    // Crucial: Initialize AGE types on the connection
    await setAGETypes(client, types);
    
    await client.query(`SELECT create_graph('age-first-time');`);
  10. Use Apache AGE Golang driver for Cypher and Graph data

    master

    The driver provides two primary ways to interact with Apache AGE:

    1. Standard database/sql API: Use the ExecCypher function to execute Cypher queries directly through a 3rd party SQL driver.
    2. AGE Wrapper: Use the specialized Age Wrapper for graph operations.

    Refer to the following sample files for implementation details:

    • samples/sql_api_sample.go for ExecCypher usage.
    • samples/age_wrapper_sample.go for Age Wrapper usage.
    • samples/main.go to run the provided samples.
  11. Run Apache AGE using Docker

    master

    You can quickly run Apache AGE using Docker by pulling the official image and running a container.

    docker pull apache/age
    
    docker run \
        --name age  \
        -p 5455:5432 \
        -e POSTGRES_USER=postgresUser \
        -e POSTGRES_PASSWORD=postgresPW \
        -e POSTGRES_DB=postgresDB \
        -d \
        apache/age
    
    # To enter the PostgreSQL psql interface:
    docker exec -it age psql -d postgresDB -U postgresUser