Skip to content

Graph Modeling

Once your data sources are connected, the next step is to model your data as a graph: defining how tables become nodes and edges, and where each graph element draws its rows from.

PuppyGraph follows the labeled property graph model. A graph consists of:

  • Nodes (also called vertices), the typed entities such as Person or Software.
  • Edges, the typed, directional relationships between nodes, such as Person -[:KNOWS]-> Person.
  • Properties, the key-value attributes attached to nodes and edges.

A PuppyGraph schema is a single JSON document that maps your tables onto this model. You can author it through the Schema Builder on the Graph page of the Web UI, let PuppyGraph AI inspect your connected tables and propose the graph for you, or upload a schema.json file directly. Once active, the schema can be edited in place from the UI without re-uploading.

Anatomy of a schema

A schema has up to five top-level sections:

Section Purpose
catalog[] Connections to external data sources. Per-source configuration is documented in Connecting.
node[] Node types. See Building a Graph.
edge[] Edge types. See Building a Graph.
localTable[] Locally cached tables. Optional. See Data Sources and Local Tables.
rowLevelSecurity Per-user query filters. Optional. See Row-Level Security.

A minimal schema with one catalog, one node type, and one edge type:

{
  "catalog": [
    {
      "name": "postgres_data",
      "type": "postgresql",
      "jdbc": {
        "username": "user",
        "password": "pass",
        "jdbcUri": "jdbc:postgresql://host:5432/postgres"
      }
    }
  ],
  "node": [
    {
      "label": "Person",
      "dataSourceGroup": {
        "externalDataSource": {
          "enabled": true,
          "catalog": "postgres_data",
          "schema": "modern",
          "table": "person"
        }
      },
      "id": [{ "name": "id", "type": "STRING" }],
      "attribute": [
        { "name": "name", "type": "STRING" },
        { "name": "age",  "type": "INT" }
      ]
    }
  ],
  "edge": [
    {
      "label":         "KNOWS",
      "fromNodeLabel": "Person",
      "toNodeLabel":   "Person",
      "dataSourceGroup": {
        "externalDataSource": {
          "enabled": true,
          "catalog": "postgres_data",
          "schema": "modern",
          "table": "knows"
        }
      },
      "id":        [{ "name": "id",      "type": "STRING" }],
      "fromKey":   [{ "name": "from_id", "type": "STRING" }],
      "toKey":     [{ "name": "to_id",   "type": "STRING" }],
      "attribute": [{ "name": "weight",  "type": "DOUBLE" }]
    }
  ]
}

What's in this section

  • Building a Graph, mapping tables to nodes and edges, identifiers and keys, the Schema Builder UI, and modeling denormalized tables.
  • Data Sources and Local Tables, where the rows behind a node or edge come from: external catalogs, locally cached tables, or unions.
  • Managing the Graph, inspecting and modifying the active schema in the Web UI, importing or exporting it as JSON, and managing local tables.
  • Migrating from v0, for users coming from PuppyGraph 0.x.

Two schema features are documented outside this section:

To have PuppyGraph design the graph for you instead of modeling it by hand, see PuppyGraph AI and the Building a Graph with PuppyGraph AI tutorial.

Next step

Once a schema is active, the graph is queryable. Continue to Querying for Cypher and Gremlin, Query UI to run queries in the browser, or PuppyGraph AI to ask questions in natural language.