DOCSEARCHbyAlgolia
Submit Docs

Apache-Age Viewer Documentation

repository·main·Indexed 18 days ago

https://github.com/apache/age-viewer

A web-based user interface for visualizing graph data stored in a PostgreSQL database with the Apache AGE extension. Includes guides for development and production deployment using Node.js and pm2, Docker setup for PostgreSQL with Apache AGE, and details on the RESTful API (/api/v1/) and Cytoscape.js integration for rendering Cypher query results.

Tokens
2.6K
Snippets
9
Records
13
Agent score
64%

What's inside Apache-Age Viewer

  1. Set up PostgreSQL with Apache AGE using Docker

    main

    Apache-Age Viewer requires a running PostgreSQL database server with the Apache AGE extension. The easiest way to set this up is using Docker.

    1. Pull the official image: docker pull apache/age

    2. Run the container with the following configuration: docker run --name myPostgresDb -p 5455:5432 -e POSTGRES_USER=postgresUser -e POSTGRES_PASSWORD=postgresPW -e POSTGRES_DB=postgresDB -d apache/age

    3. After starting the container, follow the Apache AGE Post-Installation instructions to create a graph in the database.

    Docker Flags Used:

    • --name: Assigns a name to the container (e.g., myPostgresDb).
    • -p: Publishes the container's port to the host (mapping host 5455 to container 5432).
    • -e: Sets environment variables for POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB.
    docker pull apache/age

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

  2. Install and run Apache-Age Viewer for development

    main

    Apache-Age Viewer requires Node.js version ^14.16.0. To set up a development environment, install the required node modules and start the application.

    By default, the application starts on http://localhost:3000 if port 3000 is available.

    # Install required node modules
npm run setup

# Run Age-Viewer
npm run start

  3. Build and run Apache-Age Viewer in production mode

    main

    To deploy Apache-Age Viewer in production, you must build both the front-end and back-end components and use pm2 for process management.

    First, ensure pm2 is installed globally:

    npm i pm2

    Then, follow these steps to build and restart the production service using the provided ecosystem.config.js.

    # Build the front-end
npm run build-front

# Build the back-end
npm run build-back

# Restart the project in production mode using pm2
pm2 stop ag-viewer-develop
pm2 delete ag-viewer-develop
pm2 start ecosystem.config.js

  4. Access the PostgreSQL shell in the AGE Docker container

    main

    You can access the PostgreSQL shell to manage your AGE database using one of two methods:

    Method 1: Via Docker Exec First, enter the container's bash shell, then run psql:

    docker exec -it myPostgresDb bash
psql -U postgresUser postgresDB

    Method 2: Direct Access from Host Access the shell directly from your host machine by specifying the port and host:

    psql -U postgresUser -d postgresDB -p 5455 -h localhost

    (You will be prompted for the password set during container creation.)

    # Method 1
docker exec -it myPostgresDb bash
psql -U postgresUser postgresDB

# Method 2
psql -U postgresUser -d postgresDB -p 5455 -h localhost

  6. Configure frontend application settings

    main

    The setting object in frontend/src/conf/config.js defines the application's runtime behavior and UI preferences. You can modify these keys to control theme selection, data limits for graphs and tables, and connection handling behavior.

    export const setting = {
  theme: 'default',
  maxNumOfFrames: 0,
  maxNumOfHistories: 0,
  maxDataOfGraph: 0,
  maxDataOfTable: 0,
  connectionStatusSkip: false,
  closeWhenDisconnect: false,
};

  7. Configure PM2 deployment for Age-Viewer

    main

    The ecosystem.config.js file defines the PM2 configuration for running the ag-viewer application. It supports two primary environments: a development environment (env) and a release environment (env_release).

    Environment Variables

    VariableDescription
    PORTThe port number the backend server will listen on.
    NODE_ENVThe current Node.js environment (develop or release).
    nameThe name assigned to the process in PM2.

    Deployment Script

    When deploying to a staging environment, the following sequence is executed:

    1. npm install
    2. npm run setup
    3. npm run build-front
    4. pm2 reload ecosystem.config.js
    module.exports = {
    apps: [{
        name: "ag-viewer",
        namespace: "ag-viewer",
        script: "cd backend && node ./build/bin/www",
        watch: false,
        env: {
            name: "ag-viewer-develop",
            PORT: 3001,
            NODE_ENV: "develop",
        },
        env_release: {
            name: "ag-viewer-release",
            PORT: 4000,
            NODE_ENV: "release",
        }
    }],
    deploy: {
        staging: {
            'post-deploy': 'npm install && npm run setup && npm run build-front && pm2 reload ecosystem.config.js'
        }
    }
}

  8. Connect Apache Age-Viewer to a PostgreSQL database

    main

    To use the Age-Viewer UI, you must provide connection details for your PostgreSQL server. If you used the Docker setup described in the guides, use the following credentials:

    FieldValue
    Connect URLlocalhost
    Connect Port5455
    Database NamepostgresDB
    User NamepostgresUser
    PasswordpostgresPW

  9. Update visual properties for Cypher labels

    main

    The CypherUtil provides several functions to programmatically update the visual styling (colors, sizes, and captions) of graph elements based on their labels. These changes affect how elements are rendered in the Cytoscape view.

    Update Color

    updateLabelColor(labelType, labelName, newLabelColor)

    • labelType: 'node' or 'edge'.
    • labelName: The string name of the label.
    • newLabelColor: An object containing { color, borderColor, fontColor }.

    Update Size

    • updateNodeLabelSize(labelName, newLabelSize): Sets the visual size for a node label.
    • updateEdgeLabelSize(labelName, newLabelSize): Sets the visual size for an edge label.

    Update Caption

    updateLabelCaption(labelType, labelName, newLabelCaption)

    • labelType: 'node' or 'edge'.
    • labelName: The string name of the label.
    • newLabelCaption: The string to be used as the caption (e.g., 'name', 'id', or 'gid').

  10. Generate Cytoscape elements from Cypher query results

    main

    Use generateCytoscapeElement to transform raw Cypher query result data into a format compatible with Cytoscape.js. This function handles the mapping of nodes and edges, assigns visual properties (colors, sizes, captions) based on labels, and generates a legend for the graph.

    Parameters:

    • data: The raw query result object where keys are aliases and values are node/edge/path objects.
    • maxDataOfGraph: An integer limiting the number of elements processed (use 0 for no limit).
    • isNew: A boolean; if true, new elements are assigned the CSS class 'new node'.
    import { generateCytoscapeElement } from './CypherUtil';

const results = {
  p: { label: 'Person', id: '1', properties: { name: 'Alice' } }
};

const { legend, elements } = generateCytoscapeElement(results, 0, false);

  11. Backend API Route Structure

    main

    The ag-viewer-backend provides a RESTful API under the /api/v1/ prefix. The backend is organized into several functional routers that handle different aspects of the application:

    • /api/v1/*: Managed by sessionRouter for session-related operations.
    • /api/v1/miscellaneous: Managed by miscellaneousRouter for general utility endpoints.
    • /api/v1/cypher: Managed by cypherRouter for executing Cypher queries against the AGE extension.
    • /api/v1/db: Managed by databaseRouter for database connection and management operations.

  12. Generate Cytoscape metadata elements

    main

    Use generateCytoscapeMetadataElement to transform metadata (such as label statistics) into Cytoscape elements. This is typically used for visualizing the schema or label distribution rather than specific graph instances.

    Parameters:

    • data: An array of objects containing metadata fields like la_name, la_count, la_oid, and optionally la_start/la_end to distinguish between node and edge metadata.
    import { generateCytoscapeMetadataElement } from './CypherUtil';

const metadata = [
  { la_name: 'Person', la_count: 10, la_oid: 123 }
];

const { legend, elements } = generateCytoscapeMetadataElement(metadata);